On Mar 16, 2022

Cheat Sheet: AWS Elastic Container Registry (ECR)

Kyler Middleton
Kyler MiddletonCloud IAM Advocate at IAM Pulse

AWS documentation is comprehensive, but it sometimes feels like you're reading the encyclopedia - there's just so much data! That's why we read the encyclopedia for you, and distilled down what we think are the most important flags for resources and services, and provide example IAM resource policies to give you a running start. Keep an eye out for this series as we build it out to include the most commonly (and most commonly misconfigured) services.

Link to PDF copy

Basics

The AWS Elastic Container Registry (ECR) is the native AWS service which hosts container images. These images can optionally be tagged for easy reference. The newest image pushed to the registry has the “:latest” tag, which can be referenced by other services - note this isn’t a best practice, and could include accidentally pushed or test pushes to the ECR. A best practice is to use specific versions, e.g. “ContainerName:v1.0.2”, and pin other services to those specific versions.

AWS ECR supports scan-on-push. When Scan-On-Push is enabled, ECR will scan a new image for security vulns, and provide a list of them with remediation and risk information right in the ECR.

ECR also permits encrypting images with a KMS key.

How Does IAM Fit?


Each ECR by default has no IAM policy, and permits same-account principals to access the ECR (provided the principal’s IAM policies permit this). However, an IAM policy can be added to limit access to the ECR to specific roles, or from specific public IPs. AWS has a specific ECR and IAM page, link. Images can optionally be encrypted with a KMS controlled private key, and the IAM policy on that resource can provide another layer of security for the images in each ECR.

Overview

Facts

  • ECRs are built to store potentially many versions of a single image. If you have two totally different images (not just the same image with different tags) to store, put them in two different ECRs
  • ECRs stored container images built by any tool (usually Docker), and each image is tagged with a specific image tag that is set by the tool uploading to ECR (e.g. :v1.0.2) as well as the “:latest” tag, which changes each time a new image is uploaded
  • Each ECR is set to either immutable (Once tag set, image can’t be changed) or mutable (Images can be over-written by a new upload)
  • Images can optionally be encrypted with KMS Amazon provided or customer-provided keys. This adds an additional security step, since access to the decryption key is also required to access the images

IAM Policy Examples
Several examples are listed below. For an up to date list of all stored policies, visit this page: https://www.iampulse.com/policies

Permit account B and C access to download images from ECR in account A. This uses a broad filter “:root” which indicates the entire account 222 and 333 are trusted. If principals in those accounts are granted rights to access this ECR, they will be permitted by this ECR resource policy.

1{
2  "Version" : "2008-10-17",
3  "Statement" : [
4    {
5      "Sid" : "Allow account B, C to access this ECR",
6      "Effect" : "Allow",
7      "Principal" : {
8        "AWS" : [
9          "arn:aws:iam::2222222222:root",
10          "arn:aws:iam::3333333333:root"
11        ]
12      },
13      "Action" : [
14        "ecr:GetDownloadUrlForLayer",
15        "ecr:BatchGetImage",
16        "ecr:BatchCheckLayerAvailability"
17      ]
18    }
19  ]
20}

You could instead permit only specific roles by using this principal syntax:

1{
2  "Version" : "2008-10-17",
3  "Statement" : [
4    {
5      "Sid" : "Allow account B, C to access this ECR",
6      "Effect" : "Allow",
7      "Principal" : {
8        "AWS" : [
9          "arn:aws:iam::2222222222:role/RoleNameXX",
10          "arn:aws:iam::3333333333:role/RoleNameYY"
11        ]
12      },
13      "Action" : [
14        "ecr:GetDownloadUrlForLayer",
15        "ecr:BatchGetImage",
16        "ecr:BatchCheckLayerAvailability"
17      ]
18    }
19  ]
20}

Configuration Options

IAM-Related Options

  • Permissions (none) - An IAM JSON document governing who can access. Defaults to blank, and permits same-account access (provided principal’s role permits). Can limit access to specific roles, regions, public IPs, etc.
    • Recommendation: For the most secure workloads, limit the roles that can access the ECR.
  • Encryption (AES256) - Encryption used to encrypt the stored images. Defaults to AES256, and access controlled only via IAM. If KMS is selected, images encrypted with that private key, and access can also be controlled by who can access the private key for decryption.
    • Recommendation: For the most secure workloads, use KMS CMK (customer keys) for encryption.
    • Warn: Changing this setting after creation will rebuild the resource and destroy any hosted images.

Other Options

  • Name - A name is required. Names must start with a letter and can only contain lowercase letters, numbers, hyphens, underscores, and forward slashes. Forward slashes can create a folder-like structure to be used for permissions granting.
  • Image Tag Mutability (Mutable) - Controls whether the image referenced by a tag can change.
    • Recommendation: The most reliable workloads set this to Immutable, and use a different tag for each version of the image published. This is relatively inflexible, setting should be based on business needs flexible vs reliable
  • Scan on Push (true) - Boolean, determines if security scanning should happen automatically on new image upload.
    • Note: AWS provides both “basic” scanning on native ECR, as well as “enhanced” scanning using the Inspector tool. More information here on the differences.
    • Recommendation: Basic scanning is both free and incredibly useful. Definitely set this to true.
  • Lifecycle Policy (none) - By default, all images are retained, which can quickly cost a great deal. A lifecycle policy automatically deletes images after XX amount of days, those with/without tags, or after a number of images is satisfied. More information here.

    Get the IAM Pulse Check Newsletter

    We send out a periodic newsletter full of tips & tricks, contributions from the community, commentary on the industry, relevant social posts, and more.

    Checkout past issues for a sampling of the goods.