Amazon EventBridge integration in Image Builder

Amazon EventBridge is a serverless event bus service that you can use to connect your Image Builder application with related data from other AWS services. In EventBridge, a rule matches incoming events and sends them to targets for processing. A single rule can send an event to multiple targets, and these events then run in parallel.

With EventBridge, you can automate your AWS services and respond automatically to system events such as application availability issues or resource changes. AWS services deliver events to EventBridge in near real time. You can set up rules that react to incoming events to initiate actions. For example, sending an event to a Lambda function when the status of an EC2 instance changes from pending to running. EventBridge calls these matching definitions event patterns. To create a rule based on an event pattern, see Creating Amazon EventBridge rules that react to events in the Amazon EventBridge User Guide.

Image Builder works with EventBridge in two independent directions. Choose the one that matches your goal:

Run a pipeline in response to an event (Image Builder as a target). EventBridge starts a pipeline build when an event matches a rule, or when a schedule fires.
React to what Image Builder reports (Image Builder as a source). Image Builder publishes events to the default event bus that you can match and route to your own targets.

For step-by-step procedures for both directions, see Use EventBridge with Image Builder pipelines. For the event catalog, see Event messages that Image Builder sends.

Actions that can be automatically initiated include the following:

Invoke an AWS Lambda function
Invoke Amazon EC2 Run Command
Relay the event to Amazon Kinesis Data Streams
Activate an AWS Step Functions state machine
Notify an Amazon SNS topic or an Amazon SQS queue

You can also set up scheduling rules for the default event bus to perform an action at regular intervals, such as running an Image Builder pipeline to refresh an image on a quarterly basis. There are two types of schedule expressions:

cron expressions – The following example of a cron expression schedules a task to run every day at noon UTC+0:

cron(0 12 * * ? *)

For more information about using cron expressions with EventBridge, see Cron expressions in the Amazon EventBridge User Guide.
rate expressions – The following example of a rate expression schedules a task to run every 12 hours:

rate(12 hour)

For more information about using rate expressions with EventBridge, see Rate expressions in the Amazon EventBridge User Guide.

For more information about how EventBridge rules integrate with Image Builder image pipelines, see Use EventBridge with Image Builder pipelines.

Note

A pipeline's built-in schedule and an EventBridge schedule rule are different mechanisms:

A pipeline schedule (schedule.scheduleExpression) is part of the pipeline resource. Image Builder evaluates it, can gate a build on dependency updates with pipelineExecutionStartCondition, and can auto-disable a failing pipeline with autoDisablePolicy.
An EventBridge schedule rule lives in EventBridge in your account and always starts a build when the schedule fires; it has no dependency gating and no auto-disable behavior.

Event messages that Image Builder sends

Image Builder sends events to the default EventBridge event bus when an Image Builder resource reaches a significant point in its lifecycle—for example, when an image changes state, a scan completes, a workflow step pauses for input, or a pipeline is automatically disabled. Every event uses the source aws.imagebuilder.

The following sections describe each event: when Image Builder sends it, the fields in the event detail, and the resource ARNs in the resources array. To act on these events, see React to events that Image Builder sends. The account IDs, Regions, ARNs, and timestamps in the examples are placeholders—replace them with your own.

Topics

EC2 Image Builder Image State Change
EC2 Image Builder CVE Detected
EC2 Image Builder Workflow Step Waiting
EC2 Image Builder Image Pipeline Automatically Disabled

EC2 Image Builder Image State Change

Image Builder sends this event when the state changes for an image resource during image creation. For example, when the image status changes from one state to another, as follows:

From building to testing
From testing to distribution
From testing to failed
From integrating to available


{
    "version": "0",
    "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "detail-type": "EC2 Image Builder Image State Change",
    "source": "aws.imagebuilder",
    "account": "111122223333",
    "time": "2024-01-18T17:50:56Z",
    "region": "us-west-2",
    "resources": ["arn:aws:imagebuilder:us-west-2:111122223333:image/cmkencryptedworkflowtest-a1b2c3d4-5678-90ab-cdef-EXAMPLE22222/1.0.0/1"],
    "detail": {
        "previous-state": {
            "status": "TESTING"
        },
        "state": {
            "status": "AVAILABLE"
        }
    }
}

Image Builder sends this event each time an image resource changes state during image creation, across the build transitions shown above.

The event detail contains the following fields:

Field	Description
`previous-state.status`	The image status before the change (for example, `TESTING`).
`state.status`	The new image status (for example, `AVAILABLE`).

The build-transition status values are BUILDING, TESTING, DISTRIBUTING, INTEGRATING, AVAILABLE, CANCELLED, and FAILED.

The resources array contains the ARN of the image resource that changed state.

EC2 Image Builder CVE Detected

