# Manage Image Builder distribution settings Distribution settings Before you configure distribution settings for your output images, we recommend that you verify availability for any underlying infrastructure or other requirements for instances that are launched from your output image in the distribution target Regions. For example, not all Regions support EC2 Mac Dedicated Hosts, which are required to launch instances from a macOS image. For more information about instance types and pricing for Dedicated Hosts, see [Amazon EC2 Dedicated Hosts Pricing](https://aws.amazon.com/ec2/dedicated-hosts/pricing/). After you create distribution settings with Image Builder, you can manage them using the Image Builder console, the Image Builder API, or **imagebuilder** commands in the AWS CLI. With distribution settings, you can perform the following actions: **AMI distribution** + Specify the name and description of your output AMI. + Authorize other AWS accounts, organizations, and OUs to launch the AMI from the owner's account. The owner account is billed for charges that are associated with the AMI. **Note** To make an AMI public, set the launch permission authorized accounts to `all`. For information and examples, see **[ModifyImageAttribute](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyImageAttribute.html)** in the *Amazon EC2 API Reference*. + Create a copy of the output AMI for each of the specified target accounts, organizations, and OUs in the destination Region. The target accounts, organizations, and OUs own their AMI copies, and are billed for any associated charges. For more information about distributing your AMI to AWS Organizations and OUs, see [Share an AMI with organizations or OUs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/share-amis-with-organizations-and-OUs.html). + Copy the AMI to the owner's account in other AWS Regions. + Export VM image disks to Amazon Simple Storage Service (Amazon S3). For more information, see [Example: Create distribution settings for output VM disks from the AWS CLI](cr-upd-ami-distribution-settings.md#cli-create-vm-dist-config). **Container image distribution** + Specify the ECR repository where Image Builder stores the output image in the distribution Region. You can use your distribution settings in the following ways to deliver images to target Regions, accounts, AWS Organizations and organizational units (OUs) one time, or with every pipeline build: + To automatically deliver updated images to specified Regions, accounts, Organizations, and OUs, use distribution settings with an Image Builder pipeline that runs on a schedule. + To create a new image and deliver it to the specified Regions, accounts, Organizations, and OUs, use distribution settings with an Image Builder pipeline that you run one time from the Image Builder console, using **Run pipeline** from the **Actions** menu. + To create a new image and deliver it to the specified Regions, accounts, Organizations, and OUs, use distribution settings with the following API action or Image Builder command in the AWS CLI: + The **[CreateImage](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateImage.html)** action in the Image Builder API. + The **[create-image](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-image.html)** command in the AWS CLI. + To export virtual machine (VM) image disks to S3 buckets in target Regions as part of your regular image build process. **Tip** When you have multiple resources of the same type, tagging helps you to identify a specific resource based on the tags you've assigned to it. For more information about tagging your resources using Image Builder commands in the AWS CLI, see the [Tag resources](tag-resources.md) section of this guide. **Topics** + [ # List and view distribution configuration detail ](distribution-settings-detail.md) + [ # Create and update AMI distribution configurations ](cr-upd-ami-distribution-settings.md) + [ # Create and update distribution settings for container images ](cr-upd-container-distribution-settings.md) + [ # Set up cross-account AMI distribution with Image Builder ](cross-account-dist.md) + [ # Configure AMI distribution with an EC2 launch template ](dist-using-launch-template.md) + [ # Use enhanced AMI distribution capabilities ](distribution-enhanced_functionality.md) # List and view distribution configuration detail List and view distribution configurations This section describes the various ways that you can find information and view details for your EC2 Image Builder distribution configuration. **Topics** + [ ## List distribution configurations from the console ](#list-distribution-config-console) + [ ## View distribution configuration details from the console ](#view-distribution-config-details-console) + [ ## List distributions from the AWS CLI ](#cli-list-distributions) + [ ## Get distribution configuration detail from the AWS CLI ](#cli-get-distribution-configuration) ## List distribution configurations from the console To see a list of the distribution configurations created under your account 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/). 1. Choose **Distribution settings** from the navigation pane. This shows a list of the distribution configurations that are created under your account. 1. To view details or create new distribution configuration, choose the **Configuration name** link. This opens the detail view for the distribution settings. **Note** You can also select the check box next to the **Configuration name**, then choose **View details**. ## View distribution configuration details from the console To view details for a specific distribution configuration using the Image Builder console, select the configuration to review, using the steps described in [List distribution configurations from the console](#list-distribution-config-console). On the distribution detail page, you can: + **Delete** the distribution configuration. For more information about deleting resources in Image Builder, see [Delete outdated or unused Image Builder resources](delete-resources.md). + **Edit** distribution details. ## List distributions from the AWS CLI The following example shows how to use the **[list-distribution-configurations](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/list-distribution-configurations.html)** command in the AWS CLI to list all of your distributions. ``` aws imagebuilder list-distribution-configurations ``` ## Get distribution configuration detail from the AWS CLI The following example shows how to use the **[get-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/get-distribution-configuration.html)** command in the AWS CLI to get the details of a distribution configuration by specifying its Amazon Resource Name (ARN). ``` aws imagebuilder get-distribution-configuration --distribution-configuration-arn arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-example-distribution-configuration ``` # Create and update AMI distribution configurations Create and update AMI distribution This section covers creating and updating distribution configurations for an Image Builder AMI. **Topics** + [ ## AMI distribution prerequisites ](#ami-distribution-config-prereqs) + [ ## Create an AMI distribution configuration ](#create-ami-distribution-config) + [ ## Update an AMI distribution configuration ](#update-ami-distribution-config) + [ ## Example: Enable EC2 Fast Launch with a launch template for output AMIs ](#create-ami-dist-win-fast-launch) + [ ## Example: Create distribution settings for output VM disks from the AWS CLI ](#cli-create-vm-dist-config) ## AMI distribution prerequisites Some distribution settings have prerequisites, as follows: **Topics** + [SSM output parameter prerequisites](#ami-distribution-prereqs-ssm-param) + [EC2 Fast Launch prerequisites](#ami-distribution-prereqs-fast-launch) ### Prerequisites for SSM output parameters SSM output parameter prerequisites Before you create a new AMI distribution configuration that sets an AWS Systems Manager Parameter Store parameter (SSM parameter), ensure that you've met the following prerequisites. **Execution role** When you create a pipeline or use the create-image command in the AWS CLI, you can only specify one Image Builder execution role. If you have defined an Image Builder workflow execution role, you would add any additional feature permissions to that role. Otherwise, you would create a new custom role that includes the required permissions. + To store the output AMI ID in an SSM parameter during distribution, you must specify the `ssm:PutParameter` action in your Image Builder execution role, with the parameter listed as a resource. + When you set the parameter data type to `AWS EC2 Image` to signal Systems Manager to validate the parameter value as an AMI ID, you must also add the `ec2:DescribeImages` action. ### Prerequisites for EC2 Fast Launch EC2 Fast Launch prerequisites Before you create a new distribution configuration for EC2 Fast Launch for Windows AMIs, ensure that you've met the following prerequisites. + If you provide a custom launch template when you configure EC2 Fast Launch, the service uses the VPC and other configuration settings that you've defined in the launch template. For more information, see [Use a launch template when you set up EC2 Fast Launch](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/win-fast-launch-configure.html#win-fast-launch-with-template). + If you don't use a custom launch template to configure your settings, you must attach the [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-iam-awsmanpol-EC2FastLaunchFullAccess.html](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-iam-awsmanpol-EC2FastLaunchFullAccess.html) policy to the IAM role that Image Builder uses to create your image. When you create a pipeline or use the create-image command in the AWS CLI, you can only specify one Image Builder execution role. If you have defined an Image Builder workflow execution role, you would add any additional feature permissions to that role. Otherwise, you would create a new custom role that includes the required permissions. Then, when Image Builder copies your image, EC2 Fast Launch automatically creates an CloudFormation stack with the following resources in your AWS account. + A virtual private cloud (VPC) + Private subnets across multiple Availability Zones + A launch template configured with Instance Metadata Service Version 2 (IMDSv2) + A security group with no inbound or outbound rules **Note** Image Builder doesn't support cross-account distribution for AMIs with EC2 Fast Launch pre-enabled. EC2 Fast Launch must be enabled from the destination account. ## Create an AMI distribution configuration Distribution configurations include the output AMI name, specific Region settings for encryption, launch permissions, and AWS accounts, organizations, and organizational units (OUs) that can launch the output AMI, and license configurations. A distribution configuration allows you to specify the name and description of your output AMI, authorize other AWS accounts to launch the AMI, copy the AMI to other accounts, and replicate the AMI to other AWS Regions. It also allows you to export the AMI to Amazon Simple Storage Service (Amazon S3), or configure EC2 Fast Launch for output Windows AMIs. To make an AMI public, set the launch permission authorized accounts to `all`. See the examples for making an AMI public at EC2 **[ModifyImageAttribute](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyImageAttribute.html)**. ------ #### [ Console ] Follow these steps to create a new AMI distribution configuration in the AWS Management Console: 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. Choose **Distribution settings** from the navigation pane. This shows a list of the distribution configurations that are created under your account. 1. Choose **Create distribution settings** near the top of the **Distribution settings** panel. 1. In the **Image type** section, choose the **Amazon Machine Image (AMI)** output type. 1. In the **General** section, enter a **Name** for your distribution configuration, and optional description. 1. In the **Region settings** section, enter the following details for each Region where you are distributing your AMI: 1. The AMI is distributed to the current Region (**Region 1**), by default. **Region 1** is the source for the distribution. Some settings for **Region 1** are not open for editing. For any Regions that you add, you can choose a Region from the **Region** dropdown list. The **Kms key** identifies the AWS KMS key that's used to encrypt the EBS volumes for your image in the target Region. It's important to note that this doesn't apply for the original AMI that the build creates under your account in the source Region (**Region 1**). Encryption that runs during the distribution phase of the build is only for images that are distributed to other accounts or Regions. To encrypt the EBS volumes for the AMI that's created in the source Region for your account, you must set the KMS key in the image recipe block device mapping (**Storage (volumes)** in the console). Image Builder copies the AMI to the **Target accounts** that you specify for the Region. **Prerequisite** To copy an image across accounts, you must create the `EC2ImageBuilderDistributionCrossAccountRole` role in all of the distribution target accounts, and attach the [Ec2ImageBuilderCrossAccountDistributionAccess policy](security-iam-awsmanpol.md#sec-iam-manpol-Ec2ImageBuilderCrossAccountDistributionAccess) managed policy to the role. The **Output AMI name** is optional. If you provide a name, the final output AMI name includes an appended timestamp of when the AMI is built. If you do not specify a name, Image Builder appends the build timestamp to the recipe name. This ensures unique AMI names for each build. 1. With AMI sharing, you can grant access for specified AWS Principals to launch instances from your AMI. If you expand the **AMI sharing** section, you can enter the following details: + **Launch permissions** – Select **Private** if you want to keep your AMI private, and allow access for specific AWS Principals to launch an instance from your private AMI. Select **Public** if you want to make your AMI public. Any AWS Principal can launch an instance from your public AMI. + **Principals** – You can grant access for the following types of AWS Principals to launch instances: + **AWS account** – Grant access to a specific AWS account + **Organizational unit (OU)** – Grant access to an OU, and all of its child entities. Child entities include OUs and AWS accounts. + **Organization** – Grant access to your AWS Organizations, and all of its child entities. Child entities include OUs and AWS accounts. First, select the Principal type. Then enter the ID for the AWS Principal to which you want to grant access in the box to the right of the drop-down list. You can enter multiple IDs of different types. 1. You can expand the **License configuration** section to attach license configurations created with AWS License Manager to your Image Builder images. License configurations contain licensing rules based on the terms of your enterprise agreements. Image Builder automatically includes license configurations that were associated with your base AMI. 1. You can expand the **Launch template configuration** section to specify an EC2 launch template to use for launching instances from the AMI you create. If you are using an EC2 launch template, you can instruct Image Builder to create a new version of your launch template that includes the latest AMI ID after the build completes. To update the launch template, configure the settings as follows: + **Launch template name** – Select the name of the launch template that you want Image Builder to update. + **Set the default version** – Select this check box to update the launch template default version to the new version. To add another launch template configuration, choose **Add launch template configuration**. You can have up to five launch template configurations per Region. 1. You can expand the **SSM parameter configurations** section to configure an SSM parameter that will store the output AMI ID for the image that's distributed to the destination Region. You can optionally specify a distribution account in the Region. **Parameter name** – Enter the name for your parameter. For example `/output/image/param`. **Data type** – Keep the default value (`AWS EC2 Image`). This tells Systems Manager to validate the parameter value to ensure that it's a valid AMI ID. 1. To add distribution settings for another Region, choose **Add Region**. 1. Choose **Create settings** when you are done. ------ #### [ AWS CLI ] The following example shows how to use the **create-distribution-configuration** command to create a new distribution configuration for your AMI, using the AWS CLI. 1. **Create a CLI input JSON file** Use a file-editing tool to create a JSON file with keys shown in one of the following examples, and values that are valid for your environment. These examples define which AWS accounts, AWS Organizations or organizational units (OUs) have permission to launch the AMI you distribute to the specified Regions. Name the file `create-ami-distribution-configuration.json`, for use in the next step: **Example 1: Distribute to AWS accounts** This example distributes an AMI to two Regions, and specifies AWS accounts that have launch permissions in each Region. ``` { "name": "MyExampleAccountDistribution", "description": "Copies AMI to eu-west-1, and specifies accounts that can launch instances in each Region.", "distributions": [ { "region": "us-west-2", "amiDistributionConfiguration": { "name": "Name {{imagebuilder:buildDate}}", "description": "An example image name with parameter references", "amiTags": { "KeyName": "Some Value" }, "launchPermission": { "userIds": [ "987654321012" ] } } }, { "region": "eu-west-1", "amiDistributionConfiguration": { "name": "My {{imagebuilder:buildVersion}} image {{imagebuilder:buildDate}}", "amiTags": { "KeyName": "Some value" }, "launchPermission": { "userIds": [ "100000000001" ] } } } ] } ``` **Example 2: Distribute to Organizations and OUs** This example distributes an AMI to the source Region, and specifies organization and OU launch permissions. ``` { "name": "MyExampleAWSOrganizationDistribution", "description": "Shares AMI with the Organization and OU", "distributions": [ { "region": "us-west-2", "amiDistributionConfiguration": { "name": "Name {{ imagebuilder:buildDate }}", "launchPermission": { "organizationArns": [ "arn:aws:organizations::123456789012:organization/o-myorganization123" ], "organizationalUnitArns": [ "arn:aws:organizations::123456789012:ou/o-123example/ou-1234-myorganizationalunit" ] } } } ] } ``` **Example 3: Store the output AMI ID in an SSM parameter** This example stores the output AMI ID in an AWS Systems Manager Parameter Store parameter in the distribution Region. ``` { "name": "SSMParameterOutputAMI", "description": "Updates an SSM parameter with the output AMI ID for the distribution.", "distributions": [ { "region": "us-west-2", "amiDistributionConfiguration": { "name": "Name {{ imagebuilder:buildDate }}" }, "ssmParameterConfigurations": [ { "amiAccountId": "111122223333", "parameterName": "/output/image/param", "dataType": "aws:ec2:image" } ] } ] } ``` 1. **Run the following command, using the file you created as input.** ``` aws imagebuilder create-distribution-configuration --cli-input-json file://create-ami-distribution-configuration.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). For more detailed information, see **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)** in the *AWS CLI Command Reference*. ------ ## Update an AMI distribution configuration You can change your AMI distribution configuration. However, the changes you make do not apply to any resources that Image Builder has already distributed. For example, if you have distributed an AMI to a Region that you later remove from your distribution, the AMI that was already distributed remains in that Region until you remove it manually. ------ #### [ AWS Management Console ] Follow these steps to an AMI distribution configuration in the AWS Management Console: 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. Choose **Distribution settings** from the navigation pane. This shows a list of the distribution configurations that are created under your account. 1. To view details or update a distribution configuration, choose the **Configuration name** link. This opens the detail view for the distribution settings. **Note** You can also select the check box next to the **Configuration name**, then choose **View details**. 1. To edit distribution configuration, choose **Edit** from the upper right corner of the **Distribution details** section. Some fields are locked, such as the **Name** of the distribution configuration, and the default **Region** that is displayed as **Region 1**. For more information about the distribution configuration settings, see [Create an AMI distribution configuration](#create-ami-distribution-config). 1. Choose **Save changes** when you are done. ------ #### [ AWS CLI ] The following example shows how to use the **[update-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-distribution-configuration.html)** command to update distribution settings for your AMI, using the AWS CLI. 1. **Create a CLI input JSON file** Use a file-editing tool to create a JSON file with the keys shown in the following example, and values that are valid for your environment. This example uses a file named `update-ami-distribution-configuration.json`. ``` { "distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/update-ami-distribution-configuration.json", "description": "Copies AMI to eu-west-2, and specifies accounts that can launch instances in each Region.", "distributions": [ { "region": "us-west-2", "amiDistributionConfiguration": { "name": "Name {{imagebuilder:buildDate}}", "description": "An example image name with parameter references", "launchPermissions": { "userIds": [ "987654321012" ] } } }, { "region": "eu-west-2", "amiDistributionConfiguration": { "name": "My {{imagebuilder:buildVersion}} image {{imagebuilder:buildDate}}", "tags": { "KeyName": "Some value" }, "launchPermissions": { "userIds": [ "100000000001" ] } } } ] } ``` 1. **Run the following command, using the file you created as input.** ``` aws imagebuilder update-distribution-configuration --cli-input-json file://update-ami-distribution-configuration.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). For more detailed information, see **[update-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-distribution-configuration.html)** in the *AWS CLI Command Reference*. To update tags for your distribution configuration resource, see the [Tag resources](tag-resources.md) section. ------ ## Example: Enable EC2 Fast Launch with a launch template for output AMIs The following example shows how to use the **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)** command with a launch template to create distribution settings that have EC2 Fast Launch configured for your AMI, from the AWS CLI. To configure EC2 Fast Launch settings without a launch template, ensure that you've met all of the [EC2 Fast Launch prerequisites](#ami-distribution-prereqs-fast-launch) before you create your distribution configuration. 1. **Create a CLI input JSON file** Use a file editing tool to create a JSON file with keys as shown in the following example, plus values that are valid for your environment. This example launches instances for all of its target resources simultaneously, because the maximum number of parallel launches is greater than the target resource count. This file is named `ami-dist-config-win-fast-launch.json` in the command example shown in the next step. ``` { "name": "WinFastLaunchDistribution", "description": "An example of Windows AMI EC2 Fast Launch settings in the distribution configuration.", "distributions": [ { "region": "us-west-2", "amiDistributionConfiguration": { "name": "Name {{imagebuilder:buildDate}}", "description": "Includes Windows AMI EC2 Fast Launch settings.", "amiTags": { "KeyName": "Some Value" } }, "fastLaunchConfigurations": [{ "enabled": true, "snapshotConfiguration": { "targetResourceCount": 5 }, "maxParallelLaunches": 6, "launchTemplate": { "launchTemplateId": "lt-0ab1234c56d789012", "launchTemplateVersion": "1" } }], "launchTemplateConfigurations": [{ "launchTemplateId": "lt-0ab1234c56d789012", "setDefaultVersion": true }] }] } ``` **Note** You can specify the `launchTemplateName` instead of the `launchTemplateId` in the `launchTemplate` section, but you can't specify both the name and Id. 1. **Run the following command, using the file you created as input.** ``` aws imagebuilder create-distribution-configuration --cli-input-json file://ami-dist-config-win-fast-launch.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). For more detailed information, see **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)** in the *AWS CLI Command Reference*. ## Example: Create distribution settings for output VM disks from the AWS CLI The following example shows how to use the **create-distribution-configuration** command to create distribution settings that will export VM image disks to Amazon S3 with every image build. 1. **Create a CLI input JSON file** You can streamline the **create-distribution-configuration** command that you use in the AWS CLI. To do this, create a JSON file that contains all of the export configuration that you want to pass into the command. **Note** The naming convention for the data values in the JSON file follows the pattern that is specified for the Image Builder API operation request parameters. To review the API operation request parameters, see the **[CreateDistributionConfiguration](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateDistributionConfiguration.html)** command in the *EC2 Image Builder API Reference*. To provide the data values as command line parameters, refer to the parameter names specified in the *AWS CLI Command Reference*. to the **create-distribution-configuration** command as options. Here is a summary of the parameters that we specify in the `s3ExportConfiguration` JSON object for this example: + **roleName** (string, required) – The name of the role that grants VM Import/Export permission to export images to your S3 bucket. + **diskImageFormat** (string, required) – Export the updated disk image to one of the following supported formats: + **Virtual Hard Disk (VHD)** – Compatible with Citrix Xen and Microsoft Hyper-V virtualization products. + **Stream-optimized ESX Virtual Machine Disk (VMDK)** – Compatible with VMware ESX and VMware vSphere versions 4, 5, and 6. + **Raw** – Raw format. + **s3Bucket** (string, required) – The S3 bucket in which to store the output disk images for your VM. Save the file as `export-vm-disks.json`. Use the file name in the **create-distribution-configuration** command. ``` { "name": "example-distribution-configuration-with-vm-export", "description": "example", "distributions": [ { "region": "us-west-2", "amiDistributionConfiguration": { "description": "example-with-vm-export" }, "s3ExportConfiguration": { "roleName": "vmimport", "diskImageFormat": "RAW", "s3Bucket": "vm-bucket-export" } }], "clientToken": "abc123def4567ab" } ``` 1. **Run the following command, using the file you created as input.** ``` aws imagebuilder create-distribution-configuration --cli-input-json file://export-vm-disks.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). For more detailed information, see **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)** in the *AWS CLI Command Reference*. # Create and update distribution settings for container images Create and update container image distribution This section covers creating and updating distribution settings for Image Builder container images. **Topics** + [ ## Create distribution settings for Image Builder container images from the AWS CLI ](#cli-create-container-distribution-configuration) + [ ## Update distribution settings for your container image from the AWS CLI ](#cli-update-container-distribution-configuration) ## Create distribution settings for Image Builder container images from the AWS CLI A distribution configuration enables you to specify the name and description of your output container image and replicate the container image to other AWS Regions. You can also apply separate tags to the distribution configuration resource and to the container images within each Region. 1. **Create a CLI input JSON file** Use your favorite file-editing tool to create a JSON file with the keys shown in the following example, plus values that are valid for your environment. This example uses a file named `create-container-distribution-configuration.json`: ``` { "name": "distribution-configuration-name", "description": "Distributes container image to Amazon ECR repository in two regions.", "distributions": [ { "region": "us-west-2", "containerDistributionConfiguration": { "description": "My test image.", "targetRepository": { "service": "ECR", "repositoryName": "testrepo" }, "containerTags": ["west2", "image1"] } }, { "region": "us-east-1", "containerDistributionConfiguration": { "description": "My test image.", "targetRepository": { "service": "ECR", "repositoryName": "testrepo" }, "containerTags": ["east1", "imagedist"] } } ], "tags": { "DistributionConfigurationTestTagKey1": "DistributionConfigurationTestTagValue1", "DistributionConfigurationTestTagKey2": "DistributionConfigurationTestTagValue2" } } ``` 1. **Run the following command, using the file you created as input.** ``` aws imagebuilder create-distribution-configuration --cli-input-json file://create-container-distribution-configuration.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). For more detailed information, see **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)** in the *AWS CLI Command Reference*. ## Update distribution settings for your container image from the AWS CLI The following example shows how to use the **[update-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-distribution-configuration.html)** command to update distribution settings for your container image, using the AWS CLI. You can also update tags for the container images within each Region. 1. **Create a CLI input JSON file** Use your favorite file-editing tool to create a JSON file with keys shown in the following example, plus values that are valid for your environment. This example uses a file named `update-container-distribution-configuration.json`: ``` { "distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/update-container-distribution-configuration.json", "description": "Distributes container image to Amazon ECR repository in two regions.", "distributions": [ { "region": "us-west-2", "containerDistributionConfiguration": { "description": "My test image.", "targetRepository": { "service": "ECR", "repositoryName": "testrepo" }, "containerTags": ["west2", "image1"] } }, { "region": "us-east-2", "containerDistributionConfiguration": { "description": "My test image.", "targetRepository": { "service": "ECR", "repositoryName": "testrepo" }, "containerTags": ["east2", "imagedist"] } } ] } ``` 1. **Run the following command, using the file you created as input:** ``` aws imagebuilder update-distribution-configuration --cli-input-json file://update-container-distribution-configuration.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). For more detailed information, see **[update-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-distribution-configuration.html)** in the *AWS CLI Command Reference*. To update tags for your distribution configuration resource, see the [Tag resources](tag-resources.md) section. # Set up cross-account AMI distribution with Image Builder Set up cross-account AMI distribution This section describes how you can configure distribution settings to deliver an Image Builder AMI to other accounts that you specify. The destination account can then launch or modify the AMI, as needed. **Note** AWS CLI command examples in this section assume that you have previously created image recipe and infrastructure configuration JSON files. To create the JSON file for an image recipe, see [Create an image recipe with the AWS CLI](create-image-recipes.md#create-image-recipe-cli). To create the JSON file for an infrastructure configuration, see [Create an infrastructure configuration](create-infra-config.md). ## Prerequisites for cross-account AMI distribution To ensure that target accounts can successfully launch instances from your Image Builder image, you must configure the appropriate permissions for all destination accounts in all Regions. If you encrypt your AMI using AWS Key Management Service (AWS KMS), you must configure an AWS KMS key for your account that is used to encrypt the new image. When Image Builder performs cross-account distribution for encrypted AMIs, the image in the source account is decrypted and pushed to the target Region, where it is re-encrypted using the designated key for that Region. Because Image Builder acts on behalf of the target account, and uses an IAM role that you create in the destination Region, that account must have access to keys in both the source and destination Regions. ### Encryption keys The following prerequisites are required if your image is encrypted using AWS KMS. IAM prerequisites are covered in the next section. **Source account requirements** + Create a KMS key in your account in all Regions where you build and distribute your AMI. You can also use an existing key. + Update the key policy for all of those keys to allow destination accounts to use your key. **Destination account requirements** + Add an inline policy to `EC2ImageBuilderDistributionCrossAccountRole` that allows the role to perform the required actions to distribute an encrypted AMI. For IAM configuration steps, see the [IAM policies](#cross-account-prereqs-iam) prerequisites section. For more information about cross-account access using AWS KMS, see [Allowing users in other accounts to use a KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying-external-accounts.html) in the *AWS Key Management Service Developer Guide*. Specify your encryption key in the image recipe, as follows: + If you are using the Image Builder console, choose your encryption key from the **Encryption (KMS alias)** dropdown list in the **Storage (volumes)** section of your recipe. + If you are using the **CreateImageRecipe** API action, or the **create-image-recipe** command in the AWS CLI, configure your key in the `ebs` section under `blockDeviceMappings` in your JSON input. The following JSON snippet shows encryption settings for an image recipe. In addition to providing your encryption key, you must also set the `encrypted` flag to `true`. ``` { ... "blockDeviceMappings": [ { "deviceName": "Example root volume", "ebs": { "deleteOnTermination": true, "encrypted": true, "iops": 100, "kmsKeyId": "image-owner-key-id", ... }, ... }], ... } ``` ### IAM policies To configure cross-account distribution permissions in AWS Identity and Access Management (IAM), follow these steps: 1. To use Image Builder AMIs that are distributed across accounts, the destination account owner must create a new IAM role in their account called `EC2ImageBuilderDistributionCrossAccountRole`. 1. They must attach the [Ec2ImageBuilderCrossAccountDistributionAccess policy](security-iam-awsmanpol.md#sec-iam-manpol-Ec2ImageBuilderCrossAccountDistributionAccess) to the role to enable cross-account distribution. For more information about managed policies, see [Managed Policies and Inline Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) in the *AWS Identity and Access Management User Guide*. 1. Verify that the source account ID is added to the trust policy attached to the IAM role of the destination account. The following example shows a trust policy in the destination account that specifies the account ID from the source account. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::444455556666:root" }, "Action": "sts:AssumeRole" }] } ``` ------ For more information about trust policies, see [Resource-Based Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_resource-based) in the *AWS Identity and Access Management User Guide*. 1. If the AMI you distribute is encrypted, the destination account owner must add the following inline policy to the `EC2ImageBuilderDistributionCrossAccountRole` in their account so that they can use your KMS keys. The `Principal` section contains their account number. This enables Image Builder to act on their behalf when it uses AWS KMS to encrypt and decrypt the AMI with the appropriate keys for each Region. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowRoleToPerformKMSOperationsOnBehalfOfTheDestinationAccount", "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey", "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], "Resource": "*" } ] } ``` ------ For more information about inline policies, see [Inline Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#inline-policies) in the *AWS Identity and Access Management User Guide*. 1. If you are using `launchTemplateConfigurations` to specify an Amazon EC2 launch template, you must also add the following policy to your `EC2ImageBuilderDistributionCrossAccountRole` in each destination account. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ec2:CreateLaunchTemplateVersion", "ec2:ModifyLaunchTemplate" ], "Resource": "*", "Condition": { "StringEquals": { "aws:ResourceTag/CreatedBy": "EC2 Image Builder" } } }, { "Effect": "Allow", "Action": [ "ec2:DescribeLaunchTemplates" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ec2:CreateTags" ], "Resource": "arn:aws:ec2:*:*:launch-template/*", "Condition": { "StringEquals": { "aws:RequestTag/CreatedBy": "EC2 Image Builder" } } } ] } ``` ------ 1. If you use an AWS Systems Manager Parameter Store parameter to store the AMI ID of the output AMI for the distribution account and Region, you must add the following policy to your `EC2ImageBuilderDistributionCrossAccountRole` in each destination account. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:PutParameter" ], "Resource": "arn:aws:ssm:*:111122223333:parameter/ImageBuilder-*" }, { "Effect": "Allow", "Action": [ "ec2:DescribeImages" ], "Resource": "*" } ] } ``` ------ ## Limits for cross-account distribution There are some limitations when distributing Image Builder images across accounts: + The destination account is limited to 50 concurrent AMI copies for each destination Region. + If you want to copy a paravirtual (PV) virtualization AMI to another Region, the destination Region must support PV virtualization AMIs. For more information, see [Linux AMI virtualization types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/virtualization_types.html). + You cannot create an unencrypted copy of an encrypted snapshot. If you don't specify an AWS Key Management Service (AWS KMS) customer managed key for the `KmsKeyId` parameter, Image Builder uses the default key for Amazon Elastic Block Store (Amazon EBS). For more information, see [Amazon EBS Encryption](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html) in the *Amazon Elastic Compute Cloud User Guide*. For more information, see [CreateDistributionConfiguration](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateDistributionConfiguration.html) in the *EC2 Image Builder API Reference*. ## Configure cross-account distribution for an Image Builder AMI from the console This section describes how to create and configure distribution settings for cross-account distribution of your Image Builder AMIs using the AWS Management Console. Configuring cross-account distribution requires specific IAM permissions. You must complete the [Prerequisites for cross-account AMI distribution](#cross-account-dist-prereqs) for this section before you continue. To create distribution settings 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/). 1. Choose **Distribution settings** from the navigation pane. This shows a list of the distribution settings that are created under your account. 1. At the top of the **Distribution settings** page, choose **Create distribution settings**. This takes you to the **Create distribution settings** page. 1. In the **Image type** section, choose **Amazon Machine Image (AMI)** as the **Output type**. This is the default setting. 1. In the **General** section, enter the **Name** of the distribution settings resource that you want to create (*required*). 1. In the **Region settings** section, enter a 12-digit account ID that you want to distribute your AMI to in **Target accounts** for the selected Region, and press **Enter**. This checks for the correct formatting, and then displays the account ID that you entered below the box. Repeat the process to add more accounts. To remove an account that you entered, choose the **X** displayed to the right of the account ID. Enter the **Output AMI name** for each Region. 1. Continue specifying any additional settings that you require, and choose **Create settings** to create your new distribution settings resource. ## Configure cross-account distribution for an Image Builder AMI from the AWS CLI This section describes how to configure a distribution settings file and use the **create-image** command in the AWS CLI to build and distribute an Image Builder AMI across accounts. Configuring cross-account distribution requires specific IAM permissions. You must complete the [Prerequisites for cross-account AMI distribution](#cross-account-dist-prereqs) for this section before you run the **create-image** command. 1. **Configure a distribution settings file** Before you use the **create-image** command in the AWS CLI to create an Image Builder AMI that is distributed to another account, you must create a `DistributionConfiguration` JSON structure that specifies the target account IDs in the `AmiDistributionConfiguration` settings. You must specify at least one `AmiDistributionConfiguration` in the source Region. The following sample file, named `create-distribution-configuration.json`, shows configuration for cross-account image distribution in the source Region. ``` { "name": "cross-account-distribution-example", "description": "Cross Account Distribution Configuration Example", "distributions": [ { "amiDistributionConfiguration": { "targetAccountIds": ["123456789012", "987654321098"], "name": "Name {{ imagebuilder:buildDate }}", "description": "ImageCopy Ami Copy Configuration" }, "region": "us-west-2" } ] } ``` 1. **Create the distribution settings** To create an Image Builder distribution settings resource using the [create-distribution-configuration](https://docs.aws.amazon.com/cli/latest/reference/imagebuilder/create-distribution-configuration.html) command in the AWS CLI, provide the following parameters in the command: + Enter the name of the distribution in the `--name` parameter. + Attach the distribution configuration JSON file you created in the `--cli-input-json` parameter. ``` aws imagebuilder create-distribution-configuration --name my distribution name --cli-input-json file://create-distribution-configuration.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). *You can also provide JSON directly in the command, using the `--distributions` parameter.* # Configure AMI distribution with an EC2 launch template Specify an AMI launch template To help ensure a consistent launch experience for your Image Builder AMI in target accounts and Regions, you can specify an Amazon EC2 launch template in your distribution settings, using `launchTemplateConfigurations`. When `launchTemplateConfigurations` are present during the distribution process, Image Builder creates a new version of the launch template that includes all of the original settings from the template, and the new AMI ID from the build. For more information about launching an EC2 instance using a launch template, see one of the following links, depending on your target operating system. + [Launch a Linux instance from a launch template](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-launch-templates.html) + [Launch a Windows instance from a launch template](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-launch-templates.html) **Note** When you include a launch template to enable Windows Fast Launch in your image, the launch template must include the following tag so that Image Builder can enable Windows Fast Launch on your behalf. `CreatedBy: EC2 Image Builder` ## Add an EC2 launch template to AMI distribution settings from the console To provide a launch template with your output AMI, follow these steps in the console: 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. Choose **Distribution settings** from the navigation pane. This shows a list of the distribution settings that are created under your account. 1. At the top of the **Distribution settings** page, choose **Create distribution settings**. This opens the **Create distribution settings** page. 1. In the **Image type** section, choose the **Amazon Machine Image (AMI)** **Output type**. This is the default setting. 1. In the **General** section, enter the **Name** of the distribution settings resource that you want to create (*required*). 1. In the **Region settings** section, select the name of an EC2 launch template from the list. If there are no launch templates in your account, choose **Create new launch template**, which opens the **Launch Templates** in the **EC2 Dashboard**. Select the **Set the default version** check box to update the launch template default version to the new version that Image Builder creates with your output AMI. To add another launch template to the selected Region, choose **Add launch template configuration**. To remove a launch template, choose **Remove**. 1. Continue specifying any additional settings that you require, and choose **Create settings** to create your new distribution settings resource. ## Add an EC2 launch template to AMI distribution settings from the AWS CLI This section describes how to configure a distribution settings file with a launch template, and use the **create-image** command in the AWS CLI to build and distribute an Image Builder AMI and a new version of the launch template that uses it. 1. **Configure a distribution settings file** Before you can create an Image Builder AMI with a launch template, using the AWS CLI, you must create a distribution configuration JSON structure that specifies the `launchTemplateConfigurations` settings. You must specify at least one `launchTemplateConfigurations` entry in the source Region. The following sample file, named `create-distribution-config-launch-template.json`, shows a few possible scenarios for launch template configuration in the source Region. ``` { "name": "NewDistributionConfiguration", "description": "This is just a test", "distributions": [ { "region": "us-west-2", "amiDistributionConfiguration": { "name": "test-{{imagebuilder:buildDate}}-{{imagebuilder:buildVersion}}", "description": "description" }, "launchTemplateConfigurations": [ { "launchTemplateId": "lt-0a1bcde2fgh34567", "accountId": "935302948087", "setDefaultVersion": true }, { "launchTemplateId": "lt-0aaa1bcde2ff3456" }, { "launchTemplateId": "lt-12345678901234567", "accountId": "123456789012" } ] } ], "clientToken": "clientToken1" } ``` 1. **Create the distribution settings** To create an Image Builder distribution settings resource using the [create-distribution-configuration](https://docs.aws.amazon.com/cli/latest/reference/imagebuilder/create-distribution-configuration.html) command in the AWS CLI, provide the following parameters in the command: + Enter the name of the distribution in the `--name` parameter. + Attach the distribution configuration JSON file you created in the `--cli-input-json` parameter. ``` aws imagebuilder create-distribution-configuration --name my distribution name--cli-input-json file://create-distribution-config-launch-template.json ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). *You can also provide JSON directly in the command, using the `--distributions` parameter.* # Use enhanced AMI distribution capabilities Use enhanced AMI distribution 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. 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. ## Decoupled Distribution The DistributeImage API accepts three types of source image references: + **AMI ID** – A standard AMI identifier (for example, `ami-0abcdef1234567890`) + **SSM Parameter** – An SSM parameter that stores an AMI ID (for example, `ssm:/my/ami/parameter`) + **Image Builder version ARN** – An Image Builder image version ARN ## Distribution Retry 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 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** 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. + You have the necessary IAM permissions to retry the image build. + For cross-account distribution failures, verify that the `EC2ImageBuilderDistributionCrossAccountRole` in the destination account has the `Ec2ImageBuilderCrossAccountDistributionAccess` policy attached. **Important:** Retrying without fixing the underlying issue will result in repeated failures. ## Distribution Workflows 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. To learn more about creating and customizing workflows, see [Manage Image Workflows](manage-image-workflows.html).