AWS CloudFormation
User Guide (Version )

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

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 CloudWatch Events?.

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, CloudWatch Events 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, "EventPattern" : Json, "Name" : String, "RoleArn" : String, "ScheduleExpression" : String, "State" : String, "Targets" : [ Target, ... ] } }

YAML

Type: AWS::Events::Rule Properties: Description: 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

EventPattern

Describes which events CloudWatch Events routes to the specified target. For more information, see Event Patterns in CloudWatch Events in the Amazon CloudWatch Events User Guide.

Required: No

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.

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.

Required: No

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 resources that CloudWatch Events routes events to and invokes 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 CloudWatch Events 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 CloudWatch Events 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 CloudWatch Events 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