Set up cross-account AMI distribution with Image Builder

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.

They must attach the Ec2ImageBuilderCrossAccountDistributionAccess policy to the role to enable cross-account distribution. For more information about managed policies, see Managed Policies and Inline Policies in the Amazon Identity and Access Management User Guide.

Verify that the source account ID is added to the trust policy attached to the IAM role of the destination account. For more information about trust policies, see Resource-Based Policies in the Amazon Identity and Access Management User Guide.

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 Amazon KMS to encrypt and decrypt the AMI with the appropriate keys for each Region.

{
	"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 in the Amazon Identity and Access Management User Guide.

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.

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

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 settings that are created under your account.

At the top of the Distribution settings page, choose Create distribution settings. This takes you to the Create distribution settings page.

In the Image type section, choose Amazon Machine Image (AMI) as the Output type. This is the default setting.

In the General section, enter the Name of the distribution settings resource that you want to create (required).

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.

Continue specifying any additional settings that you require, and choose Create settings to create your new distribution settings resource.

Configure a distribution settings file

Before you use the create-image command in the Amazon 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"
		}
	]
}

Create the distribution settings

To create an Image Builder distribution settings resource using the create-distribution-configuration command in the Amazon CLI, provide the following parameters in the command:

aws imagebuilder create-distribution-configuration --name my distribution name --cli-input-json file://create-distribution-configuration.json