> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Pull-through cache

> Cache upstream images in your account while keeping repository access under IAM.

A pull-through cache rule maps an account-owned repository prefix to an upstream
registry. For example, a `hub` prefix with upstream `docker.io` and
upstream prefix `library` lets a client pull `hub/nginx:stable` through
your account's registry URI:

```bash theme={null}
docker pull cr.sa-saopaulo-1.basaltic.cloud/my-account/hub/nginx:1.27
```

The `library` namespace is supplied by the rule, so it is omitted from your
image reference. Use another rule with the appropriate upstream prefix for
images in other Docker Hub namespaces.

Create a rule with `POST /v1/pull-through-cache-rules`. Its required fields are
`prefix` and `upstream_registry`. The response returns `uri_prefix`; append the
remaining image name and tag to that value. Rule prefixes may contain one or two
repository-name components.

## Credentials

For an authenticated upstream, supply both `upstream_username` and
`upstream_secret`. The secret is write-only; reads return `has_credential`, not
the secret. A PATCH preserves omitted fields. To clear stored credentials,
supply empty username and secret values together.

Only supported public upstream destinations are accepted. Upstream availability,
credentials, and rate limits still affect a cache miss. This feature does not
provide access to a private network endpoint.

## Permissions and ownership

Importing on a miss requires `registry:BatchImportUpstreamImage` in addition to
the normal pull actions. A reader without import permission can consume cached
images but cannot cause a new upstream import. Imported content consumes the
account's registry storage and is subject to its quotas and lifecycle rules.

Manage rules by their prefix at `/v1/pull-through-cache-rules/{prefix}`.
Deleting a rule stops future cache imports through it; it does not remove
repositories and images already imported. Review retained images separately.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.