AWS imagebuilder: Document IAM roles and permissions for DistributeImage and RetryImage
Summary
Rewrites enhanced distribution documentation to add DistributeImage and RetryImage APIs, including required IAM permissions, execution role recommendations, and cross-account distribution role setup.
Security assessment
The change documents IAM permissions and execution roles for new distribution APIs, including least-privilege policies and cross-account roles, which is security guidance but not a fix for a specific vulnerability.
Evidence
* 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](./security-iam-awsmanpol.html#sec-iam-manpol-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.
Diff
diff --git a/imagebuilder/latest/userguide/distribution-enhanced_functionality.md b/imagebuilder/latest/userguide/distribution-enhanced_functionality.md index 6af9e55..14ad094 100644 --- a//imagebuilder/latest/userguide/distribution-enhanced_functionality.md +++ b//imagebuilder/latest/userguide/distribution-enhanced_functionality.md @@ -7 +7 @@ -Decoupled DistributionDistribution RetryDistribution Workflows +Distribute an existing imageRetry a failed imageDistribution workflows @@ -11 +11 @@ Decoupled DistributionDistribution RetryDistribution Workflows -Image Builder offers advanced distribution capabilities that give you flexibility and control over how your AMIs are distributed across regions and accounts. These capabilities separate distribution from the build process, allowing you to distribute existing images on demand, recover from distribution failures efficiently, and implement controlled, multi-stage distribution strategies through customizable workflows. +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. @@ -13 +13 @@ Image Builder offers advanced distribution capabilities that give you flexibilit -You can use enhanced AMI distribution capabilities in Image Builder to directly perform distribution activities without the need to re-run a complete image build. +## Distribute an existing image @@ -15 +15 @@ You can use enhanced AMI distribution capabilities in Image Builder to directly -## Decoupled Distribution +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. @@ -17 +17 @@ You can use enhanced AMI distribution capabilities in Image Builder to directly -The DistributeImage API accepts three types of source image references: +You identify the source image in one of three ways: @@ -19 +19 @@ The DistributeImage API accepts three types of source image references: - * **AMI ID** – A standard AMI identifier (for example, `ami-0abcdef1234567890`) + * **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. @@ -21 +21 @@ The DistributeImage API accepts three types of source image references: - * **SSM Parameter** – An SSM parameter that stores an AMI ID (for example, `ssm:/my/ami/parameter`) + * **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. @@ -23 +23 @@ The DistributeImage API accepts three types of source image references: - * **Image Builder version ARN** – An Image Builder image version ARN + * **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. @@ -28 +28 @@ The DistributeImage API accepts three types of source image references: -## Distribution Retry +###### Note @@ -30 +30 @@ The DistributeImage API accepts three types of source image references: -If an image distribution fails, use the `RetryImage` API to retry distribution. This reduces time to troubleshoot the cause of the failure by avoiding a complete image rebuild. Use `RetryImage` after resolving the underlying cause of the distribution failure. +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. @@ -32 +32 @@ If an image distribution fails, use the `RetryImage` API to retry distribution. -The RetryImage API accepts an image build version ARN (for example, `arn:aws:imagebuilder:us-west-2:123456789012:image/my-image/1.0.0/1`). When you invoke the API, Image Builder automatically resumes the distribution process from the point of failure using the original distribution configuration and settings. The `RetryImage` API can retry distributions that failed during the distribution phase, test phase, or integration phase. It works with AMIs in the following states: pending, failed, deleted, or available. +###### Prerequisites @@ -34 +34 @@ The RetryImage API accepts an image build version ARN (for example, `arn:aws:ima -**Prerequisites** +Unlike a pipeline build, **DistributeImage** takes an execution role at call time. Make sure the following are in place: @@ -36 +36 @@ The RetryImage API accepts an image build version ARN (for example, `arn:aws:ima -Before retrying a distribution, ensure the following: + * 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](./security-iam-awsmanpol.html#sec-iam-manpol-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. @@ -38 +38 @@ Before retrying a distribution, ensure the following: - * You have identified and resolved the root cause of the failure. Review distribution logs in CloudWatch Logs for error details. + * 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`. @@ -40 +40 @@ Before retrying a distribution, ensure the following: - * You have the necessary IAM permissions to retry the image build. + * 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](./security-iam-awsmanpol.html#sec-iam-manpol-Ec2ImageBuilderCrossAccountDistributionAccess) 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](./cross-account-dist.html) lists for `launchTemplateConfigurations` and Parameter Store parameters. @@ -42 +41,0 @@ Before retrying a distribution, ensure the following: - * For cross-account distribution failures, verify that the `EC2ImageBuilderDistributionCrossAccountRole` in the destination account has the `Ec2ImageBuilderCrossAccountDistributionAccess` policy attached. @@ -45,0 +45 @@ Before retrying a distribution, ensure the following: +AWS Management Console @@ -47 +46,0 @@ Before retrying a distribution, ensure the following: -**Important:** Retrying without fixing the underlying issue will result in repeated failures. @@ -49 +48 @@ Before retrying a distribution, ensure the following: -## Distribution Workflows +To distribute an existing image in the Image Builder console, follow these steps: @@ -51 +50 @@ Before retrying a distribution, ensure the following: -Distribution workflows are a new workflow type that complement build and test workflows, enabling you to define and control the distribution process with sequential steps. With distribution workflows, you can create custom distribution processes that include AMI copy operations, wait-for-action checkpoints, image attribute modifications, and other distribution-related steps. This provides structured control over how your AMIs are distributed, with step-level visibility, parallel distribution capabilities, and granular error reporting. + 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). @@ -53 +52,114 @@ Distribution workflows are a new workflow type that complement build and test wo -To learn more about creating and customizing workflows, see [Manage Image Workflows](manage-image-workflows.html). + 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](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/distribute-image.html) 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](./image-details-list.html). + +## Retry a failed image + +If an image fails during its test or distribution phase, use the [retry-image](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/retry-image.html) 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](./security-iam-awsmanpol.html#sec-iam-manpol-Ec2ImageBuilderCrossAccountDistributionAccess) managed policy attached. For more information, see [Set up cross-account AMI distribution with Image Builder](./cross-account-dist.html). + + + + +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/](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](./integ-eventbridge.html#integ-eb-event-summary). + +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](./manage-image-workflows.html).