HA Redis Cluster Migrations

Deploy the fleet first using Deploy Eden with high availability. That guide covers the matched HA image/chart, licensing, external databases, per-pod identity Secrets, networking and readiness checks. The first customer HA release uses five validators, four required for control changes, and one traffic primary at StatefulSet ordinal zero. Run the ordinary migration workflow on that primary, using the release-matched Professional or Enterprise HA image, online license and paired HA deployment context.

Recovery fences the old primary before recreating the same ordinal with its retained UUID, keys, license custody and PVC. A crash-interrupted attempt stays fenced and may require source-route restoration, explicit target reconciliation and a fresh migration operation. There is no automatic lane takeover, promotion to a different logical owner or promise that an interrupted copy resumes. See recovery.

Advanced distributed lane model — outside this release

The remainder of this page describes the distributed lane protocol and its implementation constraints. Commercial images currently refuse new /ha/plan activation. These API examples are not installation or failover instructions for the first retained-identity active-passive release.

HA Redis migrations let multiple Eden Service nodes coordinate one live Redis Cluster migration while each node keeps its assigned traffic lanes local and fast. Use this mode when a Redis or Valkey migration has enough nodes, traffic, or availability risk that a single Eden worker should not own the whole run.

Mental Model

Each Redis source node maps to one migration lane. A lane records its source endpoint, target endpoint, role, traffic profile, active Eden owner, standby owners, checkpoint, replay watermark, and validation digest.

The hot request path stays lane-local. Eden does not consensus-order every Redis command. HA coordination only controls lane ownership, stage movement, validation barriers, and cutover decisions.

Deployment Shape

The advanced model assumes the following topology; these are not additional qualified customer profiles:

• 3, 5, or 7 Eden Service pods;
• external Postgres;
• external ClickHouse for analytics;
• active-active HA enabled;
• persistent Eden state per pod;
• Blossom/cache-sync identity Secrets provisioned before startup; and
• one immutable Eden image digest across the fleet.

The migration participant contract admits 3, 5 or 7 participants. These are configuration constraints, not completed live scale/failover qualification. Review Redis support and evidence for the evidence boundary. Larger participant sets are outside this deployment contract.

The migration stage rule is intentionally conservative: every configured Eden participant must confirm the same stage and state digest before Eden moves to the next forward stage.

Shared Postgres Authority

The shared Postgres deployment stores Eden domain tables, DBOS workflow tables, and the HA migration plan checkpoint. That does not make DBOS the HA stage authority.

When an HA migration plan exists:

• the HA plan owns lane ownership, lease epochs, checkpoints, validation

digests, stage barriers, and cutover commitment;

• DBOS owns durable workflow retries, sleeps, and restart recovery;
• DBOS may drive the workflow and call the HA APIs;
• DBOS must not mark the migration successful until the HA plan reaches

cutover_committed.

This gives operators one shared database without creating two competing stage machines.

Stage Flow

Forward stages are ordered:

created
  -> historical_copy
  -> live_capture
  -> dual_write
  -> catchup
  -> validate
  -> cutover_ready
  -> cutover_committed

Eden blocks stage movement until all required lane barriers and all participant confirmations pass.

Rollback is available before cutover commit. After cutover commit, reversal is a separate compensating operation.

API Sequence

All paths are relative to /api/v1/migrations/{migration_id}.

Example lane plan request:

{
  "expected_revision": 0,
  "deployment_uuid": "22222222-2222-4222-8222-222222222222",
  "participant_eden_uuids": [
    "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
    "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
    "cccccccc-cccc-4ccc-8ccc-cccccccccccc"
  ],
  "lanes": [
    {
      "lane_id": "redis:primary:000",
      "source_endpoint_uuid": "11111111-1111-4111-8111-111111111111",
      "target_endpoint_uuid": "33333333-3333-4333-8333-333333333333",
      "role": "primary",
      "traffic_profile": {
        "read_percent": 90,
        "write_percent": 10,
        "average_ops_per_sec": 40000,
        "peak_ops_per_sec": 80000
      },
      "standby_eden_uuids": [
        "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
        "cccccccc-cccc-4ccc-8ccc-cccccccccccc"
      ]
    }
  ]
}

As a topology-modeling example, a Redis Cluster with 36 primaries and 36 replicas has 72 lanes. This is not a scale qualification result. Use the observed production traffic profile for each lane; a common starting point is 90/10 for primaries and 100/0 for read replicas.

Failure Behavior

Losing a node closes its client sessions. The lane ownership and checkpoint formats fence stale owners, but lease expiry alone does not prove predecessor quiescence or reconcile uncertain target writes. Different-identity lane takeover and automatic migration continuation remain outside the released active-passive profile.

Stage movement waits for every configured participant to confirm the same state. This is what prevents one node from cutting over while another node is behind or seeing different lane evidence.

Operator Caveat

Use production-active-passive-values.yaml, nodeUuidFromPodUid: false, five retained per-ordinal UUIDs and OnDelete replacement. Keep the primary's exact identity and state during recovery. Changing a pod UID must not change its Eden identity. Installed advanced plans still have a fixed participant set; a new node UUID is not a transparent replacement for an old participant. The customer's fencing, storage and scheduling configuration determines downtime.

Related Docs

• Migration API Reference
• Migration API Stage Map
• Operating Live Migrations
• Validation Runs And Observability