Use enhanced AMI distribution capabilities

Image Builder gives you advanced distribution capabilities that separate distribution from the build process. You can distribute an image that you already built, retry an AMI image that failed during its test or distribution phase without rebuilding it, and define multi-stage distribution processes with custom workflows.

Distribute an existing image

The DistributeImage operation distributes an image that Image Builder (or you) already created, without rerunning the build and test phases. Image Builder runs only the distribution phase, using the targets and settings in a distribution configuration that you reference by ARN.

You identify the source image in one of three ways:

• AMI ID – A standard AMI identifier, such as ami-0abcdef1234567890. The AMI must exist and be accessible in the Region where you call the operation.

• SSM parameter – An Systems Manager Parameter Store reference in the form ssm:/path/to/parameter, where the text after ssm: is the parameter name or ARN. The parameter must be a String parameter whose value is a valid AMI ID.

• Image Builder image version ARN – The ARN of an Image Builder image in the Region where you call the operation. The image's output resources must include an AMI in that Region. You can specify a build version ARN that ends with the build number, such as image/my-image/1.0.0/1, or a version ARN without the build number, such as image/my-image/1.0.0. Image Builder resolves a version ARN to its latest build in the AVAILABLE state.

Note

The source image must be an AMI ID, an SSM parameter, or an Image Builder image ARN, and Image Builder doesn't accept an AWS Marketplace product code. The distribution configuration must be in the same Region where you call DistributeImage. You can't pass inline distribution settings to this operation.

Prerequisites

Unlike a pipeline build, DistributeImage takes an execution role at call time. Make sure the following are in place:

• An Image Builder execution role that Image Builder can assume to perform the distribution. We recommend that you create a custom role with the EC2ImageBuilderExecutionPolicy AWS managed policy attached. That policy allows ec2:ModifyImageAttribute, ec2:ModifySnapshotAttribute, and ec2:EnableFastLaunch only on resources that are tagged CreatedBy: EC2 Image Builder, and allows ssm:PutParameter only on parameters under /imagebuilder/. If your distribution acts on other resources, add the required permissions to the role. To configure EC2 Fast Launch without a launch template, also attach the EC2FastLaunchFullAccess policy. To configure EC2 Fast Launch with a launch template, the launch template must have the CreatedBy: EC2 Image Builder tag. Image Builder adds this tag only to launch templates that the distribution configuration updates in launchTemplateConfigurations. For any other launch template, add the tag yourself or attach the EC2FastLaunchFullAccess policy.

• Permission to call imagebuilder:DistributeImage, imagebuilder:GetDistributionConfiguration, and iam:PassRole for the execution role. Image Builder also describes the source AMI with your credentials to validate it, so you need ec2:DescribeImages for every source type. If the source is an SSM parameter, you also need ssm:GetParameter for that parameter. If the source is an Image Builder image ARN, you also need imagebuilder:GetImage on that image. If you include tags in the request, you also need imagebuilder:TagResource.

• If the distribution configuration copies the AMI to other accounts (targetAccountIds), or updates launch templates or SSM parameters in other accounts, the EC2ImageBuilderDistributionCrossAccountRole in each of those accounts, with the Ec2ImageBuilderCrossAccountDistributionAccess policy managed policy attached. The managed policy doesn't cover launch templates or SSM parameters. To update them, also add the policies that Set up cross-account AMI distribution with Image Builder lists for launchTemplateConfigurations and Parameter Store parameters.

AWS Management Console

To distribute an existing image in the Image Builder console, follow these steps:

1. Open the EC2 Image Builder console at https://console.aws.amazon.com/imagebuilder/.

2. Choose Distribution settings from the navigation pane.

3. Select the distribution configuration that defines your targets, then choose Distribute image from the Actions menu. You can select only one distribution configuration at a time for this action.

4. In the Image to distribute section, choose the source image type – AMI ID, SSM parameter, or Image Builder image ARN – and specify the image to distribute.

5. Choose the IAM role that Image Builder uses to perform the distribution.

6. Choose Distribute image.

AWS CLI

The following examples show how to distribute an existing image with the distribute-image command. You can specify the --execution-role by role name or by full ARN; the following examples show both forms.

