Introducing cross-Region event routing with Amazon EventBridge

Using Amazon EventBridge, you can now route events from any commercial AWS Region to other supported Regions. The initial list of supported destination Regions is: US East (N. Virginia – us-east-1), US West (Oregon – us-west-2), and Europe (Ireland – eu-west-1). This blog post explains how to configure cross-Region event routing and walks through an example you can deploy to your AWS account.

Amazon EventBridge enables developers to route events between AWS services, integrated software as a service (SaaS) applications, and your own applications. It can help decouple applications and produce more extensible, maintainable architectures. With this new feature, you can now route events across Regions using the same model used to route events to existing targets.

This makes it easier to develop multi-Region workloads and can be used to:

Centralize your AWS events into one Region for auditing and monitoring purposes. For example, capture all workload events from multiple global Regions in us-east-1 for compliance reporting.
Invoke asynchronous workflows in a different Region from a source event. For example, you can load balance from a target Region by routing events to another Region.
Replicate events from source to destinations Regions to help synchronize data in cross-Region data stores.

How cross-Region routing works

Event buses route events using rules, which match events with patterns, and route to targets. To route an event from an event bus in any Region, you must create a rule and define which event bus to route to. Currently, you can route to any event bus in the three supported Regions. Cross-Region event buses can be in the same AWS account or different AWS accounts.

Using cross-Region buses as targets works the same way as using cross-account buses as targets. To add a bus in another Region as a target to a rule:

Navigate to the EventBridge console. Choose Create rule.
Provide a name and pattern and choose the source event bus.
In the Select targets panel:
1. For Target, select Event bus in a different account or Region.
2. For Event Bus, enter the ARN of the target event bus.
3. Keep the selected option Create a new role for this specific resource. This creates the necessary IAM permissions to allow the rule to put events on the target bus.
Choose Save.

Events that match the rule are then delivered to the target cross-Region event bus. The delivered event is identical to the original event, and does not contain any additional metadata or attributes.

If you use the CLI to configure the target, you must manually create the IAM role that provides permission for the rule to route to the target bus. This role should include a policy that allows an event:PutEvents action for the target bus:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "events:PutEvents"
            ],
            "Resource": [
                "arn:aws:events:us-east-1:123456789012:event-bus/*"
            ]
        }
    ]
}

You must also enable events.amazonaws.com as a trusted entity on the IAM role:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "events.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

The target bus also requires a rule to process the event, otherwise the event is discarded. You can create a rule on the target bus to route the event to AWS Lambda functions, Amazon SQS queues, API destinations, or any other available target.

Creating a cross-Region routing rule in AWS CloudFormation

Using AWS CloudFormation or the AWS Serverless Application Model (AWS SAM), you can deploy EventBridge buses, rules, and policies using infrastructure as code (IaC). To create a rule on an event bus that routes events across Regions, first create the AWS::Events::Rule resource:

Resources:
  EventRuleRegion1: 
    Type: AWS::Events::Rule
    Properties: 
      Description: "Routes to us-east-1 event bus"
      EventBusName: "MyBusName"
      State: "ENABLED"
      EventPattern: 
        source:
          - 'MyTestApp'
        detail:
          - 'MyTestAppDetail'
      Targets: 
        - Arn: "arn:aws:events:us-east-1:123456789012:event-bus/CrossRegionDestinationBus"
          Id: " CrossRegionDestinationBus"
          RoleArn: !GetAtt EventBridgeIAMrole.Arn

Next, create an AWS::IAM::Role resource that allows EventBridge to put events on the target bus in the destination Region:

  EventBridgeIAMrole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: 2012-10-17
        Statement:
        - Effect: Allow
          Principal:
            Service:
              !Sub events.amazonaws.com
          Action: sts:AssumeRole
      Path: /
      Policies:
      - PolicyName: PutEventsDestinationBus
        PolicyDocument:
          Version: 2012-10-17
          Statement:
          - Effect: Allow
            Action:
            - events:PutEvents
            Resource:
            - "arn:aws:events:us-east-1:123456789012:event-bus/CrossRegionDestinationBus"

Limiting access to who can route events across Regions

For cross-Region event routing, the principal is always the IAM role that is configured as part of the rule target in the source Region. You can also route events to cross-Region buses in other AWS accounts. This section shows how to restrict access to limit which entities can route events to a target cross-Region bus.

Allowing only defined rules to send events cross-Region

You can define a resource-based policy using the ArnEquals conditional operator to restrict permissions to a subset of rules. This condition could be used on either the event bus policy or the IAM policy.

For example, the following policy allows rules from event buses in two Regions (us-west-2 & me-south-1) in account 444455556666 to send events to a destination bus in account 111122223333:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowRulesForCrossRegionEvents",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::444455556666:root"
      },
      "Action": "events:PutEvents",
      "Resource": "arn:aws:events:us-east-1:111122223333:event-bus/CrossRegionBus",
      "Condition": {
        "ArnEquals": {
          "aws:SourceArn": [
            "arn:aws:events:us-west-2:444455556666:rule/CrossRegionBus/SendToUSE1AnotherAccount",
            "arn:aws:events:me-south-1:444455556666:rule/CrossRegionBus/SendToUSE1AnotherAccount"
          ]
        }
      }
    }
  ]
}

Allowing only certain Regions from approved AWS accounts

Similarly, you can use an IAM policy attached to the target event bus to limit which Regions and accounts can send cross-Region targets. For example, this policy allows events from two Regions (us-west-2 and me-south-1) from account 444455556666 to be routed to an event bus called CrossRegionBus in account 111122223333 (us-east-1):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowEventsFromTwoRegions",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam:444455556666:root"
      },
      "Action": "events:PutEvents",
      "Resource": "arn:aws:events:us-east-1:111122223333:event-bus/CrossRegionBus",
      "Condition": {
        "ArnEquals": {
          "aws:SourceArn": [
            "arn:aws:events:us-west-2:*:*",
            "arn:aws:events:me-south-1:*:*"
          ]
        }
      }
    }
  ]
}

Denying access to events from specified Regions

The following policy, attached to the cross-Region bus of account 111122223333, denies events from specified Regions. There are two statements to the policy. The first allows all events from account 444455556666 and the second adds an explicit deny for any events from us-west-2.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowAllEventsFromAccount_444455556666 ",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam:444455556666:root"
      },
      "Action": "events:PutEvents",
      "Resource": "arn:aws:events:us-east-1:111122223333:event-bus/CrossRegionBus"
    },
    {
      "Sid": "DenyAllCrossRegionEventsFrom-us-west-2",
      "Effect": "Deny",
      "Principal": {
        "AWS": "*"
      },
      "Action": "events:PutEvents",
      "Resource": "arn:aws:events:us-east-1:111122223333:event-bus/CrossRegionBus",
      "Condition": {
        "ArnEquals": {
          "aws:SourceArn": [
            "arn:aws:events:us-west-2:*:*"
          ]
        }
      }
    }
  ]
}

Deploying the example application

The example application creates custom event buses and other resources in four Regions. The source Region includes a webhook to help demonstrate the routing functionality:

In the source Region, an Amazon API Gateway endpoint invokes a Lambda function, which puts an event on the event bus. It uses the Region query parameter to pass the target Region to the event payload.
There are three rules on the custom event bus in the source Region. Each rule filters on the Region attribute to route to the event bus in the target Region.
Each target Region has a custom event bus to receive the cross-Region events. There is also a rule to route these events to a Lambda function to log the output.

To deploy this application:

From a terminal, clone the GitHub repo and navigate to the solution directory:
git clone https://github.com/aws-samples/serverless-patterns
cd ./eventbridge-cross-region/eventbus-destination
First, deploy the target event buses in the supported Regions. Run the following command three times, each time replacing the deployment Region with us-east-1, us-west-2, and eu-west-1:
sam deploy --guided
Next, deploy the source Region template, which deploys a custom event bus and webhook. Select any Region except for the three Regions from step 2:
cd ../eventbus-source
sam deploy --guided
Once the stack is created, note the output value for the webhook API URL:

To test the event routing:

Use curl or Postman to call the API endpoint, replacing <<region code>> with us-east-1:
Navigate to the Lambda console in us-east-1. Choose the function beginning with ‘eventbridge-cross-region-destination’.
Select the Monitor tab, then choose View logs in CloudWatch.
Select the most recent stream to see the event. It shows the source Region in the region attribute and the destination Region in the detail attribute:
Repeat the test, changing the query parameter in the API endpoint from us-east-1 to us-west-2 and eu-west-1. Verify the Lambda function’s logs in those Regions to see the events successfully routed.

Conclusion

With cross-Region event routing in EventBridge, you can now route events from any AWS Region to other supported Regions. This post explains how to configure cross-Region event routing in the console and CLI and explains how to restrict access to routing capabilities. Finally, I walk through an example you can deploy to your AWS account.

For more serverless learning resources, visit Serverless Land.

AWS Compute Blog