Setup Walkthroughs

Single account: bus, subscriber, delivered event, teardown

Prerequisites

• The service must be available in your region; aws eventbridgev2 list-event-buses failing to resolve an endpoint means it is not.
• Your caller MUST have the events: actions used below (chapter 14; the namespace is events:, never eventbridgev2:), plus sqs:CreateQueue, iam:CreateRole, iam:PutRolePolicy, and iam:PassRole for the delivery role.

1. Create the target queue and the dead-letter queue

The targets exist before anything references them:

2. Create the delivery role

The role trusts the events.amazonaws.com service principal and MUST be able to write both queues. Granting the target but not the dead-letter queue turns every delivery failure into silent loss (chapter 13):

3. Create the bus and wait for ACTIVE

4. Create the subscriber

Filter, target, delivery role, and dead-letter queue in one call; the exact shape is the first sample in code-samples.md:

5. Allow the activation delay, then publish a test event

A subscriber published to immediately after creation can miss the first event, so you SHOULD allow a short delay (see provisioning-and-state.md). Then publish something the filter matches:

6. Confirm arrival at the target

You SHOULD read the queue and delete what you read, or counts lie to you (delivery-troubleshooting.md):

If nothing arrives promptly, something is wrong; you SHOULD work the ordered procedure in delivery-troubleshooting.md rather than waiting longer.

7. Teardown, in reverse order of creation

The bus rejects deletion while any subscriber or event source still exists (chapter 15), so you MUST delete the subscriber before the bus. The delivery role’s policy names the queue ARNs, so the role goes before the queues to keep the teardown a strict reverse of the creation order.

Multiple accounts: a central bus shared through AWS RAM

The platform account owns the bus. Each consumer account owns its own subscriber, delivery role, and target. Subscribers cannot be created centrally: the delivery role must belong to the account that creates the subscriber, and a target in another account is rejected at create, because the target ARN’s account is checked there. So the platform team shares the bus, and every consumer builds its own consumer side.

Prerequisites

• Decide the sharing mechanism. AWS RAM is the recommended path (security-and-sharing.md); a hand-written resource policy is the fallback for what RAM cannot express.
• If the accounts share an AWS Organization with resource sharing enabled, a share to an in-Org principal associates automatically and no invitation appears. Across organizations, the consumer MUST accept an invitation (step 3).
• If the bus will be encrypted with a customer managed key, you MUST put the key policy in place first; the key is checked at bus create time and a bad policy settles the bus at CREATE_FAILED (security-and-sharing.md).

1. Platform account: create the central bus

2. Platform account: share the bus, narrowest permission per principal

One share per grant scope. A consumer that only attaches subscribers gets SubscribeOnly; a producer account gets PublishOnly; the four managed permissions and what each grants are in security-and-sharing.md. Principals can be account ids, OU ARNs, or an organization ARN:

Omitting --permission-arns applies the default managed permission for the resource type, which is SubscribeOnly; you SHOULD name the permission anyway, so the grant is explicit.

3. Consumer account: accept the share (cross-Org only)

In-Org shares show no invitation; the association happens on its own.

4. Consumer account: build the consumer side

Steps 1, 2, 4, 5, and 6 of the single-account walkthrough, run in the consumer account, with one change: --event-bus-arn is the shared bus’s ARN from step 1. The queue, the dead-letter queue, the delivery role, and the subscriber all live in the consumer account.

The grant takes time to propagate after the share is accepted, so a CreateSubscriber denied immediately afterwards can be propagation rather than a missing grant; you SHOULD retry before concluding the share is wrong.

5. Verify end to end

Publish from the platform account (or from a PublishOnly-shared producer account) and confirm arrival at the consumer’s queue, exactly as in the single-account walkthrough.

6. Revoking access

Deleting the share retracts the grant RAM wrote:

Subscribers the consumer already created stop being reachable through the grant but still exist and are owned by the consumer. To cut off one specific subscriber without touching the share, the bus owner uses RevokeResource, which is terminal (authorization.md).

7. Teardown, consumer side first

1. Each consumer deletes its subscriber, then its role, then its queues (single-account step 7, minus the bus).
2. The platform account deletes the resource share.
3. The platform account deletes the bus and waits on event-bus-deleted.

The CloudFormation form of this split is in infrastructure-as-code.md: one platform stack for the bus, one sharing stack for the RAM share, and one consumer stack per account.