# 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.

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](/docs/secrets/guide/what-is)). To pick it in the console, also
  `secrets:ListSecrets`.
- The organization is below its pull-through cache rule quota (see [Quotas](quotas.md)).

## Add a rule

**Console**
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**.

**CLI**
```sh
dcloud ecr pull-through-cache create --prefix dockerhub --upstream-registry docker.io
```

**API**
```http
POST /ecr/api/pull-through-cache-rules
{ "prefix": "dockerhub", "upstreamRegistry": "docker.io" }
```

**Terraform**
```hcl
resource "dcloud_ecr_pull_through_cache_rule" "dockerhub" {
  prefix            = "dockerhub"
  upstream_registry = "docker.io"
}
```

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

## Pull through it

```sh
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](only-deploy-signed-images.md) 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`.

## Related

- [Pull an image](pull-an-image.md)
- `ecr.pull-through-cache.create` · `dcloud ecr pull-through-cache create` ·
  `dcloud_ecr_pull_through_cache_rule`
