A pull-through cache is a registry that fetches images from an upstream registry on first request and serves later pulls from its own storage. It gives you a single choke point for policy, scanning and logging, and it keeps builds working during upstream outages. It also becomes something you must patch, authenticate and monitor.
How it works
The open source registry documentation describes the mode this way: the registry responds to normal pull requests but stores all content locally. The first pull comes from the public registry and is saved. Later pulls come from the mirror.
When a tag is requested, the registry checks the remote for the latest version and fetches it if it changed. To manage disk space it periodically removes old content, and a later request for removed content triggers a new fetch. Deletion support must be enabled for that cleanup.
Configuration uses a proxy section with the upstream address, and the Docker daemon is pointed at the mirror through its registry mirrors setting.
What you gain
- One path out. Hosts pull from the cache and need no direct route to public registries. That makes egress rules simpler.
- A place to scan and approve. You can add checks before images reach build agents.
- Availability. Cached images remain pullable if the upstream is slow or down.
- Fewer rate limit problems. Many builds share one upstream pull.
- Logs. You see which images are pulled, by whom and when.
What you take on
You must secure the mirror. The documentation is direct about this. If you give the cache credentials for an upstream account, private resources that account can reach become available through your mirror, so you must secure it with authentication if they should stay private.
Stale or poisoned content. A cache serves what it fetched. If a bad image was pulled once, it can keep being served until it expires or is removed. You need a way to purge by digest.
Tag drift is hidden. Because the cache refreshes tags on its own schedule, two builds hours apart can get different content under one tag. Pin digests so the cache cannot change what you run.
Limits on what it can mirror. The documentation lists constraints: one upstream registry at a time, the mirror URL must be the root of a domain, and the Docker daemon supports only mirrors of Docker Hub. Check whether your tooling and version still match these notes before designing around them. Other runtimes may behave differently.
Another service to patch. The cache holds image data and credentials and sits in the path of every build.
Settings to check
- Require authentication for pulls and keep write access narrow.
- Use TLS between clients and the cache.
- Give upstream credentials only the access needed.
- Set a retention period and confirm deletion works.
- Log pulls and alert on first-seen images.
- Pin images by digest in your deployment files.
- Back up or rebuild plan: know how to recreate the cache.
Is a cache a substitute for scanning?
No. It stores whatever upstream serves. Scan on the way in or before use, and keep an inventory of what was cached. See the registry hardening checklist for the wider controls.
Safeguard's SBOM and dependency scanning can inventory the images you pull, and policies and gates let you set rules before deploy. Start with a free scan.
Quick check
Does a mirror protect me from a malicious upstream image?
Not by itself. It may cache the bad image. You need scanning, digest pinning and a way to purge.
Should the cache be reachable from the internet?
Usually no. Keep it on an internal network and require authentication, since it may expose private upstream content.
Sources
Last reviewed: 19 October 2026.
