Configuring KMS encryption at rest on ECR repositories with ECR replication

Introduction

In this blog post, you’ll learn how to configure AWS Key Management Service (AWS KMS) at rest on Amazon Elastic Container Registry (Amazon ECR) with image replication. By default, repository settings aren’t replicated, and with the information contained in this article, we’ll empower your organization to put security first while using the AWS tools and services that your teams are familiar with.

Customers in environments that are sensitive to compliance and regulatory concerns often want to enable encryption whenever possible. Enterprises want to secure their data footprints in transit and at rest, and container images are no exception to this posture.

With AWS KMS and Amazon ECR image replication, we can transfer the images across AWS Regions or AWS accounts, giving your business high availability while protecting your data in transit within the cloud.

Architecture

For cross-Region replication, below is the diagram for our solution:

The following diagram shows our solution for cross-Region and cross-account replication:

Walkthrough

Amazon ECR with AWS KMS encryption cross-Region replication

Following is an example of creating replication between two Amazon ECR repositories in two different Regions with AWS KMS encryption enabled. The order of the steps is crucially important. Please do not run the steps out of order.

To create an AWS KMS key in the primary Region

1. Open the AWS KMS console in the desired primary Region (for example, N. Virginia.
2. Choose Create Key.
3. Select Symmetric key type.
4. Select Encrypt and decrypt key usage.
5. Choose Next.
6. Enter an Alias for your AWS KMS key (for example, “ECR KMS Key”).
7. Choose Next.
8. In the Define key administrative permissions field, choose an IAM user or role.
9. Choose Next.
10. In the Define key usage permission field, choose an IAM user and/or role.
    1. Make sure your IAM user or role is also selected. This will be required for Amazon ECR to encrypt and decrypt the container image.
11. Choose Next.
12. Choose Finish.

To create an Amazon ECR repository in the primary Region

1. Open the Amazon ECR console in the desired primary Region (for example, N. Virginia)
2. Choose Get Started.
3. Choose Private as visibility settings.
4. Enter your Repository Name (i.e., myrepo).
5. In the Encryption Settings section, do the following:
   1. Enable encryption.
   2. Choose Customize encryption settings (advanced).
   3. Choose the key we just created in the steps above.
6. Choose Create repository.

At this point, you have an Amazon ECR repository created with AWS KMS encryption enabled. Before enabling Amazon ECR replication, let’s create the Amazon ECR repository in the secondary Region.

To create the AWS KMS repository in the second Region

1. Open the AWS KMS console in the desired secondary Region (for example, Oregon).
2. Choose Create Key.
3. Select Symmetric key type.
4. Select Encrypt and decrypt key usage.
5. Choose Next.
6. Enter an Alias for your AWS KMS key (i.e., “ECR KMS Key”).
7. Choose Next.
8. In the Define key administrative permissions field, choose an IAM user or role.
9. Choose Next.
10. In the Define key usage permission field, choose an IAM user or role.
    1. Make sure your IAM User or role is also selected. This will be required for Amazon ECR to encrypt and decrypt the container image.
11. Choose Next.
12. Choose Finish.

To create an Amazon ECR repository in the primary Region

1. Open the Amazon ECR console in the desired secondary Region (for example, Oregon).
2. Choose Get Started.
3. Choose Private for the visibility settings.
4. Enter your Repository Name (for example, myrepo).
   1. It’s very important that you give the same repository name as in your primary Region. If repository names between primary and replicated Regions do not match, replication will fail.
5. In the Encryption settings section, do the following:
   1. Enable encryption.
   2. Choose Customize encryption settings (advanced).
   3. Choose the key we just created in the previous steps.
6. Choose Create repository.

If you would like to replicate the Amazon ECR repositories to other Regions, repeat the steps for the secondary Region on the desired Region.

Finally, let’s enable the Amazon ECR replication configuration.

To enable Amazon ECR replication

1. Open the Amazon ECR console in the primary Region (for example, N. Virginia.
2. In the navigation pane, choose Private registry, then choose Replication configuration and press Edit.
3. Choose Add rule.
4. Choose Cross-region replication for replications between Regions.
5. Choose Next.
6. Choose the Destination Regions(s) that you created in your secondary Amazon ECR repository(s) (for example, Oregon).
7. Choose Next.
8. In the Repository filters, do the following:
   1. Enter the repository name (for example, myrepo). It needs to match exactly with the repository name you created.
   2. Choose Add.
   3. Choose Next.
9. Choose Submit rule.

(Optional) Amazon ECR with AWS KMS encryption cross-account replication

(Optional) If you would like to enable cross-account replication, follow all the steps above with the secondary/destination Region to another AWS account, utilizing Amazon ECR replication we will need to create the cross-Region replication. Additionally, you will need to create an Amazon ECR replication rule and permission on the destination account.

(Optional) To enable a cross-account replication rule

1. Open the Amazon ECR console in the primary Region (for example, N. Virginia).
2. In the navigation pane, choose Private Registry, then choose Replication.
3. Choose Add rule.
4. Choose Cross-account replication for replications between accounts.
5. Choose Next.
6. Choose the destination account that you created your secondary Amazon ECR repository(s).
7. Choose the destination Regions that you would like Amazon ECR to replicate to the secondary AWS account.
8. Choose Next.
9. In the Repository filters, do the following:
   1. Enter the repository name (for example, myrepo). It needs to match exactly with the repository name you created.
   2. Choose Add.
   3. Choose Next.
10. Choose Submit rule.

(Optional) To enable cross-account replication permission

1. Open the Amazon ECR console in the secondary Region (for example, Oregon) in the other AWS account.
2. In the navigation pane, choose Private Registry, then choose Permission.
3. Choose Cross account replication policy in the Policy type.
4. Enter a Statement id (for example, “replication cross-account policy”).
5. In the Accounts section, enter the AWS account number where the primary Amazon ECR repository resides.
6. Choose Save statement.
7. The console will autogenerate a JSON IAM policy similar to the following:

   1. {
      "Sid": "ECRReplicationPermission",
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::999999999999:root"
        },
        "Action": [
          "ecr:CreateRepository",
          "ecr:ReplicateImage"
        ],
        "Resource": "arn:aws:ecr:us-east-1:12345678901:repository/*"
      }

Finally, you should be able to push an image into your primary account Amazon ECR repository, and automatically the image will be replicated to your secondary Amazon ECR account.

CloudFormation automation

The same solution can be achieved by deploying CloudFormation infrastructure-as-code (IaC) templates. These templates with instructions can be found in our GitHub repository

The repository contains two solutions:

• Cross-Region replication (same account)
• Cross-Region and Cross-account replication

Conclusion

In summary, we’ve described how you can enable encryption in transit for container images stored in Amazon ECR by using AWS KMS keys for image transfer between Regions or accounts.

We’ve reviewed the components involved and how they function together for secure transfer of the container image. Furthermore, we have successfully automated the functionality described allowing you to quickly enable the services in your own Regions and accounts.

If you have feedback about this post, please submit it in the comments section below. If you have questions about this post, please start a new thread on the Containers | AWS re:Post forum.