Registries & Distribution

Already exists means that layer, identified by its sha256 digest, is already in the host's local image store, so nothing is transferred. Downloading is the compressed layer blob arriving from the registry. Extracting is that blob being decompressed and unpacked onto disk.

Docker Hub counts image manifest requests, not layers or bytes. Anonymous pulls are counted per source IP address and get the smallest quota; authenticated pulls count against your Docker account and get more; paid plans get more still. First fix: docker login on the machine that pulls.

The git-SHA tag is a permanent name for one exact build, so it can be redeployed later and traced back to a commit. The stable tag only points at whichever build is current, so it answers what is live now, not what shipped when.

:latest is an ordinary mutable tag with no special meaning — it is not "the newest image". Different hosts can run different content under the same name, rollback has nothing to roll back to, and caching makes it unpredictable. Deploy explicit version tags resolved to digests.

A tag is a mutable, human-friendly label the registry can repoint to different content at any time. A sha256 digest is the hash of the image manifest, so it is immutable and content-addressed: the same digest always resolves to exactly the same bytes.

Pass --sbom=true and --provenance=mode=max to docker buildx build. BuildKit writes each attestation as its own manifest inside the image's OCI index, next to the platform manifests — not as an extra image layer, so layers and config are untouched.

For each layer and the config blob, the client HEADs the blob digest; if absent it opens an upload session, sends the bytes, and completes with the digest. Only after every referenced blob exists does it PUT the manifest under the tag — so a tag never resolves to missing content.

A digest guarantees integrity: you got exactly those bytes, unchanged. It says nothing about who produced them or whether they were approved. A signature adds authenticated provenance: identity X asserts this digest is good. You need both — verify the signature, then deploy by digest.

Push and pull transfer an image to and from a registry over HTTP, uploading only layers the registry lacks. Save writes the whole image — layers, config, tags — into a tar file that load reads back. Use save/load for air-gapped transfer or when no registry is available.

A credential helper is an external binary the Docker CLI calls to get credentials for a registry instead of reading them from its config file. Cloud registries issue short-lived tokens — ECR's lasts 12 hours — so a helper that mints a fresh one per call avoids expiry and stores no secret on disk.

The client requests a resource, gets 401 with WWW-Authenticate: Bearer realm=..., service=..., scope=.... It calls that realm (the token service) with its credentials and the requested scope, receives a short-lived signed token listing allowed actions, then retries the original request with Authorization: Bearer <token>.

It caps how many layer blobs the Docker daemon downloads in parallel for a pull, defaulting to 3 and set in daemon.json. Raising it adds streams, not bandwidth, and does nothing for extraction, which decompresses layers one at a time in order.

By default it writes an entry to ~/.docker/config.json under auths, keyed by registry host, holding base64(username:password). That is encoding, not encryption, so anyone who reads the file has the credential. docker logout <host> removes the entry.

Layers are content-addressed by SHA-256 digest, so before uploading the client asks the registry whether each digest already exists and skips those it has. Within one registry, a cross-repository blob mount links an existing blob into another repository, transferring zero bytes.

A pull-through cache is a registry running in proxy mode: on a miss it fetches from upstream, stores the layers, and serves later requests locally. The daemon's registry-mirrors list only redirects Docker Hub (docker.io) pulls; other registries are unaffected and need per-registry configuration.

A digest pin makes builds reproducible and stops silent base-image changes, but it also freezes security patches and hides which version you are on. Write both — FROM img:3.12.4-slim@sha256:… — and let an automated dependency bot raise digest bumps as reviewable pull requests.

Copy or re-tag the existing manifest instead of rebuilding: docker buildx imagetools create -t prod-repo:1.4.2 staging-repo@sha256:…, or crane/skopeo copy. Prove sameness by comparing the sha256 manifest digest before and after — an identical digest means identical bytes.

mode=min keeps the skeleton: builder identity, timestamps, source reference and output digest. mode=max adds the full build definition — Dockerfile, per-step metadata, resolved inputs, and every --build-arg value, which is how secrets leak.

It tells the daemon to accept plain HTTP or an untrusted TLS certificate for that host, disabling verification. Credentials and images then travel unauthenticated and tamperable. In production, run the registry with real TLS and install your internal CA certificate on every node instead.

Split the pull into transfer and extraction and measure each: whether seconds pile up under Downloading or Extracting, whether one layer dominates the manifest, the real throughput to the registry, and CPU and disk during unpacking. The warm host only reuses layers it already holds.

Confirm it is registry throttling, not the network: check the 429 and remaining-quota headers, and whether pulls are anonymous. Then authenticate CI with a machine account, put a pull-through cache in front of the fleet, pin and pre-bake hot base images, and alert on 429 rate and cache hit ratio.

CI presents its OIDC identity token; Fulcio returns a short-lived certificate binding that identity to an ephemeral key; cosign signs the image digest, logs the signature in the Rekor transparency log, and discards the private key. Verifiers check the certificate chain, the logged inclusion time, and the expected signer identity and issuer.

Because the release already re-pointed that alias at the broken build, so redeploying it fetches the same manifest. A rollback has to name a tag nobody moved — the previous build's own immutable tag — not the alias the release just updated.

Change the shared build path, not each pipeline: move builds onto an index-capable builder, default to minimal provenance everywhere and SBOM on published images, and keep mode=max for repositories whose build args you have audited.

Namespace repositories per team, grant humans read-only plus break-glass, and give push rights only to machine identities scoped to their own namespace. Production pulls read-only, ideally via workload identity rather than stored secrets. Separate promotion namespaces, make release tags immutable, and set credential expiry and audit.

Measure pull time as a first-class signal, then pick among four levers: move fewer bytes, move them a shorter distance, move them before they are needed, or start before they all arrive. Each trades a different cost — staleness, a dependency, coupling, or money.

Enforce at admission, not in CI: a policy engine verifies signatures over digests against expected signer identities and rewrites tags to verified digests. Roll out in audit mode first, sign your own builds, mirror and re-sign third-party images internally, then fail closed per namespace with a documented break-glass path.

A single mutable pointer with no history is a release control plane with no audit trail and no rollback target. Keep the alias for humans, restrict who may push it, record every move externally, and move deployments onto immutable build tags.

Split tags into immutable and rolling. Immutable: one per build, carrying the commit SHA and a semver release tag, never repushed. Rolling: 1, 1.4, stable, latest — convenience pointers only. Deployments reference digests; environments are recorded in a config repo, not encoded in image tags.