How do I troubleshoot distribution errors for encrypted AMIs in Image Builder?

5 minute read

I receive errors when I try to distribute encrypted AMIs to another account in EC2 Image Builder. How do I troubleshoot this?

Short description

The following scenarios can cause distribution errors in EC2 Image Builder when you distribute an encrypted Amazon Machine Image (AMI) to another account:

The AMI that's distributed is encrypted using the default AWS managed key for Amazon Elastic Block Store (Amazon EBS).
The AWS Key Management Service (AWS KMS) or AWS Identity and Access Management (IAM) entity doesn't have the required permissions.

Resolution

The AMI that's distributed is encrypted using the default AWS managed key for Amazon EBS

You receive the following error:

Distribution failed with JobId 'XXXXXXXXXXXXXX', status = 'Failed' for ARN 'arn:aws:imagebuilder:us-east-1:xxxxxxxxxxxx:image/test-recipe/0.0.1/1'. 'Not all distribution jobs are completed. 1) EC2 Client Error: 'Snapshots encrypted with the AWS Managed CMK can’t be shared. Specify another snapshot.' when distributing the image from the source account (ID: xxxxxxxxxxxx) to the destination account (ID: xxxxxxxxxxxx) in Region us-east-1.'

You can't share AMIs that are encrypted with the default AWS KMS key. For more information see, Share an AMI with specific AWS accounts.

Scenarios to check include:

The AWS managed KMS key is specified in the recipe's storage configuration.
The AWS managed KMS key is specified in the distribution configuration along with one or more target accounts.
The parent AMI is encrypted using the AWS managed KMS key.
The parent AMI has multiple snapshots, and at least one is encrypted with the AWS managed KMS key.
Encryption by default is activated in your AWS Region, and it's using the AWS managed KMS key.

To resolve this issue, create a new version of the image recipe, and specify a customer managed KMS key for encryption in the recipe's storage configuration. For KMS keys in the distribution configuration, specify a customer managed KMS key for encryption when you distribute AMIs to other accounts.

The AWS KMS or IAM entity doesn't have the required permissions

You can distribute AMIs in Image Builder using either the launchPermissions or targetAccountIds configurations.

launchPermissions

When you distribute an AMI using launchPermissions, Image Builder uses the IAM role AWSServiceRoleForImageBuilder in the source account. By default, AWSServiceRoleForImageBuilder has the required AWS KMS permission for the resources in the source account.

The KMS key policy has a statement that allows the "kms:*" action for the root user. If this statement isn't in the key policy, then the service-linked role can't access the key in the source account. If the "kms:*" action isn't allowed for the root user, then modify the policy to allow the service-linked role to use the key.

For example:

{
  "Sid": "Enable IAM User Permissions",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::source_account_id:role/aws-service-role/imagebuilder.amazonaws.com/AWSServiceRoleForImageBuilder"
  },
  "Action": [
    "kms:Decrypt",
    "kms:Encrypt",
    "kms:GenerateDataKeyWithoutPlaintext",
    "kms:DescribeKey",
    "kms:CreateGrant",
    "kms:ReEncryptFrom",
    "kms:ReEncryptTo"
  ],
  "Resource": "*"
}

Note: Replace source_account_id with your source account's ID.

targetAccountIds

If the destination account doesn't have the IAM role EC2ImageBuilderDistributionCrossAccountRole, or the source account isn't listed in the trust policy, then you receive the following error:

Distribution failed with JobId 'xxxxxxxxxxxxxx', status = 'Failed' for ARN 'arn:aws:imagebuilder:us-east-1:XXXXXXXXXX:image/testdistribution/2.0.0/3'. 'Not all distribution jobs are completed. 1) STS Client Error: 'User: arn:aws:sts::XXXXXXXXXXXX:assumed-role/AWSServiceRoleForImageBuilder/Ec2ImageBuilderIntegrationService is not authorized to perform: sts:AssumeRole on resource: arn:aws:iam::xxxxxxxxx:role/EC2ImageBuilderDistributionCrossAccountRole'. Please make sure your 'EC2ImageBuilderDistributionCrossAccountRole' is setup with correct permission policies. If you are copying AMI to opt-in regions, please make sure the region is enabled in the account when distributing the image from the source account (ID: XXXXXXXXXXXX) to the destination account (ID: XXXXXXXXXXXX) in Region us-east-1.'STS Client Error User is not authorized to perform: sts:AssumeRole on resource.

To resolve this issue, create the role EC2ImageBuilderDistributionCrossAccountRole. Then, attach the Ec2ImageBuilderCrossAccountDistributionAccess policy to allow cross-account distribution. Then, list AWSServiceRoleForImageBuilder in the EC2ImageBuilderDistributionCrossAccountRole trust policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ec2.amazonaws.com",
        "AWS": "arn:aws:iam::XXXXXXXXXX:root"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

You might receive the following error due to issues with cross-account AWS KMS permissions:

Distribution failed with JobId 'xxxxxxxxxxxxxx', status = 'Failed' for ARN 'arn:aws:imagebuilder:ap-southeast-2:11111111111:image/test/1.0.0/1'. 'Not all distribution jobs are completed. 1) AMI Copy Reported Failure For 'ami-0047623fbcxxxxx' when distributing the image from the source account (ID: 11111111111) to the destination account (ID: 222222222222) in Region ap-southeast-2.'

When you distribute an AMI using targetAccountIds, Image Builder uses the role AWSServiceRoleForImageBuilder in the source account. In the destination account, it uses the role EC2ImageBuilderDistributionCrossAccountRole. Make sure that you give permission to EC2ImageBuilderDistributionCrossAccountRole to use the AWS KMS keys in the distribution configuration and recipe's storage configuration.

For example:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:Encrypt",
        "kms:GenerateDataKeyWithoutPlaintext",
        "kms:DescribeKey",
        "kms:CreateGrant",
        "kms:ReEncryptFrom",
        "kms:ReEncryptTo"
      ],
      "Resource": "*"
    }
  ]
}

Note: You can also restrict the Resource section by specifying the ARN of the AWS KMS key.

If the customer managed KMS keys belong to the destination account, then you must share the AWS KMS key with the source account. If the customer managed KMS keys belong to the source account, then you must share the AWS KMS keys with the destination account.

Complete the following steps to share the AWS KMS keys:

1. Log in to the account where the KMS key is.

2. Open the AWS KMS console in the same AWS Region.

3. In left navigation pane, choose Customer managed keys.

4. Select the KMS key ID.

5. Choose the Key Policy tab.

6. In the Other AWS accounts section, choose Add other AWS accounts.

7. Specify the ID of the account that you want to share the KMS key with.

8. Choose Save Changes.