Managing AWS CloudFormation events using Amazon EventBridge - AWS CloudFormation

Managing AWS CloudFormation events using Amazon EventBridge

Amazon EventBridge is a serverless service that uses events to connect application components together, making it easier for you to build scalable event-driven applications. Event-driven architecture is a style of building loosely-coupled software systems that work together by emitting and responding to events. Events represent a change in a resource or environment.

As with many AWS services, AWS CloudFormation generates and sends events to the EventBridge default event bus. (The default event bus is automatically provisioned in every AWS account.) An event bus is a router that receives events and delivers them to zero or more destinations, or targets. Rules you specify for the event bus evaluate events as they arrive. Each rule checks whether an event matches the rule's event pattern. If the event does match, the event bus sends the event to the specified target(s).

AWS services send events to the EventBridge default event bus. If the event matches a rule's event pattern, EventBridge sends the event to the targets specified for that rule.

CloudFormation events

AWS CloudFormation sends events to EventBridge whenever a create, update, delete, or drift-detection operation is performed on a stack. AWS CloudFormation also sends events to EventBridge for status changes to stack sets and stack set instances. You can use EventBridge rules to route events to your defined targets. These events are guaranteed to be delivered, and they might be delivered out of order.

Since CloudFormation events represent changes to stacks or stack sets and their resources, you can use them to initiate workflows associated with respective events. For example:

  • Create stack or stack set specific tags on all resource provisioned through AWS CloudFormation.

  • Establish an association between a CloudFormation stack or stack set and an Amazon WorkSpaces Application Manager (Amazon WAM).

  • Specify an association with an AppRegistry for the created stack or stack set.

The following events are generated by CloudFormation and sent to the default event bus in EventBridge. For more information, see AWS CloudFormation events detail reference.

Event type Description

Resource Status Change

Any updates performed on a stack which changes underlying resource properties.

For a complete list of supported AWS resource types, see AWS resource and property types reference.

Stack Status Change

Represents a status change to a given stack.

For code details, see Stack status codes.

Drift Detection Status Change

Represents a user-initiated drift detection update on a given stack.

For a complete list of fully mutable and immutable types that support drift detection, see Resource type support

StackSet Status Change

Represents a status change to a given stack set.

StackSet Stack Instance Status Change

Represents a status change to a specific StackSet stack instance.

For code details, see Stack instance status codes.

StackSet operation status

Represents a status change to a given StackSet operation.

For code details, see StackSets status codes.

Sending AWS CloudFormation events using EventBridge rules

To have the EventBridge default event bus send AWS CloudFormation events to a target, you must create a rule that contains an event pattern that matches the data in the desired AWS CloudFormation events.

Creating a rule consists of the following general steps:

  1. Creating an event pattern for the rule that specifies:

    • AWS CloudFormation is the source of events being evaluated by the rule.

    • (Optional): Any other event data to match against.

    For more information, see Creating event patterns for AWS CloudFormation events

  2. (Optional): Creating an input transformer that customizes the data from the event before EventBridge passes the information to the target of the rule.

    For more information, see Input transformation in the EventBridge User Guide.

  3. Specifying the target(s) to which you want EventBridge to deliver events that match the event pattern.

    Targets can be other AWS services, software-as-a-service (SaaS) applications, API destinations, or other custom endpoints. For more information, see Targets in the EventBridge User Guide.

For comprehensive instructions on creating event bus rules, see Creating rules that react to events in the EventBridge User Guide.

Creating event patterns for AWS CloudFormation events

When AWS CloudFormation delivers an event to the default event bus, EventBridge uses the event pattern defined for each rule to determine if the event should be delivered to the rule's target(s). An event pattern matches the data in the desired AWS CloudFormation events. Each event pattern is a JSON object that contains:

  • A source attribute that identifies the service sending the event. For AWS CloudFormation events, the source is aws.cloudformation.

  • (Optional): A detail-type attribute that contains an array of the event types to match.

  • (Optional): A detail attribute containing any other event data on which to match.

    For example, the stack ID, the resources involved, status of various resources, and other data relevant to a particular type of events.

For example, the following event pattern matches against all resource state change events:

{ "source": ["aws.cloudformation"], "detail-type": ["CloudFormation Resource Status Change"] }

While the following event pattern uses event detail data to match only resource state change events where CloudFormation creates a new AWS::S3::Bucket or AWS::SNS::Topic resource:

{ "source": ["aws.cloudformation"], "detail-type": ["CloudFormation Resource Status Change"], "detail": { "status-details": { "status": ["CREATE_COMPLETE"] }, "resource-type": ["AWS::S3::Bucket", "AWS::SNS::Topic"] } }

For more information on writing event patterns, see Event patterns in the EventBridge User Guide.

Testing event patterns for AWS CloudFormation events in EventBridge

You can use the EventBridge Sandbox to quickly define and test an event pattern, without having to complete the larger process of creating or editing a rule. Using the Sandbox, you can define an event pattern and use a sample event to confirm the pattern matches the desired events. EventBridge give you the option of creating a new rule using that event pattern, directly from the sandbox.

For more information, see Testing an event pattern using the EventBridge Sandbox in the EventBridge User Guide.

Amazon EventBridge permissions

AWS CloudFormation doesn't require any additional permissions to deliver events to Amazon EventBridge. The events contain information which is already available through CloudFormation's API operations.

The targets you specify may need specific permissions or configuration. For more details on using specific services for targets, see Amazon EventBridge targets in the Amazon EventBridge User Guide.

Additional EventBridge resources

Refer to the following topics in the Amazon EventBridge User Guide for more information on how to use EventBridge to process and manage events.

  • For detailed information on how event buses work, see Amazon EventBridge event bus.

  • For information on event structure, see Events.

  • For information on constructing event patterns for EventBridge to use when matching events against rules, see Event patterns.

  • For information on creating rules to specify which events EventBridge processes, see Rules.

  • For information on to specify what services or other destinations EventBridge sends matched events to, see Targets.