Use EventBridge with Image Builder pipelines
AWS and partner services stream events to Amazon EventBridge event buses in near real time. You can also send your own custom events. Event buses use rules to route each event to one or more targets.
Image Builder works with EventBridge in two independent directions:
-
Start a pipeline build from a rule. You can set an Image Builder pipeline as a rule target, so EventBridge runs the pipeline when an event matches the rule or when a schedule fires. See Trigger a pipeline build on a schedule and Trigger a pipeline build from an event pattern.
-
React to events that Image Builder sends. Image Builder publishes events to the default event bus when significant changes occur—for example, when an image becomes
AVAILABLEor a scan detects CVEs. You can match these events with a rule and route them to targets such as a Lambda function or an Amazon SNS topic to start your own automations. See React to events that Image Builder sends.
For more information about the events that Image Builder sends and the fields in each event, see Event messages that Image Builder sends.
Note
Event buses are Region-specific. A rule and the resources it invokes are typically in the same Region; to route across Regions, target an event bus in the destination Region. Image Builder publishes its events to the default event bus in the Region where the build runs.
Contents
EventBridge terms
The following terms help you understand how EventBridge integrates with your Image Builder pipelines.
- Event
-
Describes a change in an environment that might affect one or more application resources. The environment can be an AWS environment, a SaaS partner service or application, or one of your applications or services. You can also set up scheduled events on a timeline.
- Event bus
-
A pipeline that receives event data from applications and services.
- Source
-
The service or application that sent the event to the event bus.
- Target
-
A resource or endpoint that EventBridge invokes when it matches a rule, delivering data from the event to the target.
- Rule
-
A rule matches incoming events and sends them to targets for processing. A single rule can send an event to multiple targets, which can then run in parallel. Rules are based either on an event pattern or a schedule.
- Pattern
-
An event pattern defines the event structure and the fields that a rule matches in order to initiate the target action.
- Schedule
-
Schedule rules perform an action on a schedule, such as running an Image Builder pipeline to refresh an image on a quarterly basis. There are two types of schedule expressions:
-
Cron expressions – Match specific scheduling criteria using the cron syntax that can outline simple criteria; for example, running weekly on a specific day. You can also establish more complex criteria, such as running quarterly on the fifth day of the month, between 2 AM and 4 AM.
-
Rate expressions – Specify a regular interval when the target is invoked, such as every 12 hours.
-
View EventBridge rules for your Image Builder pipeline
The EventBridge rules tab in the Image Builder Image pipelines detail page displays EventBridge event buses that your account has access to, and the rules for the selected event bus that apply to the current pipeline. This tab also links directly to the EventBridge console for creating new resources.
Actions that link to the EventBridge console
-
Create event bus
-
Create rule
To learn more about EventBridge, see the following topics in the Amazon EventBridge User Guide.
Trigger a pipeline build on a schedule
Set an Image Builder pipeline as the target of an EventBridge schedule rule to refresh an image on a regular cadence. The following example creates a rule that starts a pipeline build every 90 days.
Note
A pipeline can also carry its own built-in schedule (a cron or rate expression stored on the pipeline). That schedule is managed by Image Builder and is separate from any EventBridge rule:
-
Use the pipeline schedule for a simple recurring rebuild. It can also gate builds on dependency updates and auto-disable a failing pipeline. See
Schedulein the EC2 Image Builder API Reference. -
Use an EventBridge rule to start a build from an event pattern, or to fan one trigger out to multiple targets.
Note
To learn more about settings for rate expression rules that are not covered in this example, see Rate expressions in the Amazon EventBridge User Guide.
Trigger a pipeline build from an event pattern
Instead of a schedule, you can start a pipeline build when an event matches a pattern. Create a rule with an event pattern, then add your pipeline as the target (with the same IAM role described in Trigger a pipeline build on a schedule).
The following example starts a build whenever a specific base image becomes
AVAILABLE—for example, to chain a dependent image build after its base
image finishes. The resources prefix scopes the rule to the base image so
that it matches only that image, and not the dependent pipeline's own output:
{ "source": ["aws.imagebuilder"], "detail-type": ["EC2 Image Builder Image State Change"], "detail": { "state": { "status": ["AVAILABLE"] } }, "resources": [{ "prefix": "arn:aws:imagebuilder:us-west-2:111122223333:image/my-base-image/" }] }
Important
Scope the event pattern to the base image, as shown by the resources
prefix in this example. A pattern that matches every AVAILABLE image in
the account also matches the dependent pipeline's own output image, which starts the
pipeline again and can create an endless build loop. Filter on the specific base
image name or ARN prefix so the rule matches only the image you intend.
For the events you can match and their fields, see Event messages that Image Builder sends.
React to events that Image Builder sends
Image Builder publishes events to the default event bus when your resources reach significant points—for example, when an image changes state, a scan completes, a workflow step pauses for input, or a pipeline is automatically disabled. You can match these events with a rule and route them to a target to start your own automation. Common patterns include:
-
Notify a team through an Amazon SNS topic when an image becomes
AVAILABLEorFAILED. -
Invoke a Lambda function to register a new AMI in a parameter store, start external compliance tests, or update a deployment pipeline.
-
Alert on security findings when a scan reports critical CVEs.
-
Drive an approval workflow when a
WaitForActionworkflow step pauses a build.
To act on an event that Image Builder sends, create a rule whose event pattern matches the
event source (aws.imagebuilder) and
detail-type, and optionally narrows on fields inside
detail. Then add the target that runs your automation.
Example: Notify on image completion
(AVAILABLE or FAILED)
{ "source": ["aws.imagebuilder"], "detail-type": ["EC2 Image Builder Image State Change"], "detail": { "state": { "status": ["AVAILABLE", "FAILED"] } } }
Example: Alert only when a scan finds critical CVEs
Use a numeric matcher so that clean scans don't trigger the rule:
{ "source": ["aws.imagebuilder"], "detail-type": ["EC2 Image Builder CVE Detected"], "detail": { "finding-severity-counts": { "critical": [{ "numeric": [">", 0] }] } } }
Note
When you match the EC2 Image Builder Workflow Step Waiting event, your
target can call SendWorkflowStepAction with the
workflow-step-execution-id from the event and an action
of RESUME or STOP. See WaitForAction.
