CloudWatch Events Rules
The cloudwatchEvent event triggers a Lambda function when an event on the default event bus matches a pattern, such as an EC2 instance changing state. CloudWatch Events is the earlier name of Amazon EventBridge: the Framework creates an EventBridge rule on the default event bus with the cloudwatchEvent event's pattern, the function as its target, and a permission for EventBridge to invoke the function. For custom event buses, schedules, retry policies and dead-letter queues, use the eventBridge event instead.
This serverless.yml runs a function whenever an EC2 instance enters the pending state:
# serverless.yml
service: my-service
provider:
name: aws
runtime: nodejs24.x
functions:
instanceStateChange:
handler: handler.instanceStateChange
events:
- cloudwatchEvent:
event:
source:
- aws.ec2
detail-type:
- EC2 Instance State-change Notification
detail:
state:
- pending
The handler receives the matching event, with the service-specific data in event.detail:
// handler.mjs
export const instanceStateChange = async (event) => {
console.log(
event['detail-type'],
event.detail['instance-id'],
event.detail.state,
)
}
cloudwatchEvent event options
The cloudwatchEvent event accepts these keys:
| Key | Type | Default | Description |
|---|---|---|---|
event | object | Required | The event pattern the rule matches |
enabled | boolean | true | Whether the rule is enabled |
name | string, 1–64 characters | Generated by CloudFormation | The rule name |
description | string, up to 512 characters | No description | The rule description |
input | object, or JSON string up to 8,192 characters | Not set: the function receives the event | A fixed payload passed instead of the event |
inputPath | JSONPath string, 1–256 characters | Not set | The part of the event passed to the function |
inputTransformer | object with inputTemplate and inputPathsMap | Not set | A payload built from values in the event |
Event patterns
The cloudwatchEvent event's event key is an EventBridge event pattern, written in YAML. The rule matches an event when every field in the pattern matches; a list matches any of its values. The pattern in the preceding example matches EC2 state-change events with the state pending.
Patterns also accept content filters, such as prefix, anything-but and numeric. This pattern matches every EC2 state change except to running:
functions:
instanceStateChange:
handler: handler.instanceStateChange
events:
- cloudwatchEvent:
event:
source:
- aws.ec2
detail-type:
- EC2 Instance State-change Notification
detail:
state:
- anything-but: running
For the pattern syntax, see Amazon EventBridge event patterns. For the events each AWS service sends, see Events from AWS services.
Input, input path and input transformer
By default, the function receives the whole event. To pass something else, set one of input, inputPath or inputTransformer on the cloudwatchEvent event; set at most one of them per event.
input passes a fixed payload instead of the event. An object is converted to JSON:
functions:
instanceStateChange:
handler: handler.instanceStateChange
events:
- cloudwatchEvent:
event:
source:
- aws.ec2
input:
stage: dev
action: audit
inputPath passes the part of the event that a JSONPath selects:
functions:
instanceStateChange:
handler: handler.instanceStateChange
events:
- cloudwatchEvent:
event:
source:
- aws.ec2
inputPath: '$.detail'
inputTransformer builds a payload from values in the event. inputPathsMap names the values with JSONPath, and inputTemplate (required) uses them as <name> placeholders:
functions:
instanceStateChange:
handler: handler.instanceStateChange
events:
- cloudwatchEvent:
event:
source:
- aws.ec2
inputTransformer:
inputPathsMap:
instance: '$.detail.instance-id'
eventTime: '$.time'
inputTemplate: '{"instance": "<instance>", "time": "<eventTime>"}'
Put a placeholder in quotes when its value is a string, so the result is valid JSON. For the template rules, see Amazon EventBridge input transformation.
Rule name and description
The cloudwatchEvent event's name and description set the rule's name and description:
functions:
instanceStateChange:
handler: handler.instanceStateChange
events:
- cloudwatchEvent:
name: ec2-pending-instances
description: Runs when an EC2 instance enters the pending state
event:
source:
- aws.ec2
detail-type:
- EC2 Instance State-change Notification
detail:
state:
- pending
name: 1 to 64 characters, using only ASCII letters, digits,.,-and_. It must be unique among the rules on the default event bus in the Region, so a fixed name stops you from deploying the same service to two stages in one Region; include the stage, as inec2-pending-${sls:stage}. Withoutname, CloudFormation generates a unique name.description: up to 512 characters.
See PutRule for the rule name rules.
Disable a rule
A cloudwatchEvent rule is enabled by default. To deploy the rule without triggering the function, set enabled: false:
functions:
instanceStateChange:
handler: handler.instanceStateChange
events:
- cloudwatchEvent:
enabled: false
event:
source:
- aws.ec2
Permissions for CloudWatch Events rules
For each cloudwatchEvent event, the Framework adds a lambda:InvokeFunction permission for events.amazonaws.com, limited to the rule's ARN. The function's execution role needs no extra permissions to receive events.
Troubleshooting CloudWatch Events rules
You can only set one of input, inputPath, or inputTransformer properties at the same time for cloudwatch events. ...
This happens when one cloudwatchEvent event sets more than one of input, inputPath and inputTransformer. Keep one of them; to send the same events with different payloads, add a second cloudwatchEvent event with the same event pattern.
Related
- EventBridge events, for custom event buses, schedules, retry policies and dead-letter queues
- CloudWatch settings in the serverless.yml reference
- Amazon EventBridge rules