Using ECR as Cache Repository for public images

Efficient image management is essential for smooth deployments and stremlined development workflows and rely only on Docker Hub to pull public images can lead to rate limits and slower pulls.

Amazon Elastic Container Registry (ECR) offers a robust solution by serving as a cache repository for public Docker images. Leveraging ECR not only enhances the performance and reliability of image pulls but also provides advanced security features and integration with AWS services. In this blog post, we’ll explore how to set up and utilize Amazon ECR as a cache repository to simplify your container management processes.

Solution Overview

Amazon Elastic Container Registry (ECR) is a fully managed Docker container registry that simplifies storing, managing, and deploying container images securely and at scale. In this solution, we’ll use ECR as cache repository for public docker images originally sourced from Docker Hub eliminating the need of manual work , to benefit from advantages such as:

• Improved performance with faster image pulls and higher pull rate limits
• Enhanced security with support for image scanning to detect vulnerabilities and private access with AWS Private link
• High availability with a fully managed service that offers cross-region replication
• Seamless integration with AWS services like ECS, EKS, App Runner and Code Pipeline.

Pre-requirements

• AWS CLI and Docker CLI installed and configured
• Permission on AWS to create AWS Elastic Container Registry and secrets on AWS Secrets Manager
• An Docker Account

Walkthrough

Step 1: Create DockerHub credentials

Go to https://app.docker.com/ > Account Settings > Personal Access Tokens > Create access token with Read-only permission.

Ref: https://docs.docker.com/security/for-developers/access-tokens/

Step 2: Create a new secret on AWS Secrets Manager

ECR uses a secret stored in the AWS Secrets Manager to authenticate into the Docker Hub. The secret must use the ecr-pullthroughcache/ prefix, otherwise, ECR will not find it during sync process. To create a new secret, use the following command:

aws secretsmanager create-secret \
    --name ecr-pullthroughcache/<SECRET_NAME> \
    --secret-string '{"username": "<USERNAME>", "accessToken": "<PAT>" }'

Step 3: Configure the cache rule

The cache rule feature allows you to configure an integration with a public repository. In this configuration, we define the public repository upstream and the credential we created in the last step, as well as the ECR repository prefix for any cached image. Using AWS CLI, you can create the ecr cache rule following the example bellow:

aws ecr create-pull-through-cache-rule \
    --ecr-repository-prefix <ECR_REPO_PREFIX> \
    --upstream-registry-url registry-1.docker.io \
    --credential-arn arn:aws:secretsmanager:us-east-1:<AWS_ACCOUNT_ID>:secret:ecr-pullthroughcache/<SECRET_ARN>

To validate if the cache rule is working, run the following command:

aws ecr validate-pull-through-cache-rule \
     --ecr-repository-prefix <ECR_REPO_PREFIX> \
     --region <AWS_REGION>

We expect to see the property isValid: true, as in the following image:

Step 4: Authenticating into ECR and pulling images

At this point, we’ve all set to starting pulling public images using ECR cache repositories. To use it, first step is to log in to the ECR using the following command:

aws ecr get-login-password \
    --region <AWS_REGION> | \
    docker login --username AWS \
    --password-stdin <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com

After logging in successfully, you can perform the docker pull command to download the public image you want to add to cache:

## Use /library/ for Docker Hub Offical images 
docker pull <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/<ECR_REPO_PREFIX>/library/<IMAGE_NAME>:<IMAGE_TAG>

## OR use /<repository_name> for non official images
docker pull <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/<ECR_REPO_PREFIX>/<REPOSITORY_NAME>/<IMAGE_NAME>:<IMAGE_TAG>

Once the pull is completed, you will see a new ECR repository created with the ECR prefix and the image name you pulled:

Full demonstration:

Conclusion

Using Amazon ECR as a cache repository for Docker images can represent a major enhancement in the container management experience, with improvements in performance, security and reliability. Easy configuration at no extra cost (beyond the normal cost of the ECR) makes it an indispensable resource if you’re using public images on a daily basis.