A container image reference such as registry.example/app:production looks stable in a deployment file. The tag is a human label, and the registry can point it at different bytes later. That is useful for releasing a new build and dangerous when an environment treats the label as a permanent identity. The content digest is the part of the reference that binds the deployment to specific bytes.
The Open Container Initiative image specification describes descriptors that identify content by media type, size, and digest. It recommends verifying referenced content against the digest before consuming it from an untrusted source. A deployment system that checks a digest at pull time but never records or enforces it has a weaker guarantee than the configuration suggests.
Separate convenience from identity
Developers use tags to communicate release intent. Operations should use immutable digest references for execution, admission, and rollback records. The two can coexist: a build pipeline resolves a tag, records the digest it resolved, and promotes that digest through environments. The production manifest then names the reviewed digest.
This also makes change review meaningful. If someone changes :production, the deployed digest changes. If an approved manifest changes from one digest to another, the diff has a security-relevant meaning. A policy that allows any registry tag to be pulled and run has no reliable answer to the question, "Which build was running during the incident?"
Verify the whole content graph
An image manifest refers to configuration and layers through descriptors. Each descriptor should be verified against its content. A local runtime or admission controller may verify the top-level manifest while trusting cached layers or accepting a different media type than expected. Test the complete path from registry response to running filesystem, including signature or provenance policy if it is part of the control.
Digest pinning is not a complete supply-chain control. It says that the bytes are the ones named by the digest. It does not by itself prove that the build was honest, that the registry is trusted, or that the image has no vulnerability. Signature verification, provenance policy, vulnerability analysis, and runtime restrictions address different questions.
Make the registry boundary explicit
A production cluster should pull from approved registries and namespaces through controlled credentials. Record whether the runtime allows tag pulls, digest pulls, or both for each workload class. If a policy controller enforces digest references, test its failure path with a syntactically valid tag. The admission response should be clear and the workload should not be created.
Mirrors and caches need the same care. A mirror can serve the correct digest or reject it. It should not be allowed to rewrite the image while preserving a convenient name. Verify that the registry's content-addressable API returns the content matching the requested digest, and keep the registry audit record alongside the deployment record.
Build a promotion record
A repeatable promotion flow can use these fields:
source repository and source commit
build pipeline identity
image digest and manifest digest
registry and repository name
signature or attestation identity when used
vulnerability review result and expiry date
deployment environment and rollout time
rollback digest and the reason for the previous choice
The exact data model is less important than consistency. If an operator can answer those questions from a deployment record, a tag change cannot silently erase the evidence that a different image was approved.
Test rollback and missing content
Deploy a test workload by digest, then remove access to that digest or point a tag elsewhere. Confirm that a new pod fails rather than falling back to an unreviewed tag. Test rollback by deploying the previous digest and verify that the running filesystem matches the recorded manifest. Check whether the runtime uses a local cache that can serve content after the registry has changed. Cached content is acceptable only when its digest and provenance are verified.
The practical rule is simple: tags are for humans, digests are for execution records. A team can still use friendly tags in release notes and developer commands. Production should be able to state the content identity it accepted, prove it, and reproduce it after the original tag has moved.