Optimizing Image Management Efficiency Using AWS ECR Pull-Through Cache

This time, we will take a look at AWS Elastic Container Registry (ECR), an essential service when building container execution environments on AWS. We will introduce the pull-through cache feature of ECR by covering its recent updates—such as support for private ECR repositories—enterprise use cases, and insights gained during our testing process.

What is ECR’s Pull-Through Cache Feature?

ECR’s pull-through cache is a feature that dynamically retrieves external container images on-demand and caches them within your private ECR. By creating a “pull-through cache rule” in your account’s private ECR and associating an upstream registry with a namespace (a prefix applied to the repository name in your ECR), developers and deployment environments can pull external images via the ECR repository URI, while ECR automatically fetches the image from the upstream registry in the background.

At the time of the first pull, a repository is automatically created in your private ECR using the specified prefix combined with the original image name, and the image layers are cached. During this initial retrieval, AWS uses an IP address from its managed infrastructure to fetch the image via the pull-through cache feature. For subsequent pulls, the image is served directly from the cached copy in ECR, so there is no further access to the external registry. In addition, ECR checks at least once every 24 hours whether the image on the upstream side with the same tag has been updated, and if an update is detected, the cached copy in your private ECR is refreshed. This means that even for tags that are frequently updated, such as latest, the ECR cache will follow the latest image at least once every 24 hours (as of the time of writing, the image update interval cannot be modified).

Through this mechanism, you can use ECR like a proxy cache to access external container images via your internal repository.

Main Benefits of the Pull-Through Cache

The most obvious benefit of caching is improved performance. Since the required container images are cached in ECR, retrieving the same external image for the second time and beyond is significantly faster, reducing your application’s startup time. Of course, this is not the only advantage; ECR’s pull-through cache offers several additional benefits in terms of security and other aspects:

Reduced External Dependency and Improved Availability

Even if an external container registry is down during deployment, having a cached copy in ECR can help avoid or mitigate service impact. Moreover, since the image is obtained from within ECR, you can also expect lower network latency and faster performance due to intra-region replication.

Avoidance of External Registry Rate Limits

For example, Docker Hub imposes rate limits on the number of pulls an anonymous user can perform within a given time period. However, if you retrieve images from Docker Hub via ECR’s pull-through cache, you can use them without worrying about these limits. As explained earlier, since ECR fetches images from Docker Hub on your behalf using AWS infrastructure, your environment does not need to directly access Docker Hub.

Centralized Security Controls

By consolidating the origin of your container images to ECR, you can centrally manage access controls and vulnerability scans. ECR integrates with IAM for authentication and offers security features such as KMS encryption at rest and image scanning integrated with Amazon Inspector. This means that even images imported from external sources can benefit from consistent security measures. For instance, images retrieved through the pull-through cache can be automatically scanned for vulnerabilities, and lifecycle policies can be used to periodically remove older tags. Additionally, you can enforce policies that only grant production clusters access to ECR while blocking direct access to external registries.

Cost Optimization

The pull-through cache only caches images that are actually pulled, so there is no need to pre-replicate all potentially used images, which helps reduce storage costs. Moreover, using cached images within the same region minimizes cross-region data transfers, lowering the cost associated with inter-region image transfers.

Supported Upstream Sources

Currently, ECR’s pull-through cache supports specifying several major public registries as well as some private registries as upstream sources.

https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html

At the initial release in 2021, only Quay.io and Amazon ECR Public were supported, but support has since expanded to include registries that require authentication, such as Docker Hub and GitHub Container Registry. Additionally, with the update released this month (March 2025), even private Amazon ECR repositories can now act as upstream sources—regardless of cross-region or cross-account boundaries.

You can find the release notes here:

https://aws.amazon.com/jp/about-aws/whats-new/2025/03/amazon-ecr-pull-through-cache/

Setup

You can create pull-through cache rules using the AWS CLI with the aws ecr create-pull-through-cache-rule command. The main options include:

• --ecr-repository-prefix: The prefix for the repository to be created in your private ECR (e.g., docker-hub or quay).
• --upstream-registry-url: The endpoint URL of the external upstream registry (e.g., for Docker Hub, registry-1.docker.io; for ECR Public, public.ecr.aws).
• --credential-arn: (For upstream sources that require authentication) The ARN of the secret stored in Secrets Manager containing your credentials.
• --registry-id: (Optional) The AWS account ID of the private registry in which to create the rule (if not specified, the default registry is used).
• --custom-role-arn: (For the case where the upstream is another AWS account’s ECR) The ARN of the IAM role used for cross-account access.

