Migrating From Classic

Concept mapping

The IAM namespace is events for both services, so a policy statement looks similar while naming a different API. The CLI command and SDK client name distinguishes them: events for classic, eventbridgev2 for the new buses.

Four new-bus concepts with no classic analogue

• Retention on the bus itself. In classic, an event not matched at publish time is gone. The new bus keeps it for the retention period, which is what makes the next three possible.
• Starting position. A subscriber on the new bus can begin at the tip, at the oldest retained event, or at a timestamp. A classic rule only ever sees what arrives after it exists.
• Pause and resume. A stopped subscriber accrues a backlog and can resume from it, either delivering the backlog or skipping it. Disabling a classic rule discards everything published while it was disabled.
• Two publish APIs with different payload models. This changes how you write filters, transformers, and target parameters. A classic event pattern ported unchanged to a DATA filter works only for PutEvents traffic, because only PutEvents keeps the classic envelope. See chapter 6 and filters-and-expressions.md.

Habits that carry over incorrectly

• One rule with many targets becomes many subscribers. A subscriber has exactly one target, so a classic rule fanning out to three targets is three subscribers on the same bus. Each is billed a delivery.
• A classic archive plus replay becomes retention plus a starting position. There is no replay API to call. See replay-and-recovery.md.
• A dead-letter queue moves from the target to the subscriber. It is OnFailureConfiguration on the subscriber, it must be SQS, and the delivery role needs sqs:SendMessage on it (chapter 13).

A migration sequence that is reversible at every step

The risk in a migration is not the concept mapping; it is a one-shot cutover. The sequence below runs classic and the new bus side by side, moves one party at a time, and keeps a rollback at every step. Retention is what makes it safe: with events retained on the new bus, a consumer cutover that goes wrong is replayed with a POINT_IN_TIME subscriber rather than lost.

Step 0: decide whether to migrate at all. Classic EventBridge remains a supported service. Migrate to get what classic does not have: retention, replay, pause and resume, ordering, deduplication, and binary payloads. If none of those matter to the workload, staying on classic is a valid outcome of this step.

Step 1: bridge classic into the new bus, changing nothing else. Create the new bus, then add a non-managed classic rule on the existing classic bus whose target is the new bus, carrying a role you supply. Both systems now carry the same traffic, and every later step works against live data. Two authorization facts govern the bridge: the forwarding is authorized per event against the new bus’s resource policy, and a stream mixing AWS service events with your own needs both events:PutEvents and events:PutRawEvents granted (see authorization.md). Rollback: delete the rule.

Step 2: confirm consumer idempotency before anything is dual-delivered. During a consumer’s cutover, and during any later replay, a consumer can see the same logical event twice: once through its classic target and once through its new subscriber. You SHOULD confirm each consumer deduplicates on a business key from the payload before moving it. A consumer that cannot be made idempotent needs a hard cutover (stop classic delivery, then start the subscriber) instead of a shadow period, so identify those consumers now.

Step 3: move consumers one team at a time, shadow first. For each consumer: create a subscriber on the new bus with the filter that matches its classic rule pattern (ported per the payload-shape rules above), point it at a shadow target the team owns, and compare shadow output against the classic delivery until the team trusts it. Then cut over: point the subscriber at the real target and disable the classic rule’s target. Rollback: re-enable the classic target and pause the subscriber (State: STOPPED); the classic path never stopped carrying the traffic. If a cutover gap is discovered later, create a replacement subscriber with StartingPosition: POINT_IN_TIME and a TIMESTAMP from before the cutover, and the gap is refilled from retention (see replay-and-recovery.md).

Step 4: move publishers last, which removes the bridge. Once every consumer reads from the new bus, repoint each publisher from the classic PutEvents call to the new bus. The lift-and-shift is small: swap the client (for the AWS SDK for Java v2, EventBridgeClient becomes EventBridgeV2Client), name the bus by ARN at the request level instead of EventBusName per entry, and keep Source, DetailType, and Detail unchanged. Update the caller’s IAM policy to cover the event-busv2/ resource ARN. When the last publisher moves, the bridge rule carries nothing; delete it. Rollback per publisher: repoint it at classic, where the bridge still forwards.

Step 5: decommission. Delete the classic rules and targets, and any classic archive whose job the new bus’s retention now does. You MUST do this only after the retention period has covered at least one full business cycle of replay demand, because a classic archive deleted early is the one thing in this sequence with no rollback.