When I first used CloudWatch Events I knew just enough to get the job done. As I've played with it more, I've realised that the official docs don't do a great job of explaining the underlying concepts involved, even though there's plenty to read there.
As with most people, I find a visual representation much more effective at illustrating concepts. I wrote this short post to prove to myself that I know what I'm talking about.
I'll start by explaining what CW Events is made up of, and then give an intermediate example of how they can be used to schedule a Lambda Function.
CloudWatch Events
Somewhat confusingly, Events are only part of CloudWatch Events (the service). A diagram explains it best:
Events
An event has a bunch of (optional) parameters.
Things generate CloudWatch Events. The "built-in" Events you get from AWS are:
- EC2 Instance state change
- Schedule (aka. Time)
- AWS API call (i.e. CloudTrail)
- AWS Console sign-in (i.e. CloudTrail)
- Auto Scaling
Obviously you and your applications can generate CW Events via the API (e.g. by using aws events put-events or the SDKs).
Rules
Rules filter or select Events for processing by Targets. They "glue" Events to Targets (which is where the interesting stuff happens).
A name is the only required parameter for a Rule, all the other parameters depend on the type of Rule. If accessing other AWS resources, it will require an IAM Role (via its ARN), if it's a scheduled event it will need an expression. Rules can be enabled or disabled without being deleted. Rules can transform the JSON payload that is passed on to the Targets.
Since Events are matched to a pattern, it means that many Rules can listen for many Events without impacting each other; One Event might match multiple Rules, and one Rule might match multiple Events.
Targets
Once an Event has passed a Rule (sometimes referred to as being "selected"), it is sent to a Target as a JSON object. The JSON might be transformed by the Target before it is used. This transformation can be extracting a specific part of the object, or replacing it with a predefined JSON payload.
This additional transformation step (which is optional) means that any logic specific to the Target is contained with the Target, which makes it easier for one Rule to trigger multiple Targets.
An Example
In a previous post I was setting up a CloudWatch Event to schedule a Lambda Function. In the context of CloudWatch Events, this is what the flow looks like:
This example uses a "Schedule" as the Event, which can be thought of as an Event that is triggered every minute (which is the minimum granularity provided by AWS - it used to be 5 minutes) and selected if it matches the shedule expression syntax.
My Rule in this case is a cron expression that only matches once per day at 0200 UTC (which is 1200 here in Sydney).
The Lambda Function is my Target, and is doing the actual work that I want to be scheduled. In practice I'm overriding the default Event JSON (which is blank in the case of a schedule) and passing my own message payload. This means I can trigger a specific action via a generic function.
If you have any questions about CloudWatch Events, or suggested improvements for this guide let me know.