Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Creating Custom Event Bus resources with Amazon CloudFormation

You can create a bus, its subscribers, its event sources, and its resource policy from a Amazon CloudFormation template. The resource types are in the AWS::EventsV2 namespace. The AWS::Events types belong to Custom Event Bus - Classic and cannot configure a Custom Event Bus.

The resource types

A subscriber's RoleArn must name a role in the same account as the subscriber. So a bus shared across accounts is more than one stack: the bus in the owner's account, and the target, the delivery role, and the subscriber in each consuming account.

Example: a bus, a queue, and a subscriber

The following template creates a bus that retains events for seven days, an Amazon SQS queue, a dead-letter queue, a delivery role, and a subscriber that delivers orders over 500 to the queue. Amazon CloudFormation creates the role and the queues before the subscriber, because the subscriber refers to them with Fn::GetAtt. The retention period decides how far back a subscriber can start reading; see Replaying retained events to a subscriber.

AWSTemplateFormatVersion: '2010-09-09'

Resources:
  OrdersBus:
    Type: AWS::EventsV2::EventBus
    Properties:
      Name: orders
      Description: Order events for the fulfillment platform
      StorageConfiguration:
        RetentionPeriodInDays: 7

  OrdersQueue:
    Type: AWS::SQS::Queue
    Properties:
      QueueName: large-orders

  OrdersDeadLetterQueue:
    Type: AWS::SQS::Queue
    Properties:
      QueueName: large-orders-dlq

  DeliveryRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: EventBusDeliveryRole
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: events.amazonaws.com
            Action: sts:AssumeRole
      Policies:
        - PolicyName: DeliverToQueues
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Effect: Allow
                Action: sqs:SendMessage
                Resource:
                  - !GetAtt OrdersQueue.Arn
                  - !GetAtt OrdersDeadLetterQueue.Arn

  LargeOrders:
    Type: AWS::EventsV2::Subscriber
    Properties:
      Name: large-orders
      EventBusArn: !Ref OrdersBus
      FilterConfiguration:
        Filters:
          - Scope: DATA
            Pattern: '{"detail":{"total":[{"numeric":[">",500]}]}}'
      InvokeConfiguration:
        TargetArn: !GetAtt OrdersQueue.Arn
        RoleArn: !GetAtt DeliveryRole.Arn
      RetryPolicy:
        MaxRetryAttempts: 10
        MaxEventAgeInSeconds: 3600
      OnFailureConfiguration:
        Arn: !GetAtt OrdersDeadLetterQueue.Arn

Outputs:
  OrdersBusArn:
    Value: !Ref OrdersBus
    Export:
      Name: orders-bus-arn

The delivery role trusts the events.amazonaws.com service principal and grants sqs:SendMessage on both queues. Without the grant on the dead-letter queue, a failed delivery cannot be recorded and nothing is observable. The identity that deploys the stack also needs iam:PassRole on the delivery role.

Return values

Ref returns the resource's primary identifier, an ARN. Fn::GetAtt returns the read-only properties. The following table lists the values for each resource type.

A subscriber's State is a property you set, not an attribute you read. Set it to STOPPED to pause delivery and back to RUNNING to resume. A bus's State is read-only, and its settled value is ACTIVE.

Properties that replace the resource

Six subscriber properties are create-only, so changing any of them in a template replaces the subscriber: Name, EventBusArn, InvokeConfiguration.TargetArn, Type, StartingPosition, and PointInTimeConfiguration. Every other subscriber property, including the filters, the transform, the retry policy, and the dead-letter queue, updates in place.

To avoid the gap, deploy twice. First add the replacement subscriber under a new logical id and wait for its State to reach RUNNING. Then remove the old subscriber in a second deployment. Both subscribers deliver during the overlap, so the target receives each matching event twice; use this approach only when duplicates are acceptable.

If you cannot deploy twice, set the new subscriber's StartingPosition to POINT_IN_TIME and give PointInTimeConfiguration a PointType of TIMESTAMP with a StartingPoint, in seconds since the Unix epoch, from before the deployment. The subscriber then reads the events it missed, provided they are still within the bus's retention period.

On a bus, only Name is create-only, so the retention period, the description, the encryption key, and the tags all update in place. On an event source, Name and EventBusArn are create-only, and on a resource policy, EventBusArn is.

Referring to a bus from another stack

A subscriber needs the full bus ARN, which includes the service-generated identifier after the bus name. Store and pass the ARN, not the name. See Names, endpoints, and IAM permissions for the Custom Event Bus.

Within one account and Region, export the ARN from the stack that owns the bus, as the example does, and import it with EventBusArn: !ImportValue orders-bus-arn. Amazon CloudFormation does not let you change or remove an exported value while another stack imports it. Renaming the bus replaces it and changes its ARN, so a rename fails while an import exists. Remove the importing subscriber first, or export under a new name.

An export cannot be imported from another account or another Region. Pass the bus ARN into the consuming stack as a template parameter instead. The bus owner must also grant the other account permission on the bus, which you do with a resource policy or with Amazon Resource Access Manager (Amazon RAM). See Access control for the Custom Event Bus.