Harbor Proxy Cache vs Replication: How to Choose for Upstream Images

The decision: pull-through or pre-copy?

If your Kubernetes cluster cannot reach Docker Hub, Quay, or an internal upstream registry directly, Harbor offers two supported ways to make those images available: a proxy-cache project that fetches on demand, or a replication rule that copies artifacts into a normal project. The choice is not about which is newer. It is about whether a pull must succeed when the upstream is unreachable, how much storage you can reserve, and whether artifacts need local scanning, signing, or retention.

The useful takeaway: choose proxy cache when you want minimal setup and storage grows with actual use, and you can tolerate first-time pulls failing during an upstream outage. Choose replication when offline availability, predictable storage, or local policy enforcement matters more than duplicated bytes.

Constraints that usually decide it

• Upstream outage tolerance. Proxy cache is a cache, not a mirror. A cached tag may still be served, but a tag that has never been pulled, or one evicted by cache cleanup, will fail while the upstream is down. Replication copies artifacts ahead of time, so the local project can serve them without upstream access.
• Credentials and rate limits. Both options can hold upstream credentials in Harbor. Proxy cache avoids a copy job and spreads requests over time as clients pull. Replication can be scheduled to run within rate limits, but a large first sync may hit them.
• Storage budget. Proxy cache grows with what clients actually pull and is subject to project quota. Replication grows with what the rule copies, which can be more predictable but also larger if the rule is broad.
• Local policy. If images must be scanned, signed, or retained under a policy before use, a normal project populated by replication is easier to reason about. Cached artifacts are still stored locally, but their lifecycle is tied to cache behavior.

Compact comparison

Attribute	Proxy-cache project	Replication rule to a normal project
Fetch model	On demand when a client pulls	Scheduled or event-driven copy
Upstream reachable at pull time	Required for uncached tags; cached tags may be served	Not required after copy completes
Storage growth	Follows actual client usage; subject to quota	Follows rule scope; can be predicted but may duplicate bytes
Setup	Register endpoint, create project flagged as proxy cache	Register endpoint, create rule, choose target project
Retention and quota	Applies to cached artifacts; verify counting in your version	Applies to replicated artifacts; pair with retention rules
Best fit	Many upstream images, low setup, tolerant of upstream outages	Offline availability, policy enforcement, predictable local inventory

Trade-offs in practice

Proxy cache minimizes configuration and avoids copying images nobody uses. The cost is coupling: pull success depends on upstream availability for uncached tags, and on Harbor's cache eviction behavior for previously pulled tags. If your upstream has an outage, you cannot assume every image remains pullable. Also, cached content counts against the project quota, so a busy proxy project can fill its quota and start rejecting pulls even though the upstream is healthy.

Replication decouples you from the upstream at pull time. The cost is duplicated storage and more moving parts: an endpoint, a rule, a target project, and retention to avoid unbounded growth. Replication rules can be scheduled, so a large upstream can be synced gradually. But if the rule is too broad, you may copy images you never use. If it is too narrow, you may miss a tag that a deployment needs.

Both options should be paired with a retention policy sized to the storage budget. Retention and quota operate on locally stored artifacts; the research brief cautions that cached and replicated artifacts may not have identical semantics in every version, so verify counting in your instance rather than assuming.

Implementation sketch

These steps are conceptual because UI labels and API fields change across Harbor releases. In the Harbor 2.x line, proxy-cache projects and replication rules are both available; confirm the exact wording in your deployed minor version before writing runbooks. You need Harbor system administrator or project administrator rights, depending on whether you are creating endpoints and projects or only rules.

1. Register the upstream as a registry endpoint. In Harbor, add an endpoint that holds the upstream URL and credentials. Prefer a scoped robot account or a dedicated credential over embedding long-lived credentials in rules. The endpoint is reused by either option.
2. For proxy cache: create a project and mark it as a proxy cache that references that endpoint. Clients then pull through a path that includes the proxy project and the upstream registry host, for example:

   docker pull harbor.example.com/proxy-dockerhub/docker.io/library/nginx:1.27

   The exact path format depends on your Harbor version and how the endpoint is named. The first pull fetches from upstream and stores the artifact; later pulls may be served from cache.
3. For replication: create a replication rule that uses the endpoint as the source and an ordinary project as the destination. Choose manual, scheduled, or event-driven trigger as your version supports. After the rule runs, clients pull from the destination project path, for example:

   docker pull harbor.example.com/mirror/library/nginx:1.27

   The repository path depends on the rule's filters and destination namespace.

Do not assume the two paths are interchangeable. A proxy-cache project is not a normal project, and a replication destination is not a cache.

Validation path

Validate the behavior you actually depend on, not just that a pull works once.

• Proxy cache: pull a tag through the proxy project while the upstream is reachable. Then make the upstream unreachable — for example, by blocking egress from Harbor to the upstream or by using a controlled upstream you can stop — and retry the same tag. A cached tag may still pull; a different, uncached tag should fail. This confirms the cache boundary rather than assuming it is a mirror.
• Replication: run the rule and inspect its job history in Harbor. Confirm the artifact appears in the destination project's artifact list. Then make the upstream unreachable and pull from the destination project to confirm offline availability.
• Quota and retention: record project quota usage before and after pulls or replication jobs. Apply a retention rule and confirm which artifacts are removed. Verify whether cached and replicated artifacts are counted the same way in your version.

If the result differs from your expectation, check the Harbor version, the endpoint configuration, and the project type before changing the rule. Option names and API fields are not stable across major releases.

Limitations and when to revisit

Proxy cache does not guarantee pullability during an upstream outage. Replication does not eliminate the need for retention and quota discipline. Supported replication adapters and upstream registry types differ by version, so verify your specific upstream is covered. If your upstream is rate-limited, neither option removes the limit; replication may simply move the requests into a scheduled window.

A practical check before committing: list the images your cluster actually pulls, estimate their size, and compare that with your storage budget. If the list is small and stable, replication gives predictable offline availability. If the list is large and mostly cold, proxy cache avoids copying bytes you never use — provided you can accept upstream dependency for uncached tags.

If you need to reverse the choice, deleting a replication rule stops future copies but does not remove already replicated artifacts. Deleting a proxy-cache project removes its cached artifacts. Confirm retention implications before deleting either.