Proxy Cache Projects

Important Prerequisites

Project admins cannot create proxy projects. You have to be a system admin. Apart from this, you will need to create an endpoint as explained here before. For which third-party registries can be proxied, see Supported Non-Harbor Registries.

Create a New Proxy Cache Project

  • In the navigation, click on Projects and then on + New Project. Create new project
  • In the open dialogue window, use the Proxy Cache slider to make this project a proxy cache.
  • Select the endpoint from the dropdown. New proxy cache project

To Make Your Proxy Cache Project Work

You are just one more step away from using your new proxy cache.

Edit your docker pull commands: replace canonical registry and project with the proxy project.

Optionally, re-configure your pod manifests in a similar manner.

The last two actions are necessary to pull images from the proxy and not directly from the canonical registry.

  1. Remember that proxy cache projects are only for pulling images.
  2. By granting users access to a proxy cache project, you automatically grant them access to the canonical registry, and they can pull any images from there.

Serve Cached Images When the Upstream Is Unavailable

By default, if the upstream registry is unreachable when a pull request arrives, the proxy cache returns an error. You can change this behavior by enabling the local-on-not-found option, which instructs the proxy to serve a locally cached copy of the image instead of failing.

This is particularly useful in air-gapped environments or during upstream outages — any image that was previously pulled through the proxy remains available to your users even when the canonical registry cannot be reached.

Enable Local-on-Not-Found

  • Open the proxy cache project and go to its Configuration tab.
  • In the Proxy Cache settings section, enable the Serve local cache when upstream is not found option.
  • Save the configuration.

Once enabled, pull requests for images that exist in the local cache will succeed even if the upstream registry is offline or unreachable. Pull requests for images that have never been cached will still fail.

This feature can also be enabled upon creating a new project.

Enable Proxy for OCI 1.1 Referrer API

OCI 1.1 registries support a Referrers API that allows clients to discover artifacts (such as signatures, SBOMs, or attestations) that reference a specific image or artifact. By default, Harbor does not proxy these referrer API requests to the upstream registry.

If your workflows depend on referrer discovery — for example, when using Cosign for signature verification or supply-chain tooling that queries referrers — you can enable this option to have the proxy cache forward referrer API requests to the upstream registry.

Enable Referrer API Proxying

  • Open the proxy cache project and go to its Configuration tab.
  • In the Proxy Cache settings section, enable the Enable proxy for referrer API option.
  • Save the configuration.

Once enabled, Harbor forwards OCI Referrers API requests to the upstream registry. If the upstream registry supports the API, clients receive its referrer results, allowing signature verification and other referrer-dependent workflows to function when pulling images through the proxy cache.

This option can also be enabled when creating a new proxy cache project.

Retention Rules for Proxy-Cached Images

Contrary to other solutions, Container Registry won’t create any retention rules for your proxy cache projects automatically. It means that not only the latest but all images will be kept.
If you want unused images to be deleted from time to time, you can create retention rules as described here.