Use a pull-through cache

Mirror Docker Hub, GitHub Container Registry and other public registries under a prefix of your registry, so each image is fetched once and served from your registry after that.

Last updated 18 November 2026View as Markdown

A cache rule maps a prefix of your registry to an upstream registry. The first pull of <host>/<prefix>/<name>:<tag> fetches the image from the upstream; later pulls are served from your registry. Replace org-example1234.ecr.example.com with your registry host.

Prerequisites

  • Permission for ecr:CreatePullThroughCacheRule. To open the console page, ecr:DescribePullThroughCacheRules; without it the page shows a refusal.
  • For an upstream login: a secret holding the upstream password or token, granted to the registry consumer (see Secrets). To pick it in the console, also secrets:ListSecrets.
  • The organization is below its pull-through cache rule quota (see Quotas).

Add a rule

  1. Open Container registry, then choose Pull-through cache.
  2. Under Add a rule, for Upstream, choose the registry, such as Docker Hub. The prefix is filled in for it (dockerhub).
  3. (Optional) For Prefix in your registry, enter another prefix.
  4. (Optional) For Upstream user, enter the login name, and for Password or token, from Secrets, choose the secret. Only secrets granted to the registry consumer are listed; a user without a secret, or a secret without a user, is ignored.
  5. Choose Add rule.

Upstreams: docker.io, ghcr.io, quay.io, registry.k8s.io, public.ecr.aws, mcr.microsoft.com.

Pull through it

docker pull org-example1234.ecr.example.com/dockerhub/node:22
docker pull org-example1234.ecr.example.com/dockerhub/bitnami/redis:7.4
docker pull org-example1234.ecr.example.com/ghcr/stefanprodan/podinfo:6.7.1

On Docker Hub, a name without an owner is an official image: dockerhub/node is library/node.

Bringing an image in needs ecr:BatchImportUpstreamImage (not in the read-only policies); a principal with only ecr:PullImage gets what is already cached.

How the cache behaves

  • A cached image lives in an ordinary repository, here dockerhub/node. It is scanned, lifecycle rules and storage charges apply, and you can pull it by digest. Pushing into it is refused.
  • A tag is checked against the upstream again after 6 hours, with a HEAD request, when a principal who may import pulls it. When the upstream fails, the cached copy is served.
  • Every manifest and layer is checked against its digest before it is stored.
  • The image's cosign signatures come along, so Only deploy signed images can check them.
  • Each image brought in emits ECR Pull Through Cache Action on your event bus.
  • Docker Hub limits anonymous pulls per IP address, and your registry shares one. A login on the rule raises that limit and reaches private upstream images.

Change or remove a rule

Set or clear a rule's login with dcloud ecr pull-through-cache update (username and passwordSecretId together, or both null); the console has no edit. In the console, the rule's delete icon removes it. Deleting a rule keeps what was cached; nothing new comes in.

If it is refused

  • 409 Prefix "dockerhub" is taken.
  • 409 with code QuotaExceeded at the rule quota.
  • 400 passwordSecretId: no such secret.
  • 400 username and passwordSecretId go together when only one of them is sent.
  • A push into a cache repository: DENIED dockerhub/node is a pull-through cache of library/node; push to another repository.
  • A pull of something not cached, by a principal without ecr:BatchImportUpstreamImage: when nothing under that name is cached yet, DENIED dockerhub/node is not cached yet, and this credential may not bring it in from docker.io (ecr:BatchImportUpstreamImage); when the repository exists but the tag is not cached, MANIFEST_UNKNOWN 22 is not cached yet, and bringing it in from docker.io needs ecr:BatchImportUpstreamImage.
Did this page help you?