Distribute from an AMI ID

aws imagebuilder distribute-image \
    --source-image ami-0abcdef1234567890 \
    --distribution-configuration-arn arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-distribution \
    --execution-role arn:aws:iam::123456789012:role/MyImageBuilderDistributionRole

Distribute from an SSM parameter

aws imagebuilder distribute-image \
    --source-image ssm:/golden/latest-ami \
    --distribution-configuration-arn arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-distribution \
    --execution-role MyImageBuilderDistributionRole

Distribute from an Image Builder image version ARN

This example uses a build version ARN. You can also omit the trailing build number (/1) to distribute the latest build of that image version.

aws imagebuilder distribute-image \
    --source-image arn:aws:imagebuilder:us-west-2:123456789012:image/my-image/1.0.0/1 \
    --distribution-configuration-arn arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-distribution \
    --execution-role MyImageBuilderDistributionRole

The command returns the imageBuildVersionArn for the distribution. Track its progress the same way you track a build – see List images and build versions.

Retry a failed image

If an image fails during its test or distribution phase, use the retry-image command (the RetryImage API) to rerun the image from the start of the phase that failed. Steps in that phase run again. If an AMI copy from the earlier attempt is still available in a target Region and account, Image Builder reuses it instead of copying the AMI again. Image Builder reuses the original execution role, distribution configuration, and settings, so you don't rebuild the image. The retry assumes the same execution role, so any permission fixes that you make to that role apply to the retry.

Prerequisites

Before you retry a failed image, verify the following. A retry counts against your concurrent image build quota, and Image Builder rejects the retry if you've already reached that quota.

• The image is in a FAILED or CANCELLED state, and it failed or was canceled during its test or distribution phase. You can't retry an image that succeeded or is still in progress, or an image that failed or was canceled in any other phase.

• The image was created within the last 30 days.

• The image is an AMI-based image. You can't retry a container image.

• The image hasn't already been retried the maximum number of times. Image Builder allows up to 10 retries per image.

• You have identified and resolved the root cause of the failure. Review the image's logs in CloudWatch Logs for error details.

• You have permission to call imagebuilder:RetryImage on the image build version that you want to retry.

• For cross-account distribution failures, verify that the EC2ImageBuilderDistributionCrossAccountRole in the destination account has the Ec2ImageBuilderCrossAccountDistributionAccess policy managed policy attached. For more information, see Set up cross-account AMI distribution with Image Builder.

AWS Management Console

To retry a failed image in the Image Builder console, follow these steps:

1. Open the EC2 Image Builder console at https://console.aws.amazon.com/imagebuilder/.

2. Choose Images from the navigation pane, and then choose the image build version that failed.

3. Choose Retry image. This action is available only when the image is in a failed or canceled state.

AWS CLI

Provide the image build version ARN of the failed image:

aws imagebuilder retry-image \
    --image-build-version-arn arn:aws:imagebuilder:us-west-2:123456789012:image/my-image/1.0.0/1

Distribution workflows

Distribution workflows are a workflow type that complements build and test workflows. A distribution workflow defines the distribution phase as a sequence of steps, which gives you step-level visibility and control over how Image Builder distributes an AMI. The steps that this section describes apply to AMI output images.

In a distribution workflow, you can include steps that do the following:

• Copy and share the AMI across Regions and accounts.

• Modify image attributes, such as launch permissions, on the distributed AMIs.

• Apply additional image configurations.

• Pause for a manual approval or an external callback with a wait-for-action step. This lets you build staged or gated rollouts – for example, distribute to a test Region, wait for approval, then continue to production Regions.

Each step reports its own status – PENDING, RUNNING, WAITING (wait-for-action steps only), COMPLETED, FAILED, SKIPPED, or CANCELLED – and Image Builder sends step-level details to your CloudWatch log group. A step that runs longer than its timeoutSeconds value reports FAILED. Image Builder also emits EventBridge events at key points – for example, when the image changes state, and when a wait-for-action step pauses for input. For the full list of events, see Event messages that Image Builder sends.

To learn how to create and customize workflows, including the YAML document format and the available step actions, see Manage build, test, and distribution workflows for Image Builder images.