Using Pull-Through Cache Repositories

Find out how pull-through cache repositories retrieve and cache images from an upstream registry.

A pull-through cache repository is a private, read-only repository: clients can pull images from it but cannot push images to it. Container Registry retrieves requested images from the upstream registry configured for the repository and caches them in the region containing the pull-through cache repository.

Supported upstream registries are Container Registry endpoints in a different OCI region within the same OCI realm as the pull-through cache repository.

Clients authenticate to Container Registry and pull images from a pull-through cache repository in the same way as from other private repositories.

To create a pull-through cache repository, follow the procedure in Creating a Repository, select Pull-through cache repository as the repository type, and specify values for Upstream URL, Upstream username, and Upstream secret ID.

Upstream Registry Authentication

Container Registry uses the Upstream username configured for the pull-through cache repository to authenticate to the upstream registry. The corresponding authentication credential is stored in a secret in OCI Vault, identified by Upstream secret ID.

For a Container Registry upstream, this credential is the upstream user’s OCI auth token.

The upstream authentication credential must be Base64-encoded when submitted to OCI Vault. If the PAT has an expiration date, replace it and update the credential stored in OCI Vault before it expires.

Upstream credentials are required even when pulling public images from Container Registry. Anonymous upstream access is not supported.

The upstream user must have permission to pull the requested images. An IAM policy in your tenancy must also allow the Container Registry pull-through resource principal to read the secret:

allow resource ocir ocirpullthrough to read secret-bundles in compartment <secret-compartment-name> where target.secret.name = '<secret-name>'

Replace <secret-compartment-name> with the compartment containing the secret and <secret-name> with the secret's name.

For example:

allow resource ocir ocirpullthrough to read secret-bundles in compartment registry-secrets where target.secret.name = 'upstream-ocir-auth-token'

How Images Are Cached

When a client pulls an image, Container Registry serves the image from the local cache when it is available, subject to the tag-refresh behavior described below. If the image or any required layers are not cached, Container Registry retrieves them from the configured upstream registry, streams them to the client, and caches them locally for subsequent pulls.

Images are cached on demand. Creating a pull-through cache repository does not automatically copy images from the upstream registry.

Cached images are stored in the region containing the pull-through cache repository and are subject to the same storage usage and retention policies as other images in Container Registry.

Tag and Digest Behavior

Pulling by Tag

When you pull an image by tag, Container Registry uses the cached version until a refresh check is due. The default refresh interval is one hour for each tag, measured from its last recorded upstream check.

The first request after that interval triggers a check of the upstream registry. If the tag points to a different image, Container Registry updates the cached tag and retrieves any required images or layers that are not already cached. If the tag has not changed, Container Registry returns the cached version.

Tags are refreshed only when requested. Container Registry does not refresh tags automatically in the background.

Behavior When an Upstream Check Fails

If the upstream registry reports that a cached tag no longer exists, Container Registry can continue returning the cached image. Deleting an image or tag from the upstream registry does not automatically delete it from the pull-through cache repository.

If a refresh fails because of a temporary problem, such as a timeout or an upstream service outage, Container Registry can return the cached image if it is available locally. A later pull can retry the refresh.

When Container Registry needs to contact the upstream registry, invalid upstream credentials, incorrect upstream configuration, or insufficient upstream permissions cause the pull to fail, even if an older version of the image is cached.

Pulling by Digest

When you pull an image by digest, Container Registry serves the cached image without checking the upstream registry for updates. If the image or any required layers are not cached, Container Registry retrieves them from the upstream registry and caches them locally.

Supported Image Manifest Formats

Pull-through cache repositories support Docker Image Manifest V2, Schema 2, Docker manifest lists, OCI image manifests, and OCI image indexes. Docker schema version 1 image manifests are not supported.

Managing a Pull-Through Cache Repository

After you create a pull-through cache repository, you can update the upstream username and upstream secret ID. You cannot change the upstream URL or repository type. For more information, see Editing a Repository.