# Manage build and test workflows for Image Builder images
An image workflow defines the sequence of steps that EC2 Image Builder performs during the build, test, and distribution stages of the image creation process. This is part of the overall Image Builder workflow framework.
**Image workflow benefits**
+ With image workflows, you have more flexibility, visibility, and control over the image creation process.
+ You can add customized workflow steps when you define your workflow document, or you can choose to use the Image Builder default workflow.
+ You can exclude workflow steps that are included in default image workflows.
+ You can create test-only workflows that skip the build process entirely. You can do the same to create build-only or distribution-only workflows.
**Note**
You can't modify an existing workflow, but you can clone it or create a new version.
**Topics**
+ [Workflow framework: Stages](#wf-stages)
+ [Service access](#wf-service-access)
+ [Use managed workflows for your images](#use-managed-workflows)
+ [List image workflows](list-image-workflows.md)
+ [Create an image workflow](image-workflow-create-resource.md)
+ [Create a YAML workflow document](image-workflow-create-document.md)
## Workflow framework: Stages
To customize image workflows, it's important to understand the workflow stages that make up the image creation workflow framework.
The image creation workflow framework includes the following distinct stages.
1. **Build stage** (pre-snapshot) – During the build stage, you make changes to the Amazon EC2 build instance that's running your base image, to create the baseline for your new image. For example, your recipe can include components that install an application or modify the operating system firewall settings.
After this stage completes successfully, Image Builder creates a snapshot or container image that it uses for the test stage and beyond.
1. **Test stage** (post-snapshot) – During the test stage, there are some differences between images that create AMIs and container images. For AMI workflows, Image Builder launches an EC2 instance from the snapshot that it created as the final step of the build stage. Tests run on the new instance to validate settings and ensure that the instance is functioning as expected. For container workflows, the tests run on the same instance that was used for building.
1. **Distribution stage** (post-build) – During the distribution stage, once the image build is complete and has successfully passed all tests, the output image undergoes various phases of distribution. These phases encompass AMI copy operations, image attribute modifications, image sharing, and other related distribution steps.
## Service access
To run image workflows, Image Builder needs permission to perform workflow actions. You can specify the [AWSServiceRoleForImageBuilder](security-iam-awsmanpol.md#sec-iam-manpol-AWSServiceRoleForImageBuilder) service-linked role, or you can specify your own custom role for service access, as follows.
+ **Console** – In the pipeline wizard **Step 3 Define image creation process**, select the service-linked role or your own custom role from the **IAM role** list in the **Service access** panel.
+ **Image Builder API** – In the [CreateImage](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateImage.html) action request, specify the service-linked role or your own custom role as the value for the `executionRole` parameter.
To learn more about how to create a service role, see [Creating a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in the *AWS Identity and Access Management User Guide*.
## Use managed workflows for your images
Managed workflows are created and maintained by AWS. When you use managed workflows in your image pipelines or for one-off image creation, you can select the Amazon Resource Name (ARN) of the managed workflow that you want to use. Amazon provides the latest versions that have patches and other updates applied. To get a list of managed workflows, see [List image workflows](list-image-workflows.md), and filter on **Owner = Amazon** (console).
# List image workflows
On the **Image workflows** list page in the Image Builder console, you can get a list of the image workflow resources that you own or have access to, along with some key details about these resources. You can also use commands or actions with the Image Builder API, SDKs, or AWS CLI to list image workflows in your account.
You can use one of the following methods to list image workflow resources that you own or have access to. For the API action, see [ListWorkflows](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflows.html) in the *EC2 Image Builder API Reference*. For the associated SDK request, refer to the [See Also](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflows.html#API_ListWorkflows_SeeAlso) link on the same page.
You can filter on the following details to streamline the list of results. For example, if you filter on **Owner = Amazon** in the console, the list displays only AWS managed workflows.
+ Workflow
+ Version
+ Type
+ Owner
------
#### [ Console ]
**Workflow details**
Details on the **Image workflows** list page in the Image Builder console include the following:
+ **Workflow** – The name of the most recent version of the image workflow resource. In the Image Builder console, the **Workflow** column links to the workflow detail page.
+ **Version** – The most recent version of the image workflow resource.
+ **Type** – The workflow type: `BUILD`, `TEST`, or `DISTRIBUTION`.
+ **Owner** – The owner of the workflow resource.
+ **Creation time** – The date and time when Image Builder created the most recent version of the image workflow resource.
+ **ARN** – The Amazon Resource Name (ARN) of the current version of the image workflow resource.
**List image workflows**
To list image workflow resources in the Image Builder console, perform the following steps:
1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/).
1. Choose **Image workflows** from the navigation pane.
**Filter results**
On the **Image workflows** list page, you can search for specific image workflows to filter your results. The following filters are available for image workflows:
`Workflow`
You can enter all or part of a workflow name to streamline results. The default is to show all workflows in the list.
`Version`
You can enter all or part of a version number to streamline results. The default is to show all versions in the list.
`Type`
You can filter by the workflow type or view all types. The default is to show all workflow types in the list.
+ *BUILD*
+ *TEST*
+ *DISTRIBUTION*
`Owner`
When you select the owner filter from the search bar, Image Builder shows a list of the owners for the image workflows in your account. You can select an owner from the list to streamline results. The default is to show all owners in the list.
+ *AWS account* – The account that owns the workflow resource.
+ *Amazon* – Workflow resources that Amazon owns and manages.
------
#### [ AWS CLI ]
When you run the **[list-workflows](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/list-workflows.html)** command in the AWS CLI, you can get a list of image workflows that you own or have access to.
The following command example shows how to use the **list-workflows** command without filters to list all of the Image Builder image workflow resources that you own or have access to.
**Example: list all image workflows**
```
aws imagebuilder list-workflows
```
**Output:**
```
{
"workflowVersionList": [
{
"name": "example-test-workflow",
"dateCreated": "2023-11-21T22:53:14.347Z",
"version": "1.0.0",
"owner": "111122223333",
"type": "TEST",
"arn": "arn:aws:imagebuilder:us-west-2:111122223333:workflow/test/example-test-workflow/1.0.0"
},
{
"name": "example-build-workflow",
"dateCreated": "2023-11-20T12:26:10.425Z",
"version": "1.0.0",
"owner": "111122223333",
"type": "BUILD",
"arn": "arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/example-build-workflow/1.0.0"
},
{
"name": "example-distribution-workflow",
"dateCreated": "2025-11-19T10:25:10.425Z",
"version": "1.0.0",
"owner": "111122223333",
"type": "DISTRIBUTION",
"arn": "arn:aws:imagebuilder:us-west-2:111122223333:workflow/distribution/example-distribution-workflow/1.0.0"
}
]
}
```
When you run the **list-workflows** command, you can apply filters to streamline the results, as the following example shows. For more information about how to filter your results, see the [list-workflows](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/list-workflows.html) command in the *AWS CLI Command Reference*.
**Example: filter for build workflows**
```
aws imagebuilder list-workflows --filters name="type",values="BUILD"
```
**Output:**
```
{
"workflowVersionList": [
{
"name": "example-build-workflow",
"dateCreated": "2023-11-20T12:26:10.425Z",
"version": "1.0.0",
"owner": "111122223333",
"type": "BUILD",
"arn": "arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/example-build-workflow/1.0.0"
}
]
}
```
------
# Create an image workflow
When you create an image workflow, you have more control over your image creation process. You can specify what workflow runs when Image Builder builds your image, and what workflows run when it tests the image. You can also specify a customer managed key to encrypt your workflow resources. To learn more about encryption for your workflow resources, see [Encryption and key management in Image Builder](data-protection.md#ib-encryption).
For image creation, you can specify one build stage workflow, and one or more test stage workflows. You can even skip the build or test stage entirely, depending on your needs. You configure the actions that your workflow takes in the YAML definition document that your workflow uses. For more information about syntax for your YAML document, see [Create a YAML workflow document](image-workflow-create-document.md).
For steps to create a new build or test workflow select the tab that matches the environment you'll use.
------
#### [ AWS Management Console ]
You can use the following process to create a new workflow in the Image Builder console.
1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/).
1. Choose **Image workflows** from the navigation pane. This displays a list of image workflows that your account owns or has access to.
**Note**
You'll always see the Amazon managed workflow resources that Image Builder uses for its default workflows in your list. To view details for those workflows, you can select the **Workflow** link.
1. To create a new workflow, choose **Create image workflow**. This displays the **Create image workflow** page.
1. Configure the details for your new workflow. To create a build workflow, select the **Build** option near the top of the form. To create a test workflow, select the **Test** option near the top of the form. Image Builder populates the **Templates** list based on this option. All other steps are the same for build and test workflows.
**General**
The general section includes settings that apply to your workflow resource, such as name and description. The general settings include the following:
+ **Image workflow name** (required) – The name for your image workflow. The name must be unique in your account. The name can be up to 128 characters in length. Valid characters include letters, numbers, spaces, `-`, and `_`.
+ **Version** (required) – The semantic version for the workflow resource to create (*major.minor.patch*).
+ **Description** (optional) – Optionally add a description for your workflow.
+ **KMS key** (optional) – You can encrypt your workflow resources with an customer managed key. For more information, see [Encrypt image workflows with a customer managed key](data-protection.md#ib-workflow-encrypt-cmk).
**Definition document**
The YAML workflow document contains all of the configuration for your workflow.
**Get started**
+ To start with an Image Builder default template as a baseline for your workflow, select the **Start from templates** option. This option is selected by default. After you choose what template to use from the **Templates** list, this copies the default configuration from the template you selected into the **Content** for your new workflow document, where you can make changes.
+ To define your workflow document from scratch, select the **Start from scratch** option. This populates the **Content** with a short outline of some important parts of the document format to help you get started.
The **Content** panel includes a status bar at the bottom that shows warnings or errors for your YAML document. For more information about how to create a YAML workflow document, see [Create a YAML workflow document](image-workflow-create-document.md).
1. When you've completed your workflow, or if you want to save progress and come back to it later, choose **Create workflow**.
------
#### [ AWS CLI ]
Before you run the **[create-workflow](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-workflow.html)** command in the AWS CLI, you must create the YAML document that contains all of the configuration for your workflow. For more information, see [Create a YAML workflow document](image-workflow-create-document.md).
The following example shows how to create a build workflow with the [create-workflow](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-workflow.html) AWS CLI command. The `--data` parameter refers to a YAML document that contains the build configuration for the workflow you create.
**Example: Create workflow**
```
aws imagebuilder create-workflow --name example-build-workflow --semantic-version 1.0.0 --type BUILD --data file://example-build-workflow.yml
```
**Output:**
```
{
"workflowBuildVersionArn": "arn:aws:imagebuilder:us-west-2:111122223333:workflow/build/example-build-workflow/1.0.0/1",
"clientToken": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222"
}
```
The following example shows how to create a test workflow with the [create-workflow](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-workflow.html) AWS CLI command. The `--data` parameter refers to a YAML document that contains the build configuration for the workflow you create.
**Example: Create test workflow**
```
aws imagebuilder create-workflow --name example-test-workflow --semantic-version 1.0.0 --type TEST --data file://example-test-workflow.yml
```
**Output:**
```
{
"workflowBuildVersionArn": "arn:aws:imagebuilder:us-west-2:111122223333:workflow/test/example-test-workflow/1.0.0/1",
"clientToken": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222"
}
```
------
# Create a YAML workflow document
The YAML format definition document configures input, output, and workflow steps for the build and test stages of the image build process. You can start from templates that include standardized steps, or you can start from scratch to define your own workflow. Whether you use a template or start from scratch, you can customize the workflow to fit your needs.
## Structure of a YAML workflow document
The YAML workflow document that Image Builder uses to perform image build and test actions is structured as follows.
+ [Workflow document identification](#wfdoc-struct-ident)
+ [Workflow document input parameters](#wfdoc-struct-param)
+ [Workflow document steps](#wfdoc-struct-step)
+ [Workflow document outputs](#wfdoc-struct-output)
### Workflow document identification
Uniquely identifies the workflow. This section can include the following attributes.
| Field | Description | Type | Required |
| --- | --- | --- | --- |
| name | The name of the workflow document. | String | No |
| description | The document description. | String | No |
| schemaVersion | The document schema version, currently 1.0. | String | Yes |
**Example**
```
---
name: sample-test-image
description: Workflow for a sample image, with extra configuration options exposed through workflow parameters.
schemaVersion: 1.0
```
### Workflow document input parameters
This part of the workflow document defines input parameters that the caller can specify. If you don't have any parameters, you can leave this section out. If you do specify parameters, each parameter can include the following attributes.
| Field | Description | Type | Required | Constraints |
| --- | --- | --- | --- | --- |
| name | The name of the parameter. | String | Yes | |
| description | The parameter description. | String | No | |
| default | The default value of the parameter, if no value is provided. If you don't include a default value in the parameter definition, the parameter value is required at runtime. | Matches the parameter data type. | No | |
| type | The data type of the parameter. If you don't include the data type in the parameter definition, the parameter type defaults to a string value required at runtime. | String | Yes | The data type of the parameter must be one of the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/image-workflow-create-document.html) |
**Example**
Specify the parameter in the workflow document.
```
parameters:
- name: waitForActionAtEnd
type: boolean
default: true
description: "Wait for an external action at the end of the workflow"
```
Use the parameter value in the workflow document.
```
$.parameters.waitForActionAtEnd
```
### Workflow document steps
Specifies up to 15 step actions for the workflow. Steps run in the order that they're defined within the workflow document. In case of failure, a rollback runs in reverse order, starting with the step that failed, and working backward through prior steps.
Each step can refer to the output of any prior step actions. This is known as *chaining, or referencing*. To refer to output from a prior step action, you can use a JSONPath selector. For example:
```
$.stepOutputs.step-name.output-name
```
For more information, see [Use dynamic variables in your workflow document](wfdoc-dynamic-vars.md).
**Note**
Even though the step itself doesn't have an output attribute, any output from a step action is included in `stepOutput` for the step.
Each step can include the following attributes.
| Field | Description | Type | Required | Default value | Constraints |
| --- | --- | --- | --- | --- | --- |
| action | The workflow action that this step performs. | String | Yes | | Must be a supported step action for Image Builder workflow documents. |
| `if`, followed by a set of conditional statements that modify the `if` operator. | Conditional statements add flow of control decision points to the body of your workflow steps. | Dict | No | | Image Builder supports the following conditional statements as modifiers to the `if` operator: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/image-workflow-create-document.html) |
| description | The step description. | String | No | | Empty strings are not allowed. If included, length must be 1-1024 characters. |
| inputs | Contains parameters that the step action needs to run. You can specify key values as static values, or with a JSONPath variable that resolves to the correct data type. | Dict | Yes | | |
| name | The name of the step. This name must be unique within the workflow document. | String | Yes | | Length must be between 3-128 characters. Can include alphanumeric characters and `_`. No spaces. |
| onFailure | Configures the action to take if the step fails, as follows. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/image-workflow-create-document.html) | String | No | `Abort` | `Abort` \$1 `Continue` |
| rollbackEnabled | Configures whether the step will be rolled back if a failure occurs. You can use a static Boolean value or a dynamic JSONPath variable that resolves to a Boolean value. | Boolean | No | `true` | `true` \$1 `false` \$1 or a JSONPath variable that resolves to true or false. |
| timeoutSeconds | The maximum time, in seconds, that the step runs before failing and retrying, if retries apply. | Integer | No | Depends on the default defined for the step action, if applicable. | Cannot be more than the max timeout of the step action |
| waitSeconds | The time, in seconds, for which the step execution will pause. | Integer | No | 0 | Cannot be more than timeoutSeconds of the step action |
**Example**
```
steps:
- name: LaunchTestInstance
action: LaunchInstance
onFailure: Abort
inputs:
waitFor: "ssmAgent"
- name: ApplyTestComponents
action: ExecuteComponents
onFailure: Abort
inputs:
instanceId.$: "$.stepOutputs.LaunchTestInstance.instanceId"
- name: TerminateTestInstance
action: TerminateInstance
onFailure: Continue
inputs:
instanceId.$: "$.stepOutputs.LaunchTestInstance.instanceId"
- name: WaitForActionAtEnd
action: WaitForAction
if:
booleanEquals: true
value: "$.parameters.waitForActionAtEnd"
```
### Workflow document outputs
Defines outputs for the workflow. Each output is a key value pair that specificies the name of the output and the value. You can use outputs to export data at runtime that subsequent workflows can use. This section is optional.
Each output that you define includes the following attributes.
| Field | Description | Type | Required |
| --- | --- | --- | --- |
| name | The name of the output. The name must be unique across the workflows that you include in your pipeline. | String | Yes |
| value | The value for the output. The value of the string can be a dyanmic variable, such as an output file from a step action. For more information, see [Use dynamic variables in your workflow document](wfdoc-dynamic-vars.md). | String | Yes |
**Example**
Create an output image ID for the workflow document with step output from the `createProdImage` step.
```
outputs:
- name: 'outputImageId'
value: '$.stepOutputs.createProdImage.imageId'
```
Refer to the workflow output in the next workflow.
```
$.workflowOutputs.outputImageId
```
# Supported step actions for your workflow document
This section includes details for the step actions that Image Builder supports.Terms used in this section
AMI
Amazon Machine Image
ARN
Amazon Resource Name
**Topics**
+ [ApplyImageConfigurations](#wfdoc-step-action-apply-image-configurations)
+ [BootstrapInstanceForContainer](#wfdoc-step-action-bootstrap-container)
+ [CollectImageMetadata](#wfdoc-step-action-collect-image-metadata)
+ [CollectImageScanFindings](#wfdoc-step-action-collect-findings)
+ [CreateImage](#wfdoc-step-action-create-img-from-inst)
+ [DistributeImage](#wfdoc-step-action-distribute-image)
+ [ExecuteComponents](#wfdoc-step-action-exec-components)
+ [ExecuteStateMachine](#wfdoc-step-action-exec-state-machine)
+ [LaunchInstance](#wfdoc-step-action-launch-instance)
+ [ModifyImageAttributes](#wfdoc-step-action-modify-image-attributes)
+ [RegisterImage](#wfdoc-step-action-register-image)
+ [RunCommand](#wfdoc-step-action-run-command)
+ [RunSysPrep](#wfdoc-step-action-run-sysprep)
+ [SanitizeInstance](#wfdoc-step-action-sanitize-instance)
+ [TerminateInstance](#wfdoc-step-action-terminate-instance)
+ [WaitForAction](#wfdoc-step-action-waitfor)
+ [WaitForSSMAgent](#wfdoc-step-action-wait-for-ssm-agent)
## 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.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| region | The image region. | String | Yes | | |
| licenseConfigurationArns | The license configuration ARN for the image. | Array | No | | |
| launchTemplateConfigurations | | Array | No | | |
| launchTemplateConfigurations:launchTemplateId | The launch template ID to apply to the image. | String | Yes if launchTemplateConfigurations is specified | | |
| launchTemplateConfigurations:accountId | The launch template account IDs to apply to the image. | String | No | | |
| launchTemplateConfigurations:setDefaultVersion | The launch template default version setting for the image. | Boolean | No | | |
| s3ExportConfiguration | | Array | No | | |
| s3ExportConfiguration:roleName | The S3 export configuration role name for the image. | String | Yes if s3ExportConfiguration is specified | | |
| s3ExportConfiguration:diskImageFormat | The S3 export configuration disk image format for the image. | String | Yes if s3ExportConfiguration is specified | | Allowed values - VMDK\$1RAW\$1VHD |
| s3ExportConfiguration:s3Bucket | The S3 export configuration bucket name for the image. | String | Yes if s3ExportConfiguration is specified | | |
| s3ExportConfiguration:s3Prefix | The S3 export configuration bucket prefix for the image. | String | No | | |
| fastLaunchConfigurations | The EC2 Fast Launch configuration for the image. | Array | No | | |
| fastLaunchConfigurations:enabled | EC2 Fast Launch enabled/disabled for the image. | Boolean | Yes if fastLaunchConfigurations is specified | | |
| fastLaunchConfigurations:snapshotConfiguration | EC2 Fast Launch enabled/disabled for the image. | Map | No | | |
| fastLaunchConfigurations:snapshotConfiguration:targetResourceCount | EC2 Fast Launch target resource count for the image. | Integer | No | | |
| fastLaunchConfigurations:maxParallelLaunches | EC2 Fast Launch maximum parallel launches for the image. | Integer | No | | |
| fastLaunchConfigurations:launchTemplate | | | No | | |
| fastLaunchConfigurations:launchTemplate:launchTemplateId | EC2 Fast Launch launch template ID for the image. | String | No | | |
| fastLaunchConfigurations:launchTemplate:launchTemplateName | EC2 Fast Launch launch template name for the image. | String | No | | |
| fastLaunchConfigurations:launchTemplate:launchTemplateVersion | EC2 Fast Launch launch template version for the image. | String | No | | |
| ssmParameterConfigurations | The SSM Parameter configuration for the image. | Map | No | | |
| ssmParameterConfigurations:amiAccountId | The SSM Parameter AMI account ID for the image. | String | No | | |
| ssmParameterConfigurations:parameterName | The SSM Parameter name for the image. | String | Yes if ssmParameterConfigurations is specified | | |
| ssmParameterConfigurations:dataType | The SSM Parameter data type for the image. | String | No | | Allowed values - text\$1aws:ec2:image) |
**Outputs: **The following table includes outputs for this step action.
| Output name | Description | Type |
| --- | --- | --- |
| configuredImages | A list of configured images. | Array |
| configuredImages:accountId | The destination account ID of the distributed image. | String |
| configuredImages:name | The name of the AMI. | String |
| configuredImages:amiId | The AMI ID of the distributed image. | String |
| configuredImages:dateStarted | UTC time when distribution started. | String |
| configuredImages:dateStopped | UTC time when distribution completed. | String |
| configuredImages:step | The step at which distribution stopped. | Completed\$1AssociateLicensesRunning\$1UpdateLaunchTemplateRunning\$1PutSsmParametersRunning\$1UpdateFastLaunchConfiguration\$1ExportAmiQueued\$1ExportAmiRunning |
| configuredImages:region | Tne AWS of the distributed image | String |
| configuredImages:status | Distribution status. | Completed\$1Failed\$1Cancelled\$1TimedOut |
| configuredImages:errorMessage | Error message, if any. | String |
**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](https://docs.aws.amazon.com/systems-manager/latest/userguide/execute-remote-commands.html).
**Note**
The bootstrap script installs the AWS CLI and Docker packages that are prerequisites for Image Builder to successfully build Docker containers. If you don't include this step action, the image build could fail.
**Default Timeout: **60 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.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| instanceId | The ID of the instance to bootstrap. | String | Yes | | This must be the output instance ID from the workflow step that launched the instance for this workflow. |
**Outputs: **The following table includes outputs for this step action.
| Output name | Description | Type |
| --- | --- | --- |
| runCommandId | The ID of the Systems Manager sendCommand that ran the bootstrap script on the instance. | String |
| status | The status returned from the Systems Manager sendCommand. | String |
| output | Output returned from the Systems Manager sendCommand. | String |
**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](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html) 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](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-inventory.html). 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.
**Note**
This step action only works for images that create AMIs.
**Default Timeout: **30 minutes
**Max Timeout: **720 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.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| instanceId | The build instance to apply the metadata settings to. | String | Yes | | This must be the output instance ID from the workflow step that launched the build instance for this workflow. |
**Outputs: **The following table includes outputs for this step action.
| Output name | Description | Type |
| --- | --- | --- |
| osVersion | The operating system name and version collected from the build instance. | String |
| associationId | The Systems Manager association ID used for inventory collection. | String |
**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
**Rollback: **There is no rollback for this step action.
**Inputs: **The following table includes supported inputs for this step action.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| instanceId | The ID for the instance that scanning ran on. | String | Yes | | This must be the output instance ID from the workflow step that launched the instance for this workflow. |
**Outputs: **The following table includes outputs for this step action.
| Output name | Description | Type |
| --- | --- | --- |
| runCommandId | The ID of the Systems Manager sendCommand that ran the script to collect findings. | String |
| status | The status returned from the Systems Manager sendCommand. | String |
| output | Output returned from the Systems Manager sendCommand. | String |
**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
**Rollback: **There is no rollback for this step action.
**Inputs: **The following table includes supported inputs for this step action.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| instanceId | The instance to create the new image from. | String | Yes | | The instance for the provided instance ID must be in a running state when this step starts. |
**Outputs: **The following table includes outputs for this step action.
| Output name | Description | Type |
| --- | --- | --- |
| imageId | The AMI ID of the image that's created. | String |
**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.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| region | The list of regions to distribute the image. | String | Yes | | Minimum length of 1. Maximum length of 1024. |
| name | The name of the distribution configuration. | String | No | | |
| description | The distributions of the distribution configuration. | String | No | | |
| targetAccountIds | Account IDs to which to distribute the image. | Array | No | | |
| amiTags | The tags of the distribution configuration. | Map | No | | |
| kmsKeyId | KMS keys to apply to the distributed image. | String | No | | |
**Outputs: **The following table includes outputs for this step action.
| Output name | Description | Type |
| --- | --- | --- |
| distributedImages | A list of distributed images | Array |
| distributedImages:region | Tne AWS region of the distributed image. | String |
| distributedImages:name | The name of the AMI. | String |
| distributedImages:amiId | The AMI ID of the distributed image. | String |
| distributedImages:accountId | The destination account ID of the distributed image. | String |
| distributedImages:dateStarted | UTC time when distribution started. | String |
| distributedImages:dateStopped | UTC time when distribution completed. | String |
| distributedImages:status | Distribution status. | Completed\$1Failed\$1Cancelled\$1TimedOut |
| distributedImages:step | The step at which distribution stopped. | Completed\$1CopyAmiRunning |
| distributedImages:errorMessage | Error message, if any. | String |
**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](https://docs.aws.amazon.com/systems-manager/latest/userguide/execute-remote-commands.html).
**Default Timeout: **720 minutes
**Max Timeout: **1 day
**Rollback: **There is no rollback for this step action.
**Inputs: **The following table includes supported inputs for this step action.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| instanceId | The ID for the instance that the components should run on. | String | Yes | | This must be the output instance ID from the workflow step that launched the instance for this workflow. |
**Outputs: **The following table includes outputs for this step action.
| Output name | Description | Type |
| --- | --- | --- |
| runCommandId | The ID of the Systems Manager sendCommand that ran the components on the instance. | String |
| status | The status returned from the Systems Manager sendCommand. | String |
| output | Output returned from the Systems Manager sendCommand. | String |
**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](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-statemachines.html) 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.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| stateMachineArn | The ARN of the Step Functions state machine to execute. | String | Yes | | Must be a valid state machine ARN. |
| input | JSON input data to provide to the state machine. | String | No | \$1\$1 | Must be valid JSON string, maximum length: 16 KiB. |
**Outputs:** The following table includes outputs for this step action.
| Output name | Description | Type |
| --- | --- | --- |
| executionArn | The ARN of the state machine execution. | String |
| output | The output of the state machine execution. | String |
**IAM permissions required**
Your custom execution role must have the following permissions to use this step action:
**Allow actions**
+ `states:StartExecution`
+ `states:DescribeExecution`
**Specify resources**
+ `arn:aws:states:us-west-2:111122223333:stateMachine:state-machine-name`
+ `arn:aws:states:us-west-2:111122223333:execution:state-machine-name:*`
**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: **75 minutes
**Max Timeout: **720 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.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| imageIdOverride | The image to use for launching the instance | String | No | Build stage: Image recipe base image Test stage: Output AMI from the build stage | Must be a valid AMI ID |
| instanceTypesOverride | Image Builder tries each instance type in the list until it finds one that launches successfully | List of String | No | Instance types specified in your Infrastructure Configuration | Must be valid instance types |
| waitFor | The condition to wait for before completing the workflow step and moving on to the next step | String | Yes | | Image Builder supports ssmAgent. |
**Outputs: **The following table includes outputs for this step action.
| Output name | Description | Type |
| --- | --- | --- |
| instanceId | The instance ID of the instance that launched. | String |
**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.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| region | The region of the image. | String | Yes | | |
| launchPermission | | | No | | |
| launchPermission:userIds | The user IDs to modify in the launch permissions for the image. | String | No | | |
| launchPermission:userGroups | The user groups to modify in the launch permissions for the image. | String | No | | |
| launchPermission:organizationArns | The AWS Organization ARNs to modify in the launch permissions for the image. | String | No | | |
| launchPermission:organizationalUnitArns | The AWS Organization Unit ARNs to modify in the launch permissions for the image. | String | No | | |
**Outputs: **The following table includes outputs for this step action.
| Output name | Description | Type |
| --- | --- | --- |
| modifiedImages | A list of modified images | Array |
| modifiedImages:accountId | The destination account ID of the distributed image. | String |
| modifiedImages:name | The name of the AMI. | String |
| modifiedImages:amiId | The AMI ID of the distributed image. | String |
| modifiedImages:dateStarted | UTC time when distribution started. | String |
| modifiedImages:dateStopped | UTC time when distribution completed. | String |
| modifiedImages:step | The step at which distribution stopped. | Completed\$1ModifyAmiRunning |
| modifiedImages:region | Tne AWS region of the image. | String |
| modifiedImages:status | Distribution status. | Completed\$1Failed\$1Cancelled\$1TimedOut |
| modifiedImages:errorMessage | Error message, if any. | String |
**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: **540 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.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| architecture | The architecture of the AMI. | String | No | | Valid values: i386, x86\$164, arm64, x86\$164\$1mac, arm64\$1mac |
| blockDeviceMapping | The block device mapping entries for the AMI. | Array | No | | |
| bootMode | The boot mode of the AMI. | String | No | | Valid values: legacy-bios, uefi, uefi-preferred |
| description | A description for the AMI. | String | No | | |
| enaSupport | Whether enhanced networking with ENA is enabled. | Boolean | No | | |
| imageLocation | The location of the AMI manifest. | String | No | | Required for S3-backed AMIs |
| imdsSupport | The IMDSv2 support level. | String | No | | Valid values: v2.0 |
| includeSnapshotTags | Whether to include tags from the first snapshot defined in the block device mapping. | Boolean | No | FALSE | When set to true, tags are included as follows: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/imagebuilder/latest/userguide/wfdoc-step-actions.html) |
| kernelId | The ID of the kernel to use. | String | No | | |
| ramdiskId | The ID of the RAM disk to use. | String | No | | |
| rootDeviceName | The device name of the root device. | String | No | | Example: /dev/sda1 |
| sriovNetSupport | Enhanced networking with the Intel 82599 VF interface. | String | No | | |
| tpmSupport | TPM version support. | String | No | | Valid values: v2.0 |
| uefiData | Base64-encoded UEFI data. | String | No | | |
| virtualizationType | The virtualization type. | String | No | | Valid values: hvm, paravirtual |
**Outputs: **The following table includes outputs for this step action.
| Output name | Description | Type |
| --- | --- | --- |
| imageId | The AMI ID of the registered image. | String |
**IAM permissions required**
Your custom execution role must have the following permissions to use this step action:
**Allow actions**
+ `ec2:DescribeSnapshots`
+ `ec2:CreateTags`
**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](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html).
**Default Timeout: **720 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.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| instanceId | The ID of the instance to run the command document on. | String | Yes | | This must be the output instance ID from the workflow step that launched the instance for this workflow. |
| documentName | The name of the Systems Manager command document to run. | String | Yes | | |
| parameters | A list of key value pairs for any parameters that the command document requires. | dictionary> | Conditional | | |
| documentVersion | The command document version to run. | String | No | \$1DEFAULT | |
**Outputs: **The following table includes outputs for this step action.
| Output name | Description | Type |
| --- | --- | --- |
| runCommandId | The ID of the Systems Manager sendCommand that ran the command document on the instance. | String |
| status | The status returned from the Systems Manager sendCommand. | String |
| output | Output returned from the Systems Manager sendCommand. | List of strings |
**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](https://aws.amazon.com/articles/public-ami-publishing-hardening-and-clean-up-requirements/).
**Default Timeout: **60 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.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| instanceId | The ID of the instance to run the AWSEC2-RunSysprep document on. | String | Yes | | This must be the output instance ID from the workflow step that launched the instance for this workflow. |
**Outputs: **The following table includes outputs for this step action.
| Output name | Description | Type |
| --- | --- | --- |
| runCommandId | The ID of the Systems Manager sendCommand that ran the AWSEC2-RunSysprep document on the instance. | String |
| status | The status returned from the Systems Manager sendCommand. | String |
| output | Output returned from the Systems Manager sendCommand. | String |
**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](security-best-practices.md#post-build-cleanup). 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](https://docs.aws.amazon.com/systems-manager/latest/userguide/execute-remote-commands.html).
**Default Timeout: **60 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.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| instanceId | The ID of the instance to sanitize. | String | Yes | | This must be the output instance ID from the workflow step that launched the instance for this workflow. |
**Outputs: **The following table includes outputs for this step action.
| Output name | Description | Type |
| --- | --- | --- |
| runCommandId | The ID of the Systems Manager sendCommand that ran the sanitize script on the instance. | String |
| status | The status returned from the Systems Manager sendCommand. | String |
| output | Output returned from the Systems Manager sendCommand. | String |
**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
**Max Timeout: **720 minutes
**Rollback: **There is no rollback for this step action.
**Inputs: **The following table includes supported inputs for this step action.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| instanceId | The ID of the instance to terminate. | String | Yes | | |
**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
**Max Timeout: **7 days
**Rollback: **There is no rollback for this step action.
**Inputs: **The following table includes supported inputs for this step action.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| snsTopicArn | An optional SNS topic ARN to send a notification to when the workflow step is pending. | String | No | | |
| lambdaFunctionName | An optional name or ARN of the Lambda function to invoke asynchronously when the workflow step is pending. | String | No | | |
| payload | JSON string used as message for SNS and payload for Lambda. If provided, a custom payload is wrapped in default message/payload, used for SNS and Lambda respectively. If not provided, generates default message/payload. | String | No | | Must be valid JSON string, max 16 KiB |
**Outputs: **The following table includes outputs for this step action.
| Output name | Description | Type |
| --- | --- | --- |
| action | The action that the SendWorkflowStepAction API action returns. | String (RESUME or STOP) |
| reason | The reason for the returned action. | String |
**IAM permissions required**
Your custom execution role must have the following permissions to use this step action:
**Allow actions**
+ `lambda:InvokeFunction`
**Specify resources**
+ `arn:aws:lambda:us-west-2:111122223333:function:function-name`
+ `arn:aws:lambda:us-west-2:111122223333:function:*`
**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.
| Input name | Description | Type | Required | Default | Constraints |
| --- | --- | --- | --- | --- | --- |
| instanceId | The ID of the instance to monitor for SSM connectivity. | String | Yes | | Must be a valid EC2 instance ID |
**Outputs: **The following table includes outputs for this step action.
| Output name | Description | Type |
| --- | --- | --- |
| status | Connection status of SSM Agent. | String |
**Example**
Specify the step action in the workflow document.
```
- name: WaitForInstanceAfterReboot
action: WaitForSSMAgent
onFailure: Abort
timeoutInSeconds: 900
inputs:
instanceId.$: $.stepOutputs.LaunchStep.instanceId
```
Use the output of the step action value in the workflow document.
```
$.stepOutputs.WaitForInstanceAfterReboot.Status
```
# Use dynamic variables in your workflow document
You can use dynamic variables in your workflow documents to represent values that vary at runtime for your image creation process. String interpolation for dynamic variables allows you to embed JSONPath expressions within structured content such as JSON strings.This is particularly useful when you need to pass runtime values within complex payloads to step actions like `ExecuteStateMachine` or `WaitForAction`.
To use string interpolation for dynamic variables, wrap JSONPath expressions in double curly braces `"{{...}}"` within your string content. Only JSONPath expressions wrapped in double curly braces are processed as variables. Any JSONPath expressions not wrapped in double curly braces are treated as literal string content.
**JSONPath dynamic workflow variable syntax**
```
$..[.]
```
Dynamic variable values are represented as JSONPath selectors with structural nodes that uniquely identify the target variable. The first node after the root (\$1) refers to the workflow document structure, such as `stepOutputs`, or in the case of Image Builder system variables, `imageBuilder`. The following list contains supported JSONPath workflow document structure nodes.
**Document structure nodes**
+ parameters - The workflow parameters
+ stepOutputs - Outputs from a step in the same workflow doc
+ workflowOutputs - Outputs from a workflow doc that already ran
+ imagebuilder - Image Builder system variables
The `parameters` and `stepOutputs` document structure nodes include an optional node for the step name. This helps ensure unique variable names across all of the steps.
The final node in the JSONPath is the name of the target variable, such as `instanceId`.
Each step can refer to the output of any prior step actions with these JSONPath dynamic variables. This is also known as *chaining, or referencing*. To refer to output from a prior step action, you might use the following dynamic variable.
```
$.stepOutputs.step-name.output-name
```
**Important**
When an input parameter refers to a dynamic variable, the chaining indicator (`.$`) must be attached to the end of the parameter name.
**Example 1: Input parameter chaining indicator**
The following example shows an input parameter that uses string interpolation to resolve a dynamic variable in the parameter value at runtime.
```
- name: ApplyTestComponents
action: ExecuteComponents
onFailure: Abort
inputs:
instanceId.$: "$.stepOutputs.LaunchTestInstance.instanceId"
```
**Example 2: String interpolation in dynamic variables**
The following example demonstrates how dynamic variables use string interpolation to determine values at runtime.
```
- name: ValidateImageConfiguration
action: ExecuteStateMachine
inputs:
stateMachineArn: arn:aws:states:us-east-1:111122223333:stateMachine:ImageValidation
input: |
{
"imageId": "{{ $.stepOutputs.CreateImageFromInstance.imageId }}",
"region": "us-east-1",
"buildDate": "{{ $.imagebuilder.dateTime }}",
"instanceType": "{{ $.stepOutputs.LaunchStep.instanceType }}"
}
```
In this example, the JSONPath expressions wrapped in double curly braces are resolved at runtime:
+ `{{ $.stepOutputs.CreateImageFromInstance.imageId }}` - Resolves to the actual image ID from the CreateImageFromInstance step
+ `{{ $.imagebuilder.dateTime }}` - Resolves to the current build timestamp. See [Use Image Builder system variables](#wfdoc-ib-vars) for a list of Image Builder system variables that you can use.
+ `{{ $.stepOutputs.LaunchStep.instanceType }}` - Resolves to the instance type used in the LaunchStep
The literal strings like `"region": "us-east-1"` remain unchanged.
**Note**
String interpolation works with any string content in your workflow document, including multiline strings using the YAML pipe (`|`) operator. The curly brace requirement acts as an escape mechanism to clearly distinguish between JSONPath variables and literal text content.
## Use Image Builder system variables
Image Builder provides the following system variables that you can use in your workflow document:
| Variable name | Description | Type | Example value |
| --- | --- | --- | --- |
| cloudWatchLogGroup | The name of the CloudWatch Logs group for output logs. Format: `/aws/imagebuilder/` | String | `/aws/imagebuilder/sampleImageRecipe` |
| cloudWatchLogStream | The name of the CloudWatch Logs stream for output logs. | String | *1.0.0/1* |
| collectImageMetadata | The setting that directs Image Builder whether to collect instance metadata. | Boolean | `true` \$1 `false` |
| collectImageScanFindings | The current value of the setting that enables Image Builder to collect image scan findings. | Boolean | `true` \$1 `false` |
| imageBuildNumber | The build version number of the image. | Integer | *1* |
| imageId | The AMI id of the base image. | String | *ami-1234567890abcdef1* |
| imageName | The name of the image. | String | *sampleImage* |
| imageType | The image output type. | String | `AMI` \$1 `Docker` |
| imageVersionNumber | The version number of the image. | String | *1.0.0* |
| instanceProfileName | The name of the instance profile role that Image Builder uses to launch build and test instances. | String | *SampleImageBuilderInstanceProfileRole* |
| platform | The operating system platform of the image that's built. | String | `Linux` \$1 `Windows` \$1 `MacOS` |
| s3Logs | A JSON object that contains configuration for the S3 logs that Image Builder writes. | JSON object | \$1's3Logs': \$1's3BucketName': '*sample-bucket*', 's3KeyPrefix': '*ib-logs*'\$1\$1 |
| securityGroups | The security group IDs that apply to build and test instances. | List [String] | *[sg-1234567890abcdef1, sg-11112222333344445]* |
| sourceImageARN | The Amazon Resource Name (ARN) of the Image Builder image resource that the workflow uses for build and test stages. | String | arn:aws:imagebuilder:*us-east-1*:*111122223333*:image/*sampleImage*/*1.0.0/1* |
| subnetId | The ID of the subnet to launch the build and test instances into. | String | *subnet-1234567890abcdef1* |
| terminateInstanceOnFailure | The current value of the setting that directs Image Builder to terminate the instance on failure or keep it for troubleshooting. | Boolean | `true` \$1 `false` |
| workflowPhase | The current stage that's running for the workflow execution. | String | `Build` \$1 `Test` |
| workingDirectory | The path to the working directory. | String | `/tmp` |
# Use conditional statements in your workflow steps
Conditional statements begin with the `if` statement document attribute. The ultimate purpose of the `if` statement is to determine whether to run the step action or to skip it. If the `if` statement resolves to `true`, then the step action runs. If it resolves to `false`, Image Builder skips the step action and records a step status of `SKIPPED` in the log.
The `if` statement supports branching statements (`and`, `or`) and conditional modifiers (`not`). It also supports the following comparison operators that perform value comparisons (equal, less than, greater than) based on the data types it compares (string or number).
**Supported comparison operators**
+ `booleanEquals`
+ `numberEquals`
+ `numberGreaterThan`
+ `numberGreaterThanEquals`
+ `numberLessThan`
+ `numberLessThanEquals`
+ `stringEquals`
**Rules for branching statements and conditional modifiers**
The following rules apply for branching statements (`and`, `or`) and conditional modifiers (`not`).
+ Branching statements and conditional modifiers must appear on a line by themselves.
+ Branching statements and conditional modifiers must follow level rules.
+ There can only be one statement at the parent level.
+ Each child branch or modifier starts a new level.
For more information about levels, see [Nested levels in conditional statements](#wfdoc-conditional-structure).
+ Each branching statement must have at least one child conditional statement, but no more than ten.
+ Conditional modifiers operate on only one child conditional statement.
## Nested levels in conditional statements
Conditional statements operate at several levels in a section of their own. For example, the `if` statement attribute appears at the same level in your workflow document as the step name and action. This is the base of the conditional statement.
You can specify up to four levels of conditional statements, but only one statement can appear at the parent level. All other branching statements, conditional modifiers, or conditional operators are indented from there, one indent per level.
The following outline shows the maximum number of nested levels for a conditional statement.
```
base:
parent:
- child (level 2)
- child (level 3)
child (level 4)
```
`if` attribute
The `if` attribute specifies the conditional statement as a document attribute. This is level zero.
Parent level
This is the first level of nesting for conditional statements. There can be only one statement at this level. If you don't need branching or modifiers, this can be a conditional operator with no child statements. This level doesn't use dash notation, except for conditional operators.
Child levels
Levels two through four are considered child levels. Child statements can include branching statements, conditional modifiers, or conditional operators.
**Example: Nested levels**
The following example shows the maximum number of levels in a conditional statement.
```
if:
and: #first level
- stringEquals: 'my_string' #second level
value: 'my_string'
- and: #also second level
- numberEquals: '1' #third level
value: 1
- not: #also third level
stringEquals: 'second_string' #fourth level
value: "diff_string"
```
**Nesting rules**
+ Each branch or modifier at the child level starts a new level.
+ Each level is indented.
+ There can be a maximum of four levels, including one statement, modifier, or operator at the parent level, and up to three additional levels.
## Conditional statement examples
This group of examples show various aspects of conditional statements.
**Branching: and**
The `and` branching statement operates on a list of expressions that are children of the branch, all of which must evaluate to `true`. Image Builder evaluates the expressions in the order that they appear in the list. If any expression evaluates to `false`, then processing stops and the branch is considered `false`.
The following example evaluates to `true`, because both expressions evaluate to `true`.
```
if:
and:
- stringEquals: 'test_string'
value: 'test_string'
- numberEquals: 1
value: 1
```
**Branching: or**
The `or` branching statement operates on a list of expressions that are children of the branch, at least one of which must evaluate to `true`. Image Builder evaluates the expressions in the order that they appear in the list. If any expression evaluates to `true`, then processing stops and the branch is considered `true`.
The following example evaluates to `true`, even though the first expression is `false`.
```
if:
or:
- stringEquals: 'test_string'
value: 'test_string_not_equal'
- numberEquals: 1
value: 1
```
**Conditional modifier: not**
The `not` conditional modifier negates the conditional statements that are children of the branch.
The following example evaluates to `true` when the `not` modifier negates the `stringEquals` conditional statement.
```
if:
not:
- stringEquals: 'test_string'
value: 'test_string_not_equal'
```
**Conditional statement: booleanEquals**
The `booleanEquals` comparison operator compares Boolean values and returns true if the Boolean values exact match.
The following example determines if `collectImageScanFindings` is enabled.
```
if:
- booleanEquals: true
value: '$.imagebuilder.collectImageScanFindings'
```
**Conditional statement: stringEquals**
The `stringEquals` comparison operator compares two strings and returns true if the strings are an exact match. If either value isn't a string, Image Builder converts it to a string before it compares.
The following example compares the platform system variable to determine if the workflow is running on a Linux platform.
```
if:
- stringEquals: 'Linux'
value: '$.imagebuilder.Platform'
```
**Conditional statement: numberEquals**
The `numberEquals` comparison operator compares two numbers and returns true if the numbers are equal. The numbers to compare must be one of the following formats.
+ Integer
+ Float
+ A string that matches the following regex pattern: `^-?[0-9]+(\.)?[0-9]+$`.
The following example comparisons all evaluate to `true`.
```
if:
# Value provider as a number
numberEquals: 1
value: '1'
# Comparison value provided as a string
numberEquals: '1'
value: 1
# Value provided as a string
numberEquals: 1
value: '1'
# Floats are supported
numberEquals: 5.0
value: 5.0
# Negative values are supported
numberEquals: -1
value: -1
```