Skip to content
Velloreth
Technology 5 min read

Container Registries: Images, Tags and Digests

A registry stores and distributes container images. Learn the tag, the digest, the layers, and the practices that keep a supply chain safe.

By

What a registry does

A registry stores and distributes container images.

build  ->  push  ->  registry  ->  pull  ->  deploy

The common registries:

RegistryNotes
Docker Hubthe default, with a rate limit on the free tier
GitHub Container Registrytied to a repository and its permissions
Amazon ECRprivate, integrated with IAM
Google Artifact Registryprivate, integrated with GCP
A self-hosted registryfull control, more maintenance

A registry is the distribution layer between a build and a deploy.

Tags and digests

A tag is a human-readable label.

docker build -t registry.example.com/app:1.2.3 .
docker push registry.example.com/app:1.2.3

A tag is mutable. latest is moved by every push, and any tag can be re-pushed.

A digest is a hash of the image content.

registry.example.com/app@sha256:8f3a...

A digest is immutable. It always identifies the same image.

The rule: use a tag for convenience and a digest for production.

# Kubernetes: pin the digest
image: registry.example.com/app@sha256:8f3a...

Why: a deploy that pulls latest can get a different image than the one that was tested, and a rollback that pulls latest gets the same new image.

The tag strategy

TagUse
latestlocal development only
1.2.3a release
1.2a moving minor
mainthe latest build of a branch
<commit-sha>the exact build, and the best default
@sha256:...the exact image, immutable

The commit SHA is the best tag for a deploy, because it identifies the source and it is unique.

A tag that is both a version and a moving pointer is a source of confusion. 1.2 moves; 1.2.3 does not.

Layers

An image is a set of layers, one per Dockerfile instruction that changes the filesystem.

FROM node:20-alpine     <- a layer
COPY package.json .     <- a layer
RUN npm ci              <- a layer
COPY . .                <- a layer

The layers are shared between images that have them in common, so a base image is downloaded once.

The order matters for the cache. A layer that changes invalidates every layer after it, which is why the dependency install comes before the source copy.

A layer is content-addressed, so the same content is stored once in the registry.

Pushing and pulling

# Log in
docker login registry.example.com

# Tag
docker tag app:local registry.example.com/app:1.2.3

# Push
docker push registry.example.com/app:1.2.3

# Pull
docker pull registry.example.com/app:1.2.3

A multi-architecture image is pushed as a manifest list, so the same tag resolves to the right architecture.

docker buildx build --platform linux/amd64,linux/arm64 \
  -t registry.example.com/app:1.2.3 --push .

Authentication

Docker stores the credential in ~/.docker/config.json after docker login.

Kubernetes uses an imagePullSecret.

kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=user \
  --docker-password=token
spec:
  imagePullSecrets:
    - name: regcred

A CI job authenticates with a token from the secret store, not a password.

A token should be scoped to push and pull the one repository, and it should expire.

Retention

A registry fills up. A retention policy deletes the old images.

The policy: keep the last N releases, keep every release that is deployed, and delete the rest.

A tag that is deployed must not be deleted, or a rollback fails.

A digest that is referenced by a running deployment must not be deleted.

A garbage collection removes the layers that no image references.

Security

A supply chain attack is when an attacker publishes a malicious image under a name that looks legitimate, or compromises a legitimate one.

The defences:

Pin a digest. A tag can be moved; a digest cannot.

Use a trusted registry. A public image from an unknown publisher is a risk.

Scan the image. A vulnerability scanner reports the known CVEs in the layers.

Sign the image. A signature lets the deploy verify the publisher.

cosign sign registry.example.com/app@sha256:8f3a...
cosign verify registry.example.com/app@sha256:8f3a...

Use a minimal base image. A smaller image has fewer packages and fewer vulnerabilities.

Do not run as root. A container that runs as root is a container that can do more damage.

A private registry prevents an anonymous pull, and it is not a substitute for the other measures.

A registry in a pipeline

The registry is the handoff point between the build and the deploy, and the pipeline is where the tag strategy is enforced. The build job produces an image tagged with the commit SHA, pushes it, and records the digest as an output. The deploy job pulls that digest rather than a tag, so the artifact that was tested is the artifact that runs. The second practice is to scan the image in the pipeline and to fail on a critical finding, which is the only point where a vulnerable base image can be caught before it ships. The third is to sign the image and to verify the signature at deploy, which closes the gap between the build and the run. The fourth is a retention policy that keeps every deployed digest, because a rollback that cannot pull its image is not a rollback.

Common mistakes

latest in production. It moves.

A tag that is re-pushed. The image that was tested is not the one that is deployed.

A credential in the Dockerfile. It is in the image layers.

A secret in a build argument. It is in the image history.

No retention policy. The registry fills up.

Deleting a deployed tag. The rollback fails.

An unsigned image. There is no way to verify the publisher.

A base image that is not pinned. FROM node:20 moves; FROM node:20.11.0-alpine3.19 does not.

No scan. A known CVE ships to production.

A quotable summary

A container registry stores and distributes images, and a client pushes to it and pulls from it. A tag is a mutable label and a digest is an immutable hash of the content, so a production deploy should pin a digest or a commit SHA rather than latest. An image is a set of shared layers, a private registry needs authentication, and the supply chain defences are to pin a digest, use a trusted registry, scan the image and sign it.

For the related topics, see docker-basics-guide and dockerfile-best-practices. For the broader context, dependency-vulnerability-scanning and kubernetes-basics.

Frequently asked questions

What is a container registry?
It is a service that stores and distributes container images. A client pushes an image to it and pulls it from it. Docker Hub, GitHub Container Registry, Amazon ECR and Google Artifact Registry are the common ones. A registry is the distribution layer between a build and a deploy.
What is the difference between a tag and a digest?
A tag is a human-readable label such as latest or 1.2.3, and it can be moved to point at a different image. A digest is a hash of the image content, such as sha256:abc..., and it always identifies the same image. A tag is convenient and a digest is exact.
Why is the latest tag a bad idea in production?
Because it moves. A deploy that pulls latest can get a different image than the one that was tested, and a rollback that pulls latest gets the same new image. Use an immutable tag such as the commit SHA, or a digest.
What is an image layer?
It is a filesystem change produced by an instruction in the Dockerfile. The layers are stacked to form the image, and they are shared between images that have them in common. This is why a base image is downloaded once and reused.
How do I authenticate to a private registry?
With a credential, usually a token or a service account. Docker uses docker login, which stores the credential locally. Kubernetes uses an imagePullSecret, which is a secret of type docker-registry referenced by the pod.
What is a supply chain attack on a registry?
It is when an attacker publishes a malicious image under a name that looks legitimate, or compromises a legitimate image. The defences are to pin a digest, to use a trusted registry, to scan the image, and to sign it so the deploy verifies the signature.