If you have CVE detection enabled for your image, Image Builder sends a message with the results whenever an image scan completes.


{
    "version": "0",
    "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "detail-type": "EC2 Image Builder CVE Detected",
    "source": "aws.imagebuilder",
    "account": "111122223333",
    "time": "2023-03-01T16:59:09Z",
    "region": "us-east-1",
    "resources": [
        "arn:aws:imagebuilder:us-east-1:111122223333:image/test-image/1.0.0/1",
        "arn:aws:imagebuilder:us-east-1:111122223333:image-pipeline/test-pipeline"
    ],
    "detail": {
        "resource-id": "i-1234567890abcdef0",
        "finding-severity-counts": {
            "all": 0,
            "critical": 0,
            "high": 0,
            "medium": 0
        }
    }
}

Image Builder sends this event when an image scan completes, and only when you enable image scanning (Amazon Inspector) for the image. If scanning is off, Image Builder doesn't send this event. To turn on scanning, see Configure security scans for Image Builder images in the AWS Management Console.

The event detail contains the following fields:

Field	Description
`resource-id`	The ID of the Amazon EC2 test instance that Image Builder scanned.
`finding-severity-counts.all`	Total number of findings across the reported severities.
`finding-severity-counts.critical`	Number of critical-severity findings.
`finding-severity-counts.high`	Number of high-severity findings.
`finding-severity-counts.medium`	Number of medium-severity findings.

Important

finding-severity-counts reports critical, high, and medium counts plus the all total. It does not report low, informational, or untriaged findings. To review the full set of findings, see the security findings in the Image Builder console or in Amazon Inspector.

The resources array contains the ARN of the image resource, and the ARN of the image pipeline when the scan ran from a pipeline.

EC2 Image Builder Workflow Step Waiting

Image Builder sends a message when a WaitForAction workflow step pauses to wait for an asynchronous action to complete.


{
    "version": "0",
    "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "detail-type": "EC2 Image Builder Workflow Step Waiting",
    "source": "aws.imagebuilder",
    "account": "111122223333",
    "time": "2024-01-18T16:54:44Z",
    "region": "us-west-2",
    "resources": ["arn:aws:imagebuilder:us-west-2:111122223333:image/workflowstepwaitforactionwithvalidsnstopictest-a1b2c3d4-5678-90ab-cdef-EXAMPLE22222/1.0.0/1", "arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/build-workflow-a1b2c3d4-5678-90ab-cdef-EXAMPLE33333/1.0.0/1"],
    "detail": {
        "workflow-execution-id": "wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
        "workflow-step-execution-id": "step-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "workflow-step-name": "TestAutoSNSStop"
    }
}

Image Builder sends this event when a WaitForAction workflow step pauses to wait for your response. The workflow stays paused until you respond or the step times out.

The event detail contains the following fields:

Field	Description
`workflow-execution-id`	The ID of the running workflow that contains the paused step.
`workflow-step-execution-id`	The ID of the specific step execution that is waiting.
`workflow-step-name`	The name of the `WaitForAction` step, as defined in the workflow document.

The resources array contains the ARN of the image resource and the ARN of the workflow.

To respond, call SendWorkflowStepAction with the workflow-step-execution-id from the event and an action of RESUME to continue, or STOP to end the build. See WaitForAction. To drive this from an event automatically, see React to events that Image Builder sends.

EC2 Image Builder Image Pipeline Automatically Disabled

If you've configured the autoDisablePolicy for your pipeline, then Image Builder disables the pipeline and sends an event message to EventBridge when the number of consecutive scheduled pipeline execution failures exceeds the maximum number that's allowed per the policy.


{
    "version": "0",
    "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "detail-type": "EC2 Image Builder Image Pipeline Automatically Disabled",
    "source": "aws.imagebuilder",
    "account": "111122223333",
    "time": "2025-09-18T16:54:44Z",
    "region": "us-west-2",
    "resources": ["arn:aws:imagebuilder:us-west-2:111122223333:image-pipeline/disabled-image-pipeline-name"],
    "detail": {
        "consecutive-failures": "5"
    }
}

If you configure an autoDisablePolicy on a pipeline's schedule, Image Builder counts consecutive failures of scheduled builds. When the count reaches the policy's failureCount, Image Builder disables the pipeline and sends this event.

The event detail contains the following fields:

Field	Description
`consecutive-failures`	The number of consecutive scheduled-build failures that triggered the auto-disable.

The resources array contains the ARN of the pipeline that was disabled.

Note

Only scheduled builds count toward the total. A manual build that fails does not increase it; a manual or scheduled build that succeeds—and creating or updating the pipeline—resets it to zero. See autoDisablePolicy in the EC2 Image Builder API Reference.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Integrate products and services

Amazon Inspector