AWS CloudFormation
User Guide (Version )

AWS::Events::Rule

The AWS::Events::Rule resource creates a rule that matches incoming events and routes them to one or more targets for processing. For more information, see What Is Amazon Eventbridge?.

A rule must contain at least an EventPattern or ScheduleExpression. Rules with EventPattern are triggered when a matching event is observed. Rules with ScheduleExpression self-trigger based on the given schedule. A rule can have both an EventPattern and a ScheduleExpression, in which case the rule triggers on matching events as well as on a schedule.

Most services in AWS treat : or / as the same character in Amazon Resource Names (ARNs). However, EventBridge uses an exact match in event patterns and rules. Be sure to use the correct ARN characters when creating event patterns so that they match the ARN syntax in the event that you want to match.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{ "Type" : "AWS::Events::Rule", "Properties" : { "Description" : String, "EventBusName" : String, "EventPattern" : Json, "Name" : String, "RoleArn" : String, "ScheduleExpression" : String, "State" : String, "Targets" : [ Target, ... ] } }

YAML

Type: AWS::Events::Rule Properties: Description: String EventBusName: String EventPattern: Json Name: String RoleArn: String ScheduleExpression: String State: String Targets: - Target

Properties

Description

The description of the rule.

Required: No

Type: String

Maximum: 512

Update requires: No interruption

EventBusName

The event bus to associate with this rule. If you omit this, the default event bus is used.

Required: No

Type: String

Minimum: 1

Maximum: 256

Pattern: [/\.\-_A-Za-z0-9]+

Update requires: Replacement

EventPattern

Describes which events are routed to the specified target. For more information, see Events and Event Patterns in EventBridge in the Amazon EventBridge User Guide.

When using CloudFormation, you must enclose each part of the event pattern in square brackets, as follows:

"EventPattern": { "source": [ "aws.ec2" ], "detail-type": [ "EC2 Instance State-change Notification" ] }

A rule must contain either EventPattern or ScheduleExpression.

Required: Conditional

Type: Json

Update requires: No interruption

Name

The name of the rule. If you don't specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the rule name.

Important

If you specify a name, you can't perform updates that require replacement of this resource. You can perform updates that require no or some interruption. If you must replace the resource, specify a new name.

Required: No

Type: String

Minimum: 1

Maximum: 64

Pattern: [\.\-_A-Za-z0-9]+

Update requires: Replacement

RoleArn

The Amazon Resource Name (ARN) of the role that is used for target invocation.

If you're setting an event bus in another account as the target and that account granted permission to your account through an organization instead of directly by the account ID, you must specify a RoleArn with proper permissions in the Target structure, instead of here in this parameter.

Required: No

Type: String

Minimum: 1

Maximum: 1600

Update requires: No interruption

ScheduleExpression

The scheduling expression that determines when and how often the rule runs. For more information, see Schedule Expressions for Rules.

A rule must contain either ScheduleExpression or EventPattern.

Required: Conditional

Type: String

Maximum: 256

Update requires: No interruption

State

Indicates whether the rule is enabled.

Required: No

Type: String

Allowed Values: DISABLED | ENABLED

Update requires: No interruption

Targets

The AWS resources that are invoked when the rule is triggered. For information about valid targets, see PutTargets.

If you're setting the event bus of another account as the target and that account granted permission to your account through an organization instead of directly by the account ID, you must specify a RoleArn with proper permissions in the Target structure. For more information, see Sending and Receiving Events Between AWS Accounts in the Amazon EventBridge User Guide.

Required: No

Type: List of Target

Update requires: No interruption

Return Values

Ref

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns event rule ID, such as mystack-ScheduledRule-ABCDEFGHIJK.

For more information about using the Ref function, see Ref.

Fn::GetAtt

Arn

The ARN of the rule, such as arn:aws:events:us-east-2:123456789012:rule/example.

Examples

Regularly Invoke Lambda Function

The following example creates a rule that invokes the specified Lambda function every 10 minutes. The PermissionForEventsToInvokeLambda resource grants EventBridge permission to invoke the associated function.

JSON

