Supported step actions for your workflow document

This section includes details for the step actions that Image Builder supports.

The following table shows which workflow stages support each step action. A check mark (X) indicates that you can use the step action in that stage. Image Builder restricts a few actions to specific stages: ExecuteComponents to the build and test stages, CollectImageScanFindings to the test stage, and DistributeImage, ModifyImageAttributes, ApplyImageConfigurations, and DistributeContainerImage to the distribution stage. You can use every other action in any stage.

ApplyImageConfigurations

Use this step action to apply various configurations and integrations to distributed AMIs, such as license configurations, launch template configurations, S3 export configurations, EC2 Fast Launch configurations, and Systems Manager parameter configurations. Configurations apply to distributed images only in the source account, except for SSM parameter configs which can be applied cross-account.

Default Timeout: 360 minutes

Max Timeout: 720 minutes (12 hours)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action. The distributedImages.$ input is required. The remaining rows describe the fields within each item of the configurations array.

Outputs: The following table includes outputs for this step action.

Example

Specify the step action in the workflow document.

- name: ApplyImageConfigurations
  action: ApplyImageConfigurations
  onFailure: Abort
  inputs:
    distributedImages.$: $.stepOutputs.DistributeImageStep.distributedImages
    configurations:
      - region: us-west-2
        licenseConfigurationArns:
          - arn:aws:license-manager:us-west-2:111122223333:license-configuration:lic-example

Use the output of the step action value in the workflow document.

$.stepOutputs.ApplyImageConfigurationsStep.configuredImages

BootstrapInstanceForContainer

This step action runs a service script to bootstrap the instance with minimum requirements to run container workflows. Image Builder uses the sendCommand in the Systems Manager API to run this script. For more information, see AWS Systems Manager Run Command.

Default Timeout: 60 minutes

Max Timeout: 720 minutes (12 hours)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

Example

Specify the step action in the workflow document.

- name: ContainerBootstrapStep
  action: BootstrapInstanceForContainer
  onFailure: Abort
  inputs:
      instanceId.$: $.stepOutputs.LaunchStep.instanceId

Use the output of the step action value in the workflow document.

$.stepOutputs.ContainerBootstrapStep.status

CollectImageMetadata

This step action is only valid for build workflows.

EC2 Image Builder runs AWS Systems Manager (Systems Manager) Agent on the EC2 instances it launches to build and test your image. Image Builder collects additional information about the instance used during the build phase with Systems Manager Inventory. This information includes the operating system (OS) name and version, as well as the list of packages and their respective versions as reported by your operating system.

Default Timeout: 30 minutes

Max Timeout: 720 minutes (12 hours)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: Image Builder rolls back any Systems Manager resources that were created during this step.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

Example

Specify the step action in the workflow document.

- name: CollectMetadataStep
  action: CollectImageMetadata
  onFailure: Abort
  inputs:
      instanceId: $.stepOutputs.LaunchStep.instanceId

Use output from the step action in the workflow document.

$.stepOutputs.CollectMetadataStep.osVersion

CollectImageScanFindings

If Amazon Inspector is enabled for your account and image scanning is enabled for your pipeline, this step action collects image scan findings reported by Amazon Inspector for your test instance. This step action is not available for build workflows.

Default Timeout: 120 minutes

Max Timeout: 720 minutes (12 hours)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

Example

Specify the step action in the workflow document.

- name: CollectFindingsStep
  action: CollectImageScanFindings
  onFailure: Abort
  inputs:
      instanceId.$: $.stepOutputs.LaunchStep.instanceId

Use the output of the step action value in the workflow document.

$.stepOutputs.CollectFindingsStep.status

CreateImage

This step action creates an image from a running instance with the Amazon EC2 CreateImage API. During the creation process, the step action waits as necessary to verify that the resources have reached the correct state before it continues.

Default Timeout: 720 minutes

Max Timeout: 3 days (259,200 seconds)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

Example

Specify the step action in the workflow document.

- name: CreateImageFromInstance
  action: CreateImage
  onFailure: Abort
  inputs:
      instanceId.$: "i-1234567890abcdef0"

Use the output of the step action value in the workflow document.

$.stepOutputs.CreateImageFromInstance.imageId

CreateImageFromIso

Use this step action to create an Amazon Machine Image (AMI) from an ISO disk image on the build instance. Use it in a build workflow when your source is an ISO file rather than a base AMI. Image Builder converts the ISO to an AMI and waits for the resources to reach the required state before it continues.

