Create and update AMI distribution configurations

Open the EC2 Image Builder console at https://console.amazonaws.cn/imagebuilder/.

Choose Distribution settings from the navigation pane. This shows a list of the distribution configurations that are created under your account.

Choose Create distribution settings near the top of the Distribution settings panel.

In the Image type section, choose the Amazon Machine Image (AMI) output type.

In the General section, enter a Name for your distribution configuration, and optional description.

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 Amazon 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 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 Amazon 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 Amazon Principals to launch an instance from your private AMI. Select Public if you want to make your AMI public. Any Amazon Principal can launch an instance from your public AMI.

      • Principals – You can grant access for the following types of Amazon Principals to launch instances:

        • Amazon account – Grant access to a specific Amazon account

        • Organizational unit (OU) – Grant access to an OU, and all of its child entities. Child entities include OUs and Amazon accounts.

        • Organization – Grant access to your Amazon Organizations, and all of its child entities. Child entities include OUs and Amazon accounts.

          First, select the Principal type. Then enter the ID for the Amazon 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.

   2. You can expand the License configuration section to attach license configurations created with Amazon 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.

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

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

2. To add distribution settings for another Region, choose Add Region.

Choose Create settings when you are done.

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 Amazon Web Services accounts, Amazon 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 Amazon Web Services accounts

This example distributes an AMI to two Regions, and specifies Amazon Web Services 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 Amazon 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"
				}
			]
		}
	]
}

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

For more detailed information, see create-distribution-configuration in the Amazon CLI Command Reference.

Open the EC2 Image Builder console at https://console.amazonaws.cn/imagebuilder/.

Choose Distribution settings from the navigation pane. This shows a list of the distribution configurations that are created under your account.

To view details or update a distribution configuration, choose the Configuration name link. This opens the detail view for the distribution settings.

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.

Choose Save changes when you are done.

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"
					]
				}
			}
		}
	]
}

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

For more detailed information, see update-distribution-configuration in the Amazon CLI Command Reference. To update tags for your distribution configuration resource, see the Tag resources section.