"ScheduledRule": { "Type": "AWS::Events::Rule", "Properties": { "Description": "ScheduledRule", "ScheduleExpression": "rate(10 minutes)", "State": "ENABLED", "Targets": [{ "Arn": { "Fn::GetAtt": ["LambdaFunction", "Arn"] }, "Id": "TargetFunctionV1" }] } }, "PermissionForEventsToInvokeLambda": { "Type": "AWS::Lambda::Permission", "Properties": { "FunctionName": { "Ref": "LambdaFunction" }, "Action": "lambda:InvokeFunction", "Principal": "events.amazonaws.com", "SourceArn": { "Fn::GetAtt": ["ScheduledRule", "Arn"] } } }

YAML

ScheduledRule: Type: AWS::Events::Rule Properties: Description: "ScheduledRule" ScheduleExpression: "rate(10 minutes)" State: "ENABLED" Targets: - Arn: Fn::GetAtt: - "LambdaFunction" - "Arn" Id: "TargetFunctionV1" PermissionForEventsToInvokeLambda: Type: AWS::Lambda::Permission Properties: FunctionName: Ref: "LambdaFunction" Action: "lambda:InvokeFunction" Principal: "events.amazonaws.com" SourceArn: Fn::GetAtt: - "ScheduledRule" - "Arn"

Invoke Lambda Function in Response to an Event

The following example creates a rule that invokes the specified Lambda function when any EC2 instance's state changes to stopping.

JSON

"EventRule": { "Type": "AWS::Events::Rule", "Properties": { "Description": "EventRule", "EventPattern": { "source": [ "aws.ec2" ], "detail-type": [ "EC2 Instance State-change Notification" ], "detail": { "state": [ "stopping" ] } }, "State": "ENABLED", "Targets": [{ "Arn": { "Fn::GetAtt": ["LambdaFunction", "Arn"] }, "Id": "TargetFunctionV1" }] } }, "PermissionForEventsToInvokeLambda": { "Type": "AWS::Lambda::Permission", "Properties": { "FunctionName": { "Ref": "LambdaFunction" }, "Action": "lambda:InvokeFunction", "Principal": "events.amazonaws.com", "SourceArn": { "Fn::GetAtt": ["EventRule", "Arn"] } } }

YAML

EventRule: Type: AWS::Events::Rule Properties: Description: "EventRule" EventPattern: source: - "aws.ec2" detail-type: - "EC2 Instance State-change Notification" detail: state: - "stopping" State: "ENABLED" Targets: - Arn: Fn::GetAtt: - "LambdaFunction" - "Arn" Id: "TargetFunctionV1" PermissionForEventsToInvokeLambda: Type: AWS::Lambda::Permission Properties: FunctionName: Ref: "LambdaFunction" Action: "lambda:InvokeFunction" Principal: "events.amazonaws.com" SourceArn: Fn::GetAtt: - "EventRule" - "Arn"

Notify a Topic in Response to a Log Entry

The following example creates a rule that notifies an Amazon Simple Notification Service topic if an AWS CloudTrail log entry contains a call by the Root user. The EventTopicPolicy resource grants Amazon EventBridge permission to notify the associated Amazon SNS topic.

JSON

"OpsEventRule": { "Type": "AWS::Events::Rule", "Properties": { "Description": "EventRule", "EventPattern": { "detail-type": [ "AWS API Call via CloudTrail" ], "detail": { "userIdentity": { "type": [ "Root" ] } } }, "State": "ENABLED", "Targets": [ { "Arn": { "Ref": "MySNSTopic" }, "Id": "OpsTopic" } ] } } "EventTopicPolicy": { "Type": "AWS::SNS::TopicPolicy", "Properties": { "PolicyDocument": { "Statement": [ { "Effect": "Allow", "Principal": { "Service": "events.amazonaws.com" }, "Action": "sns:Publish", "Resource": "*" } ] }, "Topics": [ { "Ref": "MySNSTopic" } ] } }

YAML

OpsEventRule: Type: AWS::Events::Rule Properties: Description: "EventRule" EventPattern: detail-type: - "AWS API Call via CloudTrail" detail: userIdentity: type: - "Root" State: "ENABLED" Targets: - Arn: Ref: "MySNSTopic" Id: "OpsTopic" EventTopicPolicy: Type: 'AWS::SNS::TopicPolicy' Properties: PolicyDocument: Statement: - Effect: Allow Principal: Service: events.amazonaws.com Action: 'sns:Publish' Resource: '*' Topics: - !Ref MySNSTopic