AWS Security Blog
How to share encrypted AMIs across accounts to launch encrypted EC2 instances
May 18, 2023:We’ve updated the syntax in the JSON policy document in the Create the policy setting for the source account section.
August 31, 2021:AWS KMS is replacing the term customer master key (CMK) with AWS KMS key and KMS key. The concept has not changed. To prevent breaking changes, AWS KMS is keeping some variations of this term. More info.
October 30, 2019: We’ve updated Figure 2 and its accompanying steps to show the KMS console.
October 16, 2019: We’ve updated Figure 1 to show the KMS console.
August 26, 2019: We’ve corrected the name of the console in step one.
Do you encrypt your Amazon Machine Instances (AMIs) with AWS Key Management Service (AWS KMS) keys for regulatory or compliance reasons? Do you launch instances with encrypted root volumes? Do you create a golden AMI and distribute it to other accounts in your organization for standardizing application-specific Amazon Elastic Compute Cloud (Amazon EC2) instance launches? If so, then we have good news for you!
We’re happy to announce that you can now share AMIs encrypted with customer-managed KMS keys across accounts with a single API call. Additionally, you can launch an EC2 instance directly from an encrypted AMI that has been shared with you. Previously, this was possible for unencrypted AMIs only. Extending this capability to encrypted AMIs simplifies your AMI distribution process and reduces the snapshot storage cost associated with the older method of sharing encrypted AMIs that resulted in a copy in each of your accounts.
In this post, we demonstrate how you can share an encrypted AMI between accounts and launch an encrypted, Amazon Elastic Block Store (Amazon EBS) backed EC2 instance from the shared AMI.
Prerequisites for sharing AMIs encrypted with a customer-managed KMS keys
Before you can begin sharing the encrypted AMI and launching an instance from it, you’ll need to set up your AWS KMS key policy and AWS Identity and Access Management (IAM) policies.
For this walkthrough, you need two AWS accounts:
- A source account in which you build a custom AMI and encrypt the associated EBS snapshots.
- A target account in which you launch instances using the shared custom AMI with encrypted snapshots.
In this example, I’ll use fictitious account IDs 111111111111 and 999999999999 for the source account and the target account, respectively. In addition, you’ll need to create an AWS KMS key in the source account in the source region. For simplicity, I’ve created an AWS KMS key with the alias cmkSource under account 111111111111 in us-east-1. I’ll use this cmkSource to encrypt my AMI (ami-1234578) that I’ll share with account 999999999999. As you go through this post, be sure to change the account IDs, source account, AWS KMS key, and AMI ID to match your own.
Create the policy setting for the source account
First, an IAM user or role in the source account needs permission to share the AMI (an EC2 ModifyImageAttribute operation). The following JSON policy document shows an example of the permissions an IAM user or role policy needs to have. In order to share ami-12345678, you’ll need to create a policy like this:
Second, the target account needs permission to use cmkSource for re-encrypting the snapshots. The following steps walk you through how to add the target account’s ID to the cmkSource key policy.
- From the KMS console, select Customer managed keys in the left pane, and then select the source account’s KMS key, cmkSource, as shown in Figure 1:
Figure 1: Select “cmkSource”
- Look for the Other AWS accounts subsection and select Add other AWS accounts.
- In the arn:aws:iam:: field, enter the ID of your target account (for example, 999999999999), then select Add another AWS account.
Figure 2: Enter the target account ID and then select “Add another AWS account”
Create a policy setting for the target account
Once you’ve configured the source account, you need to configure the target account. The IAM user or role in the target account needs to be able to perform the AWS KMS DescribeKey, CreateGrant, ReEncrypt* and Decrypt operations on cmkSource in order to launch an instance from a shared encrypted AMI. The following JSON policy document shows an example of these permissions:
Once you’ve completed the configuration steps in the source and target accounts, then you’re ready to share and launch encrypted AMIs. The actual sharing of the encrypted AMI is no different from sharing an unencrypted AMI. If you want to use the AWS Management Console, then follow the steps described in Sharing an AMI (Console). To use the AWS Command Line Interface (AWS CLI), follow the steps described in Sharing an AMI (AWS CLI).
Below is an example of what the CLI command to share the AMI would look like:
Launch an instance from the shared encrypted AMI
To launch an AMI that was shared with you, set the AMI ID of the shared AMI in the image-id parameter of Run-Instances API/CLI. Optionally, to re-encrypt the volumes with a custom CMK in your account, you can specify the KmsKeyId in the Block Device Mapping as follows:
Where the mapping.json contains the following:
While launching the instance from a shared encrypted AMI, you can specify a KMS key of your choice. You may also choose cmkSource to encrypt volumes in your account. However, we recommend that you re-encrypt the volumes using a KMS key in the target account. This protects you if the source KMS key is compromised, or if the source account revokes permissions, which could cause you to lose access to any encrypted volumes you created using cmkSource.
Summary
In this blog post, we discussed how you can easily share encrypted AMIs across accounts to launch encrypted instances. AWS has extended the same capabilities to snapshots, allowing you to create encrypted EBS volumes from shared encrypted snapshots.
This feature is available through the AWS Management Console, AWS CLI, or AWS SDKs at no extra charge in all commercial AWS regions except China. If you have feedback about this blog post, submit comments in the Comments section below. If you have questions about this blog post, start a new thread on the Amazon EC2 forum or contact AWS Support.
Want more AWS Security how-to content, news, and feature announcements? Follow us on Twitter.