Registry Mirroring

What Is Registry Mirroring?

Registry mirroring is the practice of copying container images and other artifacts from an upstream registry into a registry you control, so that builds and deployments pull from your copy. Population is deliberate: content is copied on a schedule or at promotion. That distinguishes a mirror from a cache, which fills lazily on demand.

The motivation is control rather than speed. A mirror decides what exists inside the boundary, holds it as long as policy requires, and keeps serving when the upstream is unreachable, rate-limited or has deleted a tag.

That is why regulated and air-gapped estates adopt one: a build that only succeeds when a public registry answers has an external dependency in its critical path.

How Mirroring Differs From Caching and Replication

The three patterns are often conflated, and they fail in different ways.

• Mirroring — an eager copy into a registry you own. You choose what enters it, so its contents are known before anything needs them.
• Pull-through cache — a lazy copy. A pull-through cache fetches on first request and may evict later, so a cold miss still reaches upstream.
• Replication — synchronisation between registries you already control, usually for geography or availability. It moves your copies around rather than severing the upstream dependency.
• Air-gapped transfer — export to an OCI layout, physical transfer, import on the far side. The internal copy becomes the only source of truth.

A cache is an optimisation; a mirror is an inventory. That distinction decides what happens during an upstream outage, and whether you can say what was deployable last quarter.

The Costs and the Failure Modes

Eager population has a price. Copying every tag of a popular repository consumes storage immediately and keeps consuming it. A mirror needs a retention policy, garbage collection and an owner, or it becomes an unbounded archive nobody can reason about.

Content identity is the other concern. An OCI image is referenced by a mutable tag or an immutable content-addressed digest, the sha256 of its manifest. Copying by digest preserves that identity; rebuilding or re-compressing a manifest changes it, and signatures over the original no longer match.

The recurring failure modes are mundane:

• Credentials expire. A sync job fails quietly, and the mirror stops updating while still serving stale content.
• Rate limits bite. Eager copying of many tags amplifies anonymous pull limits, throttling a sync into partial completion.
• Digests drift. Re-tagging or re-pushing through an intermediary changes the digest, breaking digest pinning and signature verification.
• Partial syncs pass silently. Missing attestations or architecture variants surface only when a deployment on another platform fails.

How to Operate a Mirror in Production Environments

A mirror sits in the delivery path and needs the same operational treatment as anything else there.

• Copy by digest, verify by digest. Record the source digest, compare it after the copy, and fail the job when they diverge.
• Mirror what you promote. Sync the references that passed your gates rather than whole repositories, and the storage problem mostly disappears.
• Copy the whole artifact. Signatures, attestations, SBOMs and every architecture variant must travel with the image, or verification breaks inside the boundary.
• Alert on sync age, not sync errors. The dangerous state is a mirror that looks healthy and has not updated in weeks.
• Set retention deliberately. Decide how long each repository is kept and enforce it, so storage stays bounded and audits have an answer.

How Hardened Container Images Simplify a Mirror

A mirror is only as good as what goes into it, and a narrower upstream is easier to run. Fewer images and tags mean less storage, faster syncs and a smaller surface to verify.

It also shifts the maintenance question. When base images are maintained and rebuilt for you, the mirror synchronises a curated set rather than tracking the churn of public repositories. Echo states that its images are mirrored to Azure, Google Cloud, JFrog, Docker, GitHub, Nexus, Harbor and Red Hat Quay (echo.ai/product), which narrows what a team must copy itself.

Echo's guide to migrating from public base images covers how that transition affects internal distribution.

FAQs

What is the difference between a mirror and a pull-through cache?

A mirror is populated deliberately, on a schedule or at promotion, so its contents are known in advance and survive an upstream outage. A cache populates lazily on first request and may evict entries later, which means a cold miss still depends on the upstream registry being reachable at that moment.

Does copying an image to another registry change its digest?

Copying the manifest and layers unchanged preserves the digest, because the digest is the sha256 of the manifest content rather than a property of its location. Rebuilding, re-compressing or rewriting the manifest produces a different digest, which breaks pinned references and invalidates any signature that covered the original. Copy by digest throughout.

Why do air-gapped environments need a mirror rather than a cache?

A cache cannot answer a request it has never seen, so the first pull of anything new fails without network access. A mirror is populated before the boundary closes, which makes its contents deterministic. Inside an isolated environment the internal registry has to be the complete source of truth, not an accelerator.

How much storage does a mirror need?

It depends entirely on scope, and that is the point. Syncing whole repositories grows without limit, while syncing only promoted references stays proportional to what you actually deploy. Set a retention policy per repository, enable garbage collection, and measure growth monthly rather than discovering it during an incident. Scope is the real lever.

What usually breaks in a mirroring setup?

Credentials silently expiring is the most common cause, followed by upstream rate limits truncating a sync. After those come partial copies that omit signatures, attestations or architecture variants. All three present identically: a mirror that appears healthy while serving stale, incomplete or unverifiable content. Alerting on sync age catches them.