amazon-eventbridge-event-bus

Files (18)

• SKILL.md
• authorization.md · references/
• cloudevents.md · references/
• code-samples.md · references/
• cost-and-quotas.md · references/
• delivery-troubleshooting.md · references/
• event-sources.md · references/
• filters-and-expressions.md · references/
• infrastructure-as-code.md · references/
• migrating-from-classic.md · references/
• observability.md · references/
• provisioning-and-state.md · references/
• replay-and-recovery.md · references/
• schema-registries.md · references/
• security-and-sharing.md · references/
• setup-walkthroughs.md · references/
• target-configuration.md · references/
• target-contract.md · references/

SKILL.md (first lines)

# Building with the new EventBridge custom event buses

## Overview

The new EventBridge custom event bus routes events and retains them. You publish with
one of two APIs, and subscribers filter, optionally transform, and deliver each matching event to one target.

**Read chapters 5 and 6 before writing any filter, transformer, or target parameter.** The two publish APIs
deliver different payload shapes, and an expression written for one silently matches nothing against the
other.

Publish metrics are on by default, so you can always tell whether events reached a bus. Subscriber logs
are **off** by default, so turn them on before you debug a delivery rather than after (chapter 18).

**Works best with** the [AWS MCP server](https://docs.aws.amazon.com/aws-mcp/), which is recommended for
running the CLI calls in this skill: it executes them in a sandboxed environment with audit logging. All
guidance also works with standard AWS CLI access.

## Conventions

The key words **MUST**, **MUST NOT**, **SHOULD**, and **MAY** in this skill are to be interpreted as
described in RFC 2119. They appear only in decision procedures, where following the wrong course either
breaks the configuration or loses events silently. **MUST** marks an absolute requirement, **SHOULD** a
strong recommendation you may have a specific reason to set aside, and **MAY** a genuine option.

Everything else is ordinary description. A sentence stating how the service behaves carries no keyword,
because it is a fact rather than an instruction to you.

## When not to use this skill

This skill is only about the new custom event buses, the service you reach with the `eventsv2` CLI
and the `eventbridgev2` SDK clients. It does not cover:

* **Classic EventBridge**, meaning the `events` API with rules, targets, archives, and event patterns on
  `AWS::Events::Rule`. The two services share the `events:` IAM namespace and some vocabulary, which is
  exactly why they are easy to confuse. If you are writing a rule, you are not on a new bus. Chapter 3
  maps the concepts across if you are migrating.
* **EventBridge Pipes, Scheduler, and Schemas** (the classic schema registry and its discovery feature).
  Different APIs.
* **Configuring the Firehose service itself**, such as buffering hints or record transformation. A
  Firehose delivery stream is a valid subscriber target; chapter 9 covers that side of it.

## Trigger examples

1. "Write a filter so this subscriber only gets orders over $500."
2. "My producer says PUBLISHED but nothing shows up in the queue. What do I check?"
3. "Should I use PutEvents or PutRawEvents for Protobuf payloads?"
4. "Set up a subscriber that reprocesses everything from the last two days."
5. "Write a JSONata expression that pulls the customer id out of the event into a DynamoDB putItem."

## Guardrail — where this skill's own files live (MCP vs local install)

This skill can be loaded two ways, and they resolve the skill's own bundled
files from different places. Determine how the skill was loaded before reading
a reference:

* **Loaded through the AWS MCP `retrieve_skill` tool:** The skill is not
  installed on the local filesystem. You MUST fetch each reference via
  `retrieve_skill` with the `file` parameter (e.g.
  `file="references/setup-walkthroughs.md"`). Do NOT `file_read` these paths
  locally — they do not exist on disk.
* **Installed locally** (e.g. `.kiro/skills/amazon-eventbridge-event-bus/` or
  `~/.claude/skills/amazon-eventbridge-event-bus/`): Read files from the local
  skill directory using relative paths.

This distinction applies only to the skill's own packaged files. User data and
session artifacts are always read from and written to the user's working
directory. Never fetch or write customer data through `retrieve_skill`.

## Reference files

The chapters below carry the decisions and the failure modes; the detail lives in these files. Load a
file when the task matches its row, and do not load them all by default.

| File | When to load |
|---|---|
| [setup-walkthroughs.md](references/setup-walkthroughs.md) | standing up a working bus end to end, in one account or shared across accounts with AWS RAM, including prerequisites and teardown |
| [code-samples.md](references/code-samples.md) | writing an individual CLI or SDK call (Python, Java, TypeScript): create a bus and subscriber, publish with either API, binary payloads, replay, cross-account grants, waiters, per-entry results, throttling backoff |
| [filters-and-expressions.md](references/filters-and-expressions.md) | writing any filter pattern, JSONata expression, or target parameter that reads the event; both delivered envelopes in full |
| [target-configuration.md](references/target-configuration.md) | configuring any subscriber target, especially a universal target |
| [target-contract.md](references/target-contract.md) | writing an actual `CreateSubscriber` call: required fields, a working example per target type, literal versus JSONata, the delivery error taxonomy |
| [migrating-from-classic.md](references/migrating-from-classic.md) | migrating from classic EventBridge, planning the migration sequence, or classic habits producing wrong new-bus config |
| [event-sources.md](references/event-sources.md) | putting AWS service events or partner events on a bus with an event source, or forwarded events not arriving or not matching a filter |
| [provisioning-and-state.md](references/provisioning-and-state.md) | creating or updating a bus, or a resource stuck in an unexpected state |
| [delivery-troubleshooting.md](references/delivery-troubleshooting.md) | an event published but never arrived, or building a test rig that counts deliveries correctly |
| [authorization.md](references/authorization.md) | writing an IAM policy or bus resource policy, cross-account access checks, or anything that forwards events into a bus |
| [replay-and-recovery.md](references/replay-and-recovery.md) | reading history rather than new events, pausing or resuming, or a replay that looks broken |
| [observability.md](references/observability.md) | setting up metrics, alarms, or the vended-log delivery; reading delivery logs; observing across accounts |
| [schema-registries.md](references/schema-registries.md) | publishing Avro, Protobuf, or anything that is not JSON; the accepted content types; running alongside Kafka |
| [cloudevents.md](references/cloudevents.md) | publishing or consuming CloudEvents, or filtering on CloudEvents attributes |
| [security-and-sharing.md](references/security-and-sharing.md) | encrypting a bus, sharing it cross-account, or tagging |
| [cost-and-quotas.md](references/cost-and-quotas.md) | billing mechanics, who pays what across accounts, shaping events for cost, or handling throttling |
| [infrastructure-as-code.md](references/infrastructure-as-code.md) | writing a CloudFormation template, splitting stacks across accounts, or private connectivity |

---

## 1. The three resources

**Event bus.** The thing you publish to. It routes events and retains them.

**Subscriber.** A statement of which events you want and where to send them, in one resource. It watches its
bus, keeps the events matching its filter, optionally transforms each one, and delivers it to exactly one
target. To send one event to several targets, create several subscribers on the same bus.

**Event source.** A managed feed into a bus, either AWS service events or a partner/SaaS source.

Names and identifiers:

* A bus ARN and a subscriber ARN both end in a service-generated id after the name:
  `arn:aws:events:us-east-1:111122223333:event-busv2/my-bus/exampleid0123456789abcdef`.
  **Store the full ARN, not the name**, because the name alone does not identify the resource and
  re-creating a deleted bus with the same name yields a different id.
* Event source names are unique per account, not per bus.
* **Three names identify this service and they do not match.** The CLI command and the endpoint host
  are `eventsv2`, as in `aws eventsv2 create-event-bus` and `eventsv2.{region}.amazonaws.com`. The SDK
  clients are `eventbridgev2`. IAM actions and ARNs are `events`, shared with classic EventBridge, as
  in `events:PutEvents` and `arn:aws:events:...:event-busv2/...`. See chapter 14.

## 2. A router with a durable log behind it

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws