Pull-through cache

Early access. Registry is rolling out behind an organization flag.

Every registry has a reserved cache/ namespace that mirrors a curated catalog of public upstreams. Pulling through it keeps images close to your clusters and insulates your builds from a rate limit or an outage upstream.

Pulling through the cache

Prefix the upstream host and repository with <registry>/cache/:

docker pull registry.lngbrdg.com/acme-prod/cache/docker.io/library/redis:7
docker pull registry.lngbrdg.com/acme-prod/cache/ghcr.io/acme/tool:v2

The first pull fetches from the upstream and caches every layer; later pulls serve from the EU. A thundering herd on a fresh tag collapses into a single upstream fetch.

List the catalog you can mirror:

lbr registry upstream list

Bring your own upstream credentials

To mirror an upstream’s private images — or to pull under your own account’s rate limits rather than the platform’s — attach a credential for that upstream:

lbr registry upstream credential set docker.io \
  --username acme --password "$DOCKERHUB_TOKEN" -r acme-prod

Credentials are per-registry and per-upstream, stored encrypted, and never read back. Content fetched under your credential is visible only to your organization; publicly-fetched content is shared.

lbr registry upstream credential list -r acme-prod
lbr registry upstream credential delete docker.io -r acme-prod

Freshness and retention

By-digest pulls are immutable and cached indefinitely. By-tag pulls are checked against the upstream after a short freshness window and served stale if the upstream is briefly unavailable — trouble upstream degrades freshness, never availability. Cold cached content ages out on a retention sweep.

Note: cache egress counts toward your registry egress, shown separately from your own images in the Console usage view. Pulling your own private images is never rate-limited; the cache has staff-tunable guardrails only as an abuse backstop.

Where to next

• Pricing — how cache egress is measured.
• Registry with Terraform — declare upstream credentials as code.