Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Supported step actions for your workflow document

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

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

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

LaunchInstance

This step action launches an instance in your Amazon Web Services 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

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

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.

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

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

$.stepOutputs.SendEventAndWait.reason