Proxy cache project transitions from global pull-through to project-scoped upstream auth in Harbor

Question

Goal is to understand cache freshness and credential isolation when using the project-scoped proxy cache instead of the legacy per-registry pull-through cache.

The feature binds upstream registry credentials to a dedicated proxy-cache project rather than using global configuration, which changes multi-tenant isolation. Cached manifests and blobs are served from Harbor without contacting upstream unless the entry is evicted or explicitly purged. Garbage collection interacts with proxy-cache artifacts, so storage reclamation is delayed until GC runs. Behavior around upstream token authentication and default cache headers may vary across Harbor 2.x minor releases.

The unresolved decision is whether to accept potentially stale content until manual purge or implement an external eviction policy, and how to measure impact before optimization.

Questions:

What is the documented revalidation behavior for cached manifests in a proxy-cache project?
Does upstream tag deletion affect subsequent pulls from Harbor without manual purge or GC?
How does project-scoped credential isolation interact with upstream token auth compatibility boundaries?

Tasadduq Burney · Answer

Transitioning from global pull-through to project-scoped proxy cache in Harbor significantly alters how the system handles artifact lifecycle and security. This architecture moves logic from global registry settings to per-project isolation

Manifest Revalidation and Freshness
p>In a project-scoped proxy cache, Harbor does not typically revalidate cached manifests against the upstream registry on every pull. Once a manifest and its associated blobs are stored within the proxy-cache project, Harbor serves them locally. The freshness of the content is governed by the presence of the local artifact rather than upstream Cache-Control headers. To retrieve updated content, you must either:

Manually purge the proxy-cache project.
Wait for storage retention policies to evict the entries.

Upstream Tag Deletion Impact
Deleting a tag on the upstream registry does not immediately affect subsequent pulls from the Harbor proxy-cache. Because the cache binds the manifest to the specific project, Harbor will continue to serve the 'deleted' version of the tag as long as the manifest exists in the local storage. Garbage collection (GC) in Harbor will only reclaim these blobs once the manifest itself is removed or purged.

Credential Isolation and Token Auth
Project-scoped isolation ensures that upstream credentials are strictly bound to the dedicated proxy-cache project. This enhances multi-tenant security by preventing one project's proxy from using the authentication context of another. However, this means each proxy-cache project requires its own valid upstream credential configuration. If the upstream registry uses short-lived tokens, Harbor must be able to refresh these within the specific project scope to maintain cache functionality.

Implementation Steps for Transition

Create a new project in Harbor designated to act as the proxy cache.
Configure the upstream registry URL and credentials specifically within that project's settings.
Perform an initial pull to populate the cache.
Monitor storage growth by comparing the size of the proxy-cache project against your legacy global cache metrics.

Note: To provide a specific recommendation on eviction policies, are you using a specific version of Harbor 2.x, and do you have an external orchestration layer capable of triggering purges?

Proxy cache project transitions from global pull-through to project-scoped upstream auth in Harbor

1 answer

Transitioning from global pull-through to project-scoped proxy cache in Harbor significantly alters how the system handles artifact lifecycle and security. This architecture moves logic from global registry settings to per-project isolation

Manifest Revalidation and Freshness

Upstream Tag Deletion Impact

Credential Isolation and Token Auth

Implementation Steps for Transition

Your perspective belongs here.

0 question comments