Skip to content

Docker / OCI

Entrepot implements the OCI Distribution Spec (v2) with Docker token authentication. Because Docker clients address registries at the host root, the first path segment is the Entrepot repository and the rest is the image name:

docker pull entrepot.example.com/docker-hub/library/alpine:3.20
└────── host ──────┘ └─ repo ─┘ └─── image ──┘
Kind Behaviour
hosted docker push target. Chunked and monolithic uploads, cross-repository blob mounts, multi-platform manifest lists and OCI image indexes. Tags can move by default.
proxy A pull-through cache of one registry: Docker Hub, ghcr.io, quay.io, registry.gitlab.com, public.ecr.aws, … Content is verified against its digest before caching. Tags are revalidated with cheap HEAD requests, which don’t count as Docker Hub pulls.
group Tries members in order — e.g. your hosted images first, then the Docker Hub proxy.
Terminal window
api -X POST $E/api/v1/repositories -d '{"name":"docker-hub","format":"docker","kind":"proxy","blobStore":"s3","proxy":{"remoteUrl":"https://registry-1.docker.io"}}'
api -X POST $E/api/v1/repositories -d '{"name":"ghcr","format":"docker","kind":"proxy","blobStore":"s3","proxy":{"remoteUrl":"https://ghcr.io"}}'
api -X POST $E/api/v1/repositories -d '{"name":"docker-internal","format":"docker","kind":"hosted","blobStore":"s3"}'
api -X POST $E/api/v1/repositories -d '{"name":"docker","format":"docker","kind":"group","blobStore":"s3","group":{"members":["docker-internal","docker-hub"]}}'

proxy.remoteUrl must be the registry root (https://ghcr.io), without a path. docker.io, index.docker.io and hub.docker.com are all mapped to https://registry-1.docker.io.

Large registries are a good fit for an S3 blob store with redirectDownloads, so layers are served straight from S3.

Terminal window
echo "$ENTREPOT_TOKEN" | docker login entrepot.example.com -u token --password-stdin
# pull through the Docker Hub proxy (library/ is implied for official images)
docker pull entrepot.example.com/docker-hub/library/alpine:3.20
docker pull entrepot.example.com/docker-hub/alpine:3.20
# push to the hosted repository
docker tag my-app:1.0 entrepot.example.com/docker-internal/team/my-app:1.0
docker push entrepot.example.com/docker-internal/team/my-app:1.0

Any username works; the password is the token. Anonymous pulls from repositories with anonymousRead: true need no login.

To make a cluster pull Docker Hub images through Entrepot without changing image references, configure a registry mirror in /etc/containerd/certs.d/docker.io/hosts.toml:

/etc/containerd/certs.d/docker.io/hosts.toml
server = "https://registry-1.docker.io"
[host."https://entrepot.example.com/v2/docker-hub"]
capabilities = ["pull", "resolve"]
override_path = true

override_path is needed because the repository name is part of the path. containerd falls back to server if Entrepot is unreachable. Make sure config_path = "/etc/containerd/certs.d" is set in containerd’s CRI registry configuration.

/etc/containers/registries.conf.d/entrepot.conf
[[registry]]
prefix = "docker.io"
location = "docker.io"
[[registry.mirror]]
location = "entrepot.example.com/docker-hub"

For private repositories, create a pull secret with a read-only service-account token:

Terminal window
kubectl create secret docker-registry entrepot \
--docker-server=entrepot.example.com \
--docker-username=token \
--docker-password="$ENTREPOT_TOKEN"
build-image:
image: docker:27
services: [docker:27-dind]
id_tokens:
ENTREPOT_ID_TOKEN:
aud: https://entrepot.example.com
script:
- echo "$ENTREPOT_ID_TOKEN" | docker login entrepot.example.com -u gitlab-ci --password-stdin
- docker build -t entrepot.example.com/docker-internal/$CI_PROJECT_NAME:$CI_COMMIT_SHORT_SHA .
- docker push entrepot.example.com/docker-internal/$CI_PROJECT_NAME:$CI_COMMIT_SHORT_SHA
  • Hosted Docker repositories allow moving tags by default. Set "hosted": {"allowRedeploy": false} for immutable tags.
  • DELETE /v2/<repo>/<image>/manifests/<digest> deletes a manifest and its tags; deleting by tag removes just the tag.
  • A cleanup policy with untaggedOlderThanDays removes untagged manifests and the layer links no remaining manifest references. Freed blobs are garbage-collected afterwards.
  • http: server gave HTTP response to HTTPS client — for a plain-HTTP test setup, add the host to Docker’s insecure-registries.
  • unauthorized: authentication required — docker login first, or enable anonymousRead on the repository.
  • denied/403 on a tag pull — the image may be quarantined. Tag and digest manifests are blocked in quarantine mode; layers never are.
  • toomanyrequests — Docker Hub’s limit on the proxy’s upstream account; configure proxy.username/password.
  • Pushes fail behind an ingress — layer uploads need a large body size and long timeouts. The Helm chart sets the nginx annotations (proxy-body-size: "0", proxy-request-buffering: "off", 900s timeouts); see Kubernetes.
  • Pulled the wrong image name — remember the first path segment is the Entrepot repository: entrepot.example.com/<repo>/<image>.