Pull-Through Cache

The Distr registry can act as a pull-through cache for any OCI-compatible upstream registry. Configure an artifact with an upstream URL and Distr will sync tags from the upstream and serve blobs to your customers on demand, with no direct upstream access required.

This lets you consolidate all image pulls through a single registry endpoint with unified access control, download analytics, and entitlement enforcement, regardless of where the images are originally hosted.

After a sync, Distr stores the tag list and manifest metadata from the upstream. Blob data (layers, image configs) is fetched from the upstream on first pull and cached in the Distr registry. Subsequent pulls are served entirely from Distr. A synced tag counts toward your registry storage only once it has been pulled.

When creating or editing an artifact, set the Upstream URL to the fully qualified image reference of the upstream repository. The URL must point to a specific repository, not the entire registry. Each pull-through artifact maps to exactly one upstream repository. The upstream registry must be reachable at a public address: Distr rejects hosts that resolve to private, loopback, link-local or other special-purpose addresses.

If the upstream requires authentication, select one of the supported auth types. Credentials are validated against the upstream when saved.

Public repositories do not require authentication. Select “No authentication”.

For AWS Elastic Container Registry, select “AWS ECR” and provide an AWS access key ID and secret access key. Distr automatically exchanges these credentials for a short-lived ECR authorization token and refreshes it before it expires.

The IAM identity associated with the credentials must have the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DistrPullThroughCache",
      "Effect": "Allow",
      "Action": [
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:DescribeImages",
        "ecr:GetAuthorizationToken",
        "ecr:DescribeRepositories",
        "ecr:ListImages"
      ],
      "Resource": "*"
    }
  ]
}

Once configured, pull images using the standard Docker CLI (or any OCI client) via the Distr registry URL:

docker pull registry.distr.sh/<slug>/<artifact-name>:<tag>

Replace <slug> with your organization’s registry slug, <artifact-name> with the name you gave the artifact in Distr, and <tag> with the upstream tag you want to pull.

Clients must authenticate with a Personal Access Token the same way they do for any other artifact in the Distr registry.

Distr runs a background sync job to keep the local tag list in sync with the upstream repository. The sync fetches all tags and their manifest metadata, making them available for HEAD requests and entitlement enforcement without requiring an actual pull. On Distr Cloud, the sync runs twice per hour (at :15 and :45). For self-hosted instances, the schedule is controlled by the REGISTRY_UPSTREAM_SYNC_CRON environment variable. See Upstream Tag Synchronization.

You can also trigger a manual sync at any time from the artifact details page or via the API:

curl -X POST https://app.distr.sh/api/v1/artifacts/<artifactId>/sync \
  -H "Authorization: AccessToken <token>"

You can delete a synced tag like any other tag, but the next sync restores it unless it has been removed from the upstream repository. The last tag of a pull-through cache artifact cannot be deleted; delete the artifact instead.

A pull-through cache artifact can use semantic versioning like any other artifact. Since the upstream decides which tags exist, the sync then skips every upstream tag that is not a SemVer version, such as latest, instead of failing. Signature and attestation tags are synced as usual. A manual sync from the artifact details page lists the tags it skipped.

Switching to semantic versioning deletes the tags the artifact already holds that are not SemVer versions, as for any other artifact. The sync does not restore them afterwards.

The artifact details page shows:

• Last synced at: when the most recent sync completed successfully.
• Last sync error: the error message from the most recent failed sync, if any.

If the sync error field is populated, verify that the upstream URL is correct and that the configured credentials have not expired or been revoked.