Default Timeout: 720 minutes

Max Timeout: 720 minutes (12 hours)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

Example

Specify the step action in the workflow document.

- name: CreateImageFromIsoStep
  action: CreateImageFromIso
  onFailure: Abort
  inputs:
      instanceId.$: $.stepOutputs.LaunchStep.instanceId

Use the output of the step action value in the workflow document.

$.stepOutputs.CreateImageFromIsoStep.amiName

DistributeContainerImage

Use this step action to distribute a container image that the build stage created to Amazon ECR repositories in the target Regions defined for the image. Use this action in a distribution workflow for container (DOCKER) images. It works as the container-image counterpart to DistributeImage.

This step action runs a Systems Manager command on the build instance to push the container image. The instance must have Docker and the AWS CLI installed. For more information, see BootstrapInstanceForContainer.

Default Timeout: 120 minutes

Max Timeout: 720 minutes (12 hours)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

Example

Specify the step action in the workflow document.

- name: DistributeContainer
  action: DistributeContainerImage
  onFailure: Abort
  inputs:
      instanceId.$: $.stepOutputs.LaunchStep.instanceId

Use the output of the step action value in the workflow document.

$.stepOutputs.DistributeContainer.status

DistributeImage

This step action distributes an AMI to the target Regions and accounts that you specify. It uses the distribution configuration from your CreateImage or CreateImagePipeline request, or custom distribution settings in the workflow that override the default configuration.

Default Timeout: 360 minutes

Max Timeout: 720 minutes (12 hours)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

Example

Specify the step action in the workflow document.

- name: DistributeImage
  action: DistributeImage
  onFailure: Abort
  inputs:
    distributions:
      - region.$: "$.parameters.SourceRegion"
        description: "AMI distribution to source region"
        amiTags:
          DistributionTest: "SourceRegion"
          WorkflowStep: "DistributeToSourceRegion"
          BuildDate: "{{imagebuilder:buildDate:yyyyMMHHss}}"
          BuildVersion: "{{imagebuilder:buildVersion}}"
		  

Use the output of the step action value in the workflow document.

$.stepOutputs.DistributeImageStep.distributedImages

ExecuteComponents

This step action runs components that are specified in the recipe for the current image being built. Build workflows run build components on the build instance. Test workflows only run test components on the test instance.

Image Builder uses the sendCommand in the Systems Manager API to run components. For more information, see AWS Systems Manager Run Command.

Default Timeout: 720 minutes

Max Timeout: 1 day (24 hours)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

Example

Specify the step action in the workflow document.

- name: ExecComponentsStep
  action: ExecuteComponents
  onFailure: Abort
  inputs:
      instanceId: $.stepOutputs.LaunchStep.instanceId

Use output from the step action in the workflow document.

$.stepOutputs.ExecComponentsStep.status

ExecuteStateMachine

This step action starts execution of an AWS Step Functions state machine from an Image Builder workflow. Image Builder uses the Step Functions StartExecution API to initiate the state machine and waits for it to complete. This is useful for integrating complex workflows, compliance validation, or certification processes into your image building pipeline.

For more information, see Learn about state machines in Step Functions in the AWS Step Functions Developer Guide.

Default Timeout: 6 hours

Max Timeout: 24 hours

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

IAM permissions required

Your custom execution role must have the following permissions to use this step action:

Example

Specify the step action in the workflow document.

- name: ValidateImageCompliance
  action: ExecuteStateMachine
  timeoutSeconds: 3600
  onFailure: Abort
  inputs:
    stateMachineArn: arn:aws:states:us-west-2:111122223333:stateMachine:ImageComplianceValidation
    input: |
      {
        "imageId": "{{ $.stepOutputs.CreateImageFromInstance.imageId }}",
        "region": "us-west-2",
        "complianceLevel": "high",
        "requiredScans": ["cve", "benchmark", "configuration"]
      }

Use the output of the step action value in the workflow document.

$.stepOutputs.ValidateImageCompliance.executionArn

LaunchInstance

Use this step action to launch an instance in your AWS account. The action waits until the instance meets the specified health check condition and the Systems Manager agent is running before proceeding to the next step. The launch action uses settings from your recipe and infrastructure configuration resources. For example, the instance type to launch comes from the infrastructure configuration. The output is the instance ID of the instance that launched.

The waitFor input configures the condition that satisfies the step completion requirement. The healthCheck input specifies the level of EC2 instance health validation that must pass before the step proceeds.

Default Timeout: 75 minutes

Max Timeout: 720 minutes (12 hours)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: For build instances, rollback performs the action that you have configured in your infrastructure configuration resource. By default, build instances are terminated if image creation fails. However, there is a setting in the infrastructure configuration to keep the build instance for troubleshooting.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

Example

Specify the step action in the workflow document.

- name: LaunchStep
  action: LaunchInstance
  onFailure: Abort
  inputs:
    healthCheck: "RUNNING"
    waitFor: ssmAgent

Use output from the step action in the workflow document.

$.stepOutputs.LaunchStep.instanceId

ModifyImageAttributes

Use this step action to modify attributes of distributed AMIs, such as launch permissions and other AMI attributes. It operates on AMIs that have been distributed to target Regions and accounts.

Default Timeout: 120 minutes

Max Timeout: 180 minutes (3 hours)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

Example

Specify the step action in the workflow document.

- name: ModifyImageAttributes
  action: ModifyImageAttributes
  onFailure: Abort
  inputs:
    distributedImages.$: $.stepOutputs.DistributeImageStep.distributedImages
    attributes:
      - region: us-west-2
        launchPermission:
          userIds:
            - "111122223333"

Use the output of the step action value in the workflow document.

$.stepOutputs.ModifyImageAttributesStep.modifiedImages

RegisterImage

This step action registers a new Amazon Machine Image (AMI) using the Amazon EC2 RegisterImage API. It allows you to create an AMI from an existing snapshot or set of snapshots, specifying various image attributes.

Default Timeout: 540 minutes

Max Timeout: 720 minutes (12 hours)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

IAM permissions required

Your custom execution role must have the following permissions to use this step action:

Example

Specify the step action in the workflow document.

- name: RegisterNewImage
  action: RegisterImage
  onFailure: Abort
  inputs:
    architecture: "x86_64"
    bootMode: "uefi"
    blockDeviceMapping:
      - DeviceName: "/dev/sda1"
        Ebs:
          SnapshotId: "snap-1234567890abcdef0"
          VolumeSize: 100
          VolumeType: "gp3"
    rootDeviceName: "/dev/sda1"
    virtualizationType: "hvm"

Use the output of the step action value in the workflow document.

$.stepOutputs.RegisterNewImage.imageId

Example with a SnapshotId from another step and snapshot tags included in the generated AMI

- name: CreateSnapshot
  action: RunCommand
  onFailure: Abort
  inputs:
    instanceId: "i-1234567890abcdef0"
    documentName: "AWS-RunShellScript"
    parameters:
      commands:
        - "aws ec2 create-snapshot --volume-id vol-1234567890abcdef0 --description 'Snapshot for AMI' --query 'SnapshotId' --output text"

- name: RegisterImageFromSnapshot
  action: RegisterImage
  onFailure: Abort
  inputs:
    architecture: "x86_64"
    bootMode: "uefi"
    blockDeviceMapping:
      - DeviceName: "/dev/sda1"
        Ebs:
          SnapshotId.$: "$.stepOutputs.CreateSnapshot.output[0]"
          VolumeSize: 100
          VolumeType: "gp3"
    includeSnapshotTags: true
    rootDeviceName: "/dev/sda1"
    virtualizationType: "hvm"

RunCommand

This step action runs a command document for your workflow. Image Builder uses the sendCommand in the Systems Manager API to run it for you. For more information, see AWS Systems Manager Run Command.

Default Timeout: 720 minutes

Max Timeout: 720 minutes (12 hours)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

Example

Specify the step action in the workflow document.

- name: RunCommandDoc
  action: RunCommand
  onFailure: Abort
  inputs:
    documentName: SampleDocument
    parameters:
        osPlatform: 
          - "linux"
    instanceId.$: $.stepOutputs.LaunchStep.instanceId

Use the output of the step action value in the workflow document.

$.stepOutputs.RunCommandDoc.status

RunSysPrep

This step action uses the sendCommand in the Systems Manager API to run the AWSEC2-RunSysprep document for Windows instances before the build instance shuts down for the snapshot. These actions follow AWS best practices for hardening and cleaning the image.

Default Timeout: 60 minutes

Max Timeout: 720 minutes (12 hours)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

Example

Specify the step action in the workflow document.

- name: RunSysprep
  action: RunSysPrep
  onFailure: Abort
  inputs:
      instanceId.$: $.stepOutputs.LaunchStep.instanceId

Use the output of the step action value in the workflow document.

$.stepOutputs.RunSysprep.status

SanitizeInstance

This step action runs the recommended sanitize script for Linux instances before the build instance shuts down for the snapshot. The sanitize script helps ensure that the final image follows security best practices, and that build artifacts or settings that should not carry over to your snapshot are removed. For more information about the script, see Required post-build clean up. This step action does not apply to container images.

Image Builder uses the sendCommand in the Systems Manager API to run this script. For more information, see AWS Systems Manager Run Command.

Default Timeout: 60 minutes

Max Timeout: 720 minutes (12 hours)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

Example

Specify the step action in the workflow document.

- name: SanitizeStep
  action: SanitizeInstance
  onFailure: Abort
  inputs:
      instanceId: $.stepOutputs.LaunchStep.instanceId

Use the output of the step action value in the workflow document.

$.stepOutputs.SanitizeStep.status

TerminateInstance

This step action terminates the instance that you specify with the instanceId input. By default, it initiates termination and moves to the next step without waiting. A background process handles cleanup if termination encounters EC2 service errors. To wait for full termination before proceeding, set the waitForTermination input to true.

Default Timeout: 30 minutes

Max Timeout: 720 minutes (12 hours)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action.

Outputs: There are no outputs for this step action.

Example

Specify the step action in the workflow document.

- name: TerminateInstance
  action: TerminateInstance
  onFailure: Continue
  inputs:
      instanceId.$: i-1234567890abcdef0
      waitForTermination: false

WaitForAction

This step action pauses the running workflow and waits to receive an external action from the Image Builder SendWorkflowStepAction API action. This step publishes an EventBridge event to your default EventBridge event bus with detail type EC2 Image Builder Workflow Step Waiting. The step can also send an SNS notification if you provide an SNS Topic ARN, or invoke a Lambda function asynchronously if you provide a Lambda function name.

How the pause and resume works

When a WaitForAction step runs, Image Builder sets the step status to WAITING and publishes an EventBridge event (detail type EC2 Image Builder Workflow Step Waiting). If you provide snsTopicArn, it also sends an Amazon SNS notification. If you provide lambdaFunctionName, it invokes that function asynchronously. The workflow stays paused until one of the following happens:

The reason that you pass to SendWorkflowStepAction is stored with the step and is available to later steps as the step's reason output.

Default Timeout: 3 days

Max Timeout: 7 days (604,800 seconds)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

IAM permissions required

Your custom execution role must have the following permissions to use this step action:

Example

Specify the step action in the workflow document with SNS notification.

- name: SendEventAndWait
  action: WaitForAction
  onFailure: Abort
  inputs:
    snsTopicArn: arn:aws:sns:us-west-2:111122223333:ExampleTopic

Specify the step action in the workflow document with Lambda function invocation.

- name: SendEventAndWaitWithLambda
  action: WaitForAction
  onFailure: Abort
  inputs:
    lambdaFunctionName: ExampleFunction
    payload: |
      {
        "imageId": "{{ $.stepOutputs.CreateImageFromInstance.imageId }}",
        "region": "us-west-2"
      }

Use the output of the step action value in the workflow document.

$.stepOutputs.SendEventAndWait.reason

WaitForSSMAgent

This step action waits for an EC2 instance to become manageable by AWS Systems Manager after expected periods of unresponsiveness. It's particularly valuable for workflows with known instance interruptions, such as system reboots, OS upgrades, or platform-specific operations that temporarily disconnect the instance from SSM. Image Builder monitors the instance until it regains SSM connectivity or times out.

Default Timeout: 60 minutes

Max Timeout: 180 minutes (3 hours)

You can override the default with timeoutSeconds, up to the maximum shown. A value above the maximum fails validation.

Rollback: There is no rollback for this step action.

Inputs: The following table includes supported inputs for this step action.

Outputs: The following table includes outputs for this step action.

Example

Specify the step action in the workflow document.

- name: WaitForInstanceAfterReboot
  action: WaitForSSMAgent
  onFailure: Abort
  timeoutSeconds: 900
  inputs:
    instanceId.$: $.stepOutputs.LaunchStep.instanceId

Use the output of the step action value in the workflow document.

$.stepOutputs.WaitForInstanceAfterReboot.status