View a markdown version of this page

Manage Image Builder distribution settings - EC2 Image Builder

Manage Image Builder 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.

A distribution configuration is a reusable resource that tells Image Builder where and how to deliver the output images that a build produces. You can attach one distribution configuration to a pipeline or to a CreateImage request, and you must specify one in a DistributeImage request. You manage distribution configurations from the Image Builder console, the Image Builder API, or imagebuilder commands in the AWS CLI. With a distribution configuration, Image Builder can perform the following actions:

AMI distribution

  • Specify the name and description of your output AMI.

  • Grant other AWS accounts, organizations, and OUs permission to launch instances from the AMI. The AMI stays in the owner account, and the owner account continues to pay for the AMI's snapshot storage. The accounts that launch instances from the AMI are billed for those instances. For more information about sharing your AMI with AWS Organizations and OUs, see Share an AMI with organizations and organizational units.

    Note

    To make an AMI public, set the launch permission authorized accounts to all. For information and examples, see ModifyImageAttribute in the Amazon EC2 API Reference.

    Important

    You cannot make AMIs with watermarks public. If your image recipe includes watermarks, or if the source AMI has watermarks attached, you cannot set launch permissions to public. Image Builder rejects the distribution configuration. Watermarks propagate automatically when you copy or distribute an AMI across Regions or accounts. For more information, see Track AMI lineage with watermarks.

  • Copy the output AMI into each target account that you specify in the destination Region. Each target account owns its copy of the AMI, and is billed for any associated charges. Organizations and OUs don't receive copies. To give them access, grant launch permission instead.

  • Copy the AMI to the owner's account in other AWS Regions. In a Region other than the one where the build runs, Image Builder copies the AMI to the owner's account only if you omit targetAccountIds or include the owner's account ID in it.

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

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:

  • 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 section of this guide.

Contents