Below is an example of setting Docker Hub as the upstream source. Since authentication is required for retrieving images from Docker Hub, a Secrets Manager secret ARN is specified. The secret name in Secrets Manager must begin with the prefix ecr-pullthroughcache/ (Creating a pull through cache rule in Amazon ECR – Amazon ECR).

# Set Docker Hub as the upstream (authentication required)
aws ecr create-pull-through-cache-rule \
    --ecr-repository-prefix "docker-hub" \
    --upstream-registry-url "registry-1.docker.io" \
    --credential-arn "arn:aws:secretsmanager:::secret:ecr-pullthroughcache/"

For using ECR Public as the source (which does not require authentication), the command would look like:

# Set ECR Public as the upstream (no credentials required)
aws ecr create-pull-through-cache-rule \
    --ecr-repository-prefix "ecr-public" \
    --upstream-registry-url "public.ecr.aws"

Considerations When Using the Pull-Through Cache

Beyond general considerations such as supported regions and quotas, here are some points to note:

Using Secrets Manager

For registries like Docker Hub and GitHub that require authentication, the secret name in Secrets Manager must begin with the prefix ecr-pullthroughcache/.

For example, in the case of Docker Hub, including the keys username and accessToken in the secret allows ECR to perform upstream authentication using those credentials.

When setting up via the console, only secrets with this prefix will be displayed as options, so if your secret is not shown, verify that the prefix is correctly applied.

This prefix must also be used when provisioning secrets through CloudFormation or Terraform.

Tag Updates and Immutability

As mentioned earlier, pull-through cache checks for updates on the upstream side on a tag-by-tag basis every 24 hours. If you have enabled immutability for image tags in your ECR repository, which prevents overwriting images with the same tag, there is a concern that the cache might not update. However, there have been issues reported (see pull through cache rule related cache repository’s immutability not …) where image replacement still occurs even when immutability is enabled. This is something to be aware of when using the feature.

Applying the Concept to Enterprise Environment Segregation

Let’s explore some potential use cases that might arise in an enterprise setting where separation between development and production environments is a key requirement. Often, due to the security and reliability demands of a production environment, a policy may be adopted where “external images can be used flexibly in the development environment, while only trusted internal images are allowed in production.” The pull-through cache feature can be very useful in implementing such segregation.

Controlling the Image Flow in Development Environments

When developers test new middleware or OSS images, they typically pull various images from Docker Hub or GitHub Container Registry. By setting up pull-through cache rules in the ECR of the development AWS account and retrieving external images via ECR, you can centralize the image flow and maintain visibility into which images have been used. For example, since images cached in the development ECR can be scanned for vulnerabilities using ECR’s scanning feature, potential vulnerabilities in images being used during development can be identified early. In organizations with a dedicated platform or infrastructure operations team, this centralized caching can also aid in monitoring the usage of external images by application teams.

Commonizing Sources Across Multiple Environments

If you are managing multiple AWS accounts or regions for development, staging, and regression testing, you can create a central repository and use pull-through cache rules to ensure that all environments retrieve images from a common source. For instance, only images that pass tests in the development environment could be exported to the central repository, and each environment could then create its own pull-through cache rule pointing to this common upstream repository. While push-based image distribution (e.g., using replication) is also an option, pull-based caching via the pull-through cache can simplify management as each environment’s ECR automatically caches from the central repository without requiring additional distribution mechanisms.

Moving Images from a Development Repository to a Production Repository

In enterprise environments, it is common to have separate repositories for development and production to meet different isolation requirements. In such cases, when exporting images from a central development repository to a production repository, a design that uses replication or individual image export/import might be more secure than using on-demand retrieval via pull-through cache. This is because on-demand retrieval from the development repository could inadvertently cache images in the production repository that are not authorized for production deployment.

Conclusion

In this post, we have introduced the pull-through cache feature of ECR along with its latest updates and potential enterprise use cases. Although caching is often associated with improved performance, as highlighted here, the feature also offers significant benefits in terms of availability and security. As discussed, pull-through cache can play a key role in managing image distribution channels and vulnerability scanning scopes in production environments.