Supported step actions for your workflow document

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

ApplyImageConfigurations

This step action applies 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

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: ApplyImageConfigurations
  action: ApplyImageConfigurations
  onFailure: Abort
  inputs:
    distributedImages.$: $.stepOutputs.DistributeImageStep.distributedImages

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

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

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

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

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

DistributeImage

This step action distributes an AMI to specified regions and accounts. It creates copies of the AMI in target regions and accounts based on the provided distribution configurationgiven in the requests for the CreateImage or CreateImagePipeline APIs or custom distribution settings provided in the workflow to override the settings in the distribution configuration.

Default Timeout: 360 minutes

Max Timeout: 720 minutes

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

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

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

This step action launches an instance in your AWS account and waits until the Systems Manager agent is running on the instance before moving on to the next step. The launch action uses settings from your recipe and infrastructure configuration resources that are associated with your image. For example, the instance type to launch comes from the infrastructure configuration. The output is the instance ID of the instance that it launched.

The waitFor input configures the condition that satisfies the step completion requirement.

Default Timeout: 60 minutes

Rollback: For build instances, rollback performs the action that you've 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:
    waitFor: ssmAgent

Use output from the step action in the workflow document.

$.stepOutputs.LaunchStep.instanceId

ModifyImageAttributes

This step action modifies 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

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

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: 720 minutes

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: 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: 12 hours

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

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

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 terminate the instance with the instance id that's passed in as input.

Default Timeout: 30 minutes

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

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.

Default Timeout: 3 days

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 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

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
  timeoutInSeconds: 900 # 15 minutes
  inputs:
    instanceId.$: $.stepOutputs.LaunchStep.instanceId

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

$.stepOutputs.WaitForInstanceAfterReboot.Status