3.2.3.4 Digest Deployment Pinning

Digest deployment pinning is the practice of specifying an image by its exact content digest in deployment configuration, rather than by a tag, ensuring that what gets deployed is precisely and verifiably the intended content, immune to any later tag reassignment.

Pinning in Deployment Manifests

Rather than referencing an image by a tag that could change meaning over time, deployment configuration can reference the specific digest that was validated, locking the deployment to that exact content.

spec:
  containers:
    - name: myapp
      image: registry.example.com/myapp@sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Applying this configuration always deploys exactly this content, regardless of what registry.example.com/myapp:latest or any other tag currently points to.

Generating Pinned References Automatically

Because manually copying digests is error-prone, deployment pipelines commonly resolve a tag to its digest automatically at the moment of deployment, pinning the resulting manifest to that resolved value rather than requiring a person to look it up.

DIGEST=$(docker inspect myapp:2.3.0 --format '{{index .RepoDigests 0}}')
sed -i "s|myapp:2.3.0|$DIGEST|" deployment.yaml

Why Pinning Matters for GitOps Workflows

In deployment workflows where configuration itself is version-controlled and treated as the source of truth, pinning by digest means the deployment configuration's history accurately reflects exactly what content was deployed at each point in time, since a tag-based reference would not preserve this information once the tag was later reassigned.

git log -p deployment.yaml

Reviewing this history shows the exact digest deployed at each commit, which a tag-only history would not reliably capture.

Tradeoffs of Digest Pinning

Pinning by digest sacrifices some convenience — deployment configuration must be updated explicitly with each new digest rather than simply being left pointing at a tag that updates automatically — which is a deliberate tradeoff favoring certainty over convenience.

kubectl set image deployment/myapp myapp=registry.example.com/myapp@sha256:newdigest...

Why Digest Deployment Pinning Matters

Pinning deployments by digest is one of the most direct, concrete steps toward eliminating ambiguity about exactly what is running in a given environment, particularly valuable for production systems where unexpected drift in deployed content carries real operational or security risk.