Tag vs digest strategy — immutability and reproducibility

Tag vs digest is the immutability vs convenience trade-off in image references. This lesson walks tags, digests, the trade-offs, the recommendation, and the discipline.

Tags vs digests

flowchart LR
    A[Image references] --> B[Tags]
    A --> C[Digests]
    B --> B1["Mutable: myapp:1.2.3"]
    B --> B2["myapp:latest"]
    C --> C1["Immutable: myapp@sha256:abc..."]
    C --> C2[Specific bytes]

Tags vs digests:

• Tags. Mutable; a re-push can change the contents. e.g., myapp:1.2.3 may refer to different bytes over time.
• Digests. Immutable; SHA256 hash of the image manifest. e.g., myapp@sha256:abc... always refers to the same bytes.

Pulling by digest

# Get the digest of an image
docker inspect --format='{{index .RepoDigests 0}}' \
  myapp:1.2.3

# Output: myapp@sha256:abc123...

# Pull by digest
docker pull myapp@sha256:abc123...

The digest is the SHA256 hash of the image manifest. The hash is computed by the registry at push time and never changes.

Using digests in Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
        - name: app
          image: registry.example.com/myapp@sha256:abc123...
          imagePullPolicy: IfNotPresent

The Pod references the image by digest. The kubelet pulls the exact bytes identified by the digest.

# Track image versions via digest
sum by (image) (kube_pod_container_info)

The trade-offs

flowchart LR
    A[Tags] --> B[+ Convenient]
    A --> C["- Mutable: surprises"]
    D[Digests] --> E["+ Immutable: reproducible"]
    D --> F[- Hard to read]
    D --> G[- More verbose]

The trade-offs:

Tags:

• Pros: Convenient; human-readable; CI/CD workflows are familiar.
• Cons: Mutable; a re-push can change the bytes; surprises.

Digests:

• Pros: Immutable; reproducible; exact bytes.
• Cons: Hard to read (long SHA256 strings); more verbose in YAML.

The recommendation

flowchart LR
    A[Recommendation] --> B["Development: tags"]
    A --> C["Production: digests"]
    B --> B1[Convenient for iteration]
    C --> C1[Reproducible for safety]
    C --> C2[Combined with semantic version tags]

The recommendation:

• Development. Tags are convenient; iteration is fast.
• Production. Digests ensure the exact bytes deployed; combined with semantic version tags (:1.2.3 becomes @sha256:abc... with a comment referencing the tag).

# Production: digest + comment with tag
containers:
  - name: app
    # 1.2.3
    image: registry.example.com/myapp@sha256:abc123...

The comment documents the version; the digest ensures reproducibility.

The CI/CD workflow

flowchart LR
    A["CI: build image"] --> B[Push to registry]
    B --> C[Get digest]
    C --> D[Update manifest with digest]
    D --> E[Commit to Git]
    E --> F[Argo CD syncs]

The workflow:

1. CI builds the image.
2. CI pushes the image to the registry.
3. CI queries the digest (docker inspect or registry API).
4. CI updates the Kubernetes manifest with the digest.
5. CI commits the updated manifest to Git.
6. Argo CD (or Flux) syncs the manifest.

The digest is captured at push time and stored in Git; the cluster always pulls the exact bytes.

Quiz

The operational discipline

Tag vs digest in production rests on five non-negotiable elements:

• Pin digests in production. Reproducibility; defence against tag mutation.
• Comment with the tag. Human readability.
• Automate digest capture in CI. Manual capture is error-prone.
• Test the digest pinning. Verify the deployment pulls the expected bytes.
• Document the strategy. In the runbook: tags for dev, digests for prod.

Tag vs digest is the immutability vs convenience trade-off. The discipline is digests for production with CI/CD automation.