|
| 1 | +# # Amazon EventBridge fan-out pattern in Terraform |
| 2 | + |
| 3 | +This Terraform pattern demonstrates schedule fan-out using Amazon EventBridge Scheduler. A single schedule puts an event onto a custom EventBridge event bus, which routes it to three downstream targets simultaneously which includes an AWS Lambda function for processing, an Amazon SNS topic for notifications, and an Amazon SQS queue for archival. Each target is matched by its own EventBridge Rule on the bus, so new targets can be added without modifying the schedule itself. Every target is fully decoupled and if one fails, the others are unaffected. |
| 4 | + |
| 5 | +Learn more about this pattern at Serverless Land Patterns: https://serverlessland.com/patterns/eventbridge-fanout-pattern |
| 6 | + |
| 7 | +Important: this application uses various AWS services and there are costs associated with these services after the Free Tier usage - please see the [AWS Pricing page](https://aws.amazon.com/pricing/) for details. You are responsible for any AWS costs incurred. No warranty is implied in this example. |
| 8 | + |
| 9 | +## Prerequisites |
| 10 | + |
| 11 | +* [Create an AWS account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) if you do not already have one and log in. The IAM user that you use must have sufficient permissions to make necessary AWS service calls and manage AWS resources. |
| 12 | +* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) installed and configured |
| 13 | +* [Git Installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) |
| 14 | +* [Terraform](https://learn.hashicorp.cxom/tutorials/terraform/install-cli?in=terraform/aws-get-started) installed |
| 15 | + |
| 16 | +## Deployment Instructions |
| 17 | + |
| 18 | +1. Create a new directory, navigate to that directory in a terminal and clone the GitHub repository: |
| 19 | + ``` |
| 20 | + git clone https://github.com/aws-samples/serverless-patterns |
| 21 | + ``` |
| 22 | +1. Change directory to the pattern directory: |
| 23 | + ``` |
| 24 | + cd eventbridge-fanout-pattern |
| 25 | + ``` |
| 26 | +1. From the command line, initialize terraform to downloads and installs the providers defined in the configuration: |
| 27 | + ``` |
| 28 | + terraform init |
| 29 | + ``` |
| 30 | +1. From the command line, apply the configuration in the main.tf file: |
| 31 | + ``` |
| 32 | + terraform apply -auto-approve |
| 33 | + ``` |
| 34 | +1. During the prompts: |
| 35 | + #var.aws_region |
| 36 | + - Enter a value: {enter the region for deployment} |
| 37 | +
|
| 38 | + #var.prefix |
| 39 | + - Enter a value: {enter any prefix to associate with resources} |
| 40 | +
|
| 41 | +1. Note the outputs from the Terraform deployment process. These contain the resource names and/or ARNs which are used for testing. |
| 42 | +
|
| 43 | +## How it works |
| 44 | +
|
| 45 | + |
| 46 | +
|
| 47 | +Amazon EventBridge Scheduler runs a single schedule on a five minute rate and targets a custom EventBridge Event Bus which is the core of the fan-out pattern. Because Scheduler only supports one target per schedule, the bus acts as a routing hub. Three EventBridge Rules sit on that bus, each matching the same event pattern and forwarding the event simultaneously to three independent targets namely an AWS Lambda function that processes the payload, an Amazon SNS topic that delivers notifications to subscribers, and an Amazon SQS queue that stores the event for archival or downstream consumption. If one target fails or is removed, the others continue to work without interruption. |
| 48 | +
|
| 49 | +## Testing |
| 50 | +
|
| 51 | +The scheduler fires once every five minutes and puts an event onto a custom EventBridge Event Bus. Three rules on that bus match the event and fan it out simultaneously to a Lambda function, an SNS topic, and an SQS queue. |
| 52 | +
|
| 53 | +To test the full flow without waiting for the next five-minute trigger, you can publish the same event to the bus manually using the AWS CLI put-events command and verify within seconds that Lambda logs the event, a message appears in the SQS queue, and SNS delivers to any confirmed subscribers. |
| 54 | +
|
| 55 | +1. After deploying the stack, create a Subscriber for your Amazon SNS topic (For ex, your email) and confirm the subscription. |
| 56 | + https://docs.aws.amazon.com/sns/latest/dg/sns-create-subscribe-endpoint-to-topic.html |
| 57 | +
|
| 58 | +1. Publish the event in the custom bus using the following CLI command: |
| 59 | + ``` |
| 60 | + PREFIX=$(terraform output -raw prefix) |
| 61 | + ``` |
| 62 | + |
| 63 | + ``` |
| 64 | + aws events put-events --entries '[ |
| 65 | + { |
| 66 | + "Source": "'$PREFIX'.scheduler.fan-out", |
| 67 | + "DetailType": "ScheduledTask", |
| 68 | + "EventBusName": "'$PREFIX'-scheduled-bus", |
| 69 | + "Detail": "{\"taskId\":\"manual-testing\",\"message\":\"manual-test-message-1\"}" |
| 70 | + } |
| 71 | + ]' |
| 72 | + ``` |
| 73 | +
|
| 74 | +1. Now check the CloudWatch logs for the Lambda function to see if the message has been processed |
| 75 | + ``` |
| 76 | + aws logs tail /aws/lambda/$PREFIX-scheduled-processor --region $(terraform output -raw region) --since 5m --format short |
| 77 | + ``` |
| 78 | + You should see an output like this: |
| 79 | + ``` |
| 80 | + { |
| 81 | + "statusCode": 200, |
| 82 | + "taskId": "manual-test", |
| 83 | + "result": { |
| 84 | + "echo": { |
| 85 | + "taskId": "manual-testing", |
| 86 | + "message": "manual-test-message-1" |
| 87 | + } |
| 88 | + }, |
| 89 | + "processedAt": "2026-03-09TXXXXX", |
| 90 | + "requestId": "a730a9b9-fbXXXXXX" |
| 91 | + } |
| 92 | + ``` |
| 93 | + This means that the message has been processed by the Lambda function |
| 94 | +
|
| 95 | +1. Check the SQS queue to see if the message has been received |
| 96 | + ``` |
| 97 | + aws sqs receive-message --queue-url $(terraform output -raw sqs_queue_url) --region $(terraform output -raw region) --wait-time-seconds 5 |
| 98 | + ``` |
| 99 | + You should see an output in this format: |
| 100 | + ``` |
| 101 | + { |
| 102 | + "Messages": [ |
| 103 | + { |
| 104 | + "MessageId": "e6be124b-XXXX", |
| 105 | + "ReceiptHandle": "AQEBXXXX", |
| 106 | + "MD5OfBody": "dff96eXXXXX", |
| 107 | + "Body": { |
| 108 | + "version": "0", |
| 109 | + "id": "417a39aXXXXX", |
| 110 | + "detail-type": "ScheduledTask", |
| 111 | + "source": "<prefix>.scheduler.fan-out", |
| 112 | + "account": "123456789012", |
| 113 | + "time": "2025-01-15TXXXX", |
| 114 | + "region": "<region>", |
| 115 | + "resources": [], |
| 116 | + "detail": { |
| 117 | + "taskId": "manual-testing", |
| 118 | + "message": "manual-test-message-1" |
| 119 | + } |
| 120 | + } |
| 121 | + } |
| 122 | + ]} |
| 123 | + ``` |
| 124 | +
|
| 125 | +1. The SNS topic will send the message to the confirmed subscriber so check the subscriber (for ex, email) to see the message. |
| 126 | + ``` |
| 127 | + { |
| 128 | + "version": "0", |
| 129 | + "id": "df58af75-xxxx-xxxx-xxxx-xxxxxxxxxxxx", |
| 130 | + "detail-type": "ScheduledTask", |
| 131 | + "source": "<prefix>.scheduler.fan-out", |
| 132 | + "account": "123456789012", |
| 133 | + "time": "2025-01-15T10:30:00Z", |
| 134 | + "region": "<region>", |
| 135 | + "resources": [], |
| 136 | + "detail": { |
| 137 | + "taskId": "manual-testing", |
| 138 | + "message": "manual-test-message-1" |
| 139 | + } |
| 140 | + } |
| 141 | + ``` |
| 142 | +
|
| 143 | +## Cleanup |
| 144 | +
|
| 145 | +1. Change directory to the pattern directory: |
| 146 | + ``` |
| 147 | + cd serverless-patterns/eventbridge-fanout-pattern |
| 148 | + ``` |
| 149 | +
|
| 150 | +1. Delete all created resources |
| 151 | + ``` |
| 152 | + terraform destroy -auto-approve |
| 153 | + ``` |
| 154 | + |
| 155 | +1. During the prompts: |
| 156 | + ``` |
| 157 | + Enter all details as entered during creation. |
| 158 | + ``` |
| 159 | +
|
| 160 | +1. Confirm all created resources has been deleted |
| 161 | + ``` |
| 162 | + terraform show |
| 163 | + ``` |
| 164 | +---- |
| 165 | +Copyright 2026 Amazon.com, Inc. or its affiliates. All Rights Reserved. |
| 166 | +
|
| 167 | +SPDX-License-Identifier: MIT-0 |
0 commit comments