Sign In to the Console
AWS CloudFormation
User Guide (API Version 2010-05-15)

AWS Documentation » AWS CloudFormation » User Guide » Template Reference » AWS Resource and Property Types Reference » Amazon CloudWatch Resource Types Reference » AWS::Events::Rule

AWS::Events::Rule

The AWS::Events::Rule resource creates a rule that matches incoming Amazon CloudWatch Events (CloudWatch Events) events and routes them to one or more targets for processing. For more information, see Using CloudWatch Events in the Amazon CloudWatch User Guide.

Syntax

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

JSON

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

YAML

Type: AWS::Events::Rule
Properties: 
  Description: String
  EventPattern: JSON object
  Name: String
  ScheduleExpression: String
  State: String
  Targets:
    - Target

Properties

Description

A description of the rule's purpose.

Required: No

Type: String

Update requires: No interruption

EventPattern

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

Required: Conditional. You must specify this property, the ScheduleExpression property, or both.

Type: JSON object

Update requires: No interruption

Name

A name for the rule. If you don't specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the rule name. For more information, see Name Type.

Important

If you specify a name, you cannot 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

Update requires: Replacement

ScheduleExpression

The schedule or rate (frequency) that determines when CloudWatch Events runs the rule. For more information, see Schedule Expression Syntax for Rules in the Amazon CloudWatch User Guide.

Required: Conditional. You must specify this property, the EventPattern property, or both.

Type: String

Update requires: No interruption

State

Indicates whether the rule is enabled. For valid values, see the State parameter for the PutRule action in the Amazon CloudWatch Events API Reference.

Required: No

Type: String

Update requires: No interruption

Targets

The resources, such as Lambda functions or Kinesis streams, that CloudWatch Events routes events to and invokes when the rule is triggered. For information about valid targets, see the PutTargets action in the Amazon CloudWatch Events API Reference.

Note

Creating rules with built-in targets is supported only in the AWS Management Console.

Required: No

Type: List of Amazon CloudWatch Events Rule Target

Update requires: No interruption

Return Value

Ref

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

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

Fn::GetAtt

Fn::GetAtt returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

Arn

The event rule Amazon Resource Name (ARN), such as arn:aws:events:us-east-2:123456789012:rule/example.

For more information about using Fn::GetAtt, see Fn::GetAtt.

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