
A container image digest is a content-based identifier for one exact image artifact. It is commonly represented with a sha256: value.
A tag can later be moved to another image. A digest stays fixed, so the image reference in the Kubernetes manifest continues to identify the same artifact.
Use the digest in the Kubernetes image: field. Keep the tag, release version or commit SHA separately in labels, annotations and release records for human-readable context.
The exact values depend on the chart. A common pattern uses separate repository and digest fields that render as repository@digest. Render the chart before deployment to confirm the generated manifest.
No. Digest pinning establishes which artifact is deployed. Image scanning identifies known vulnerabilities and policy issues in that artifact.
A Kubernetes deployment can say it is running v1.4.2 and still leave an important question unanswered: which exact image is behind that tag?
Tags are useful labels for humans. They make releases easier to read and discuss. But a tag can be moved to a different image after a deployment has been created. During an incident or rollback, this can make it harder to establish exactly what code is running.
Image digests solve that problem by giving Kubernetes an immutable reference to a specific image artifact. This guide explains how digests work, how to use them in Kubernetes and Helm, and how to verify the image running in a workload.
A typical Kubernetes manifest references an image by name and tag:
image: registry.example.com/acme/payments-api:1.4.2
The tag 1.4.2 is a readable release label. It does not, by itself, guarantee that the tag will always point to the same image.
For example, a CI pipeline may rebuild an image and push it again under the same tag. A registry administrator may correct a release tag. A deployment applied at two different times could then resolve the same tag to different image content.
Kubernetes supports both tags and digests in image references. Its documentation describes tags as version labels that can move, while digests are fixed identifiers for a specific image version. It also recommends avoiding :latest in production because it makes the deployed version and rollback state harder to track. Kubernetes image documentation.
An image digest is a content-based identifier, usually displayed with a SHA-256 prefix:
sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
The full image reference combines the image repository with that digest:
registry.example.com/acme/payments-api@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
The @ matters. It tells Kubernetes that the value after it is a digest rather than a tag.
OCI image descriptors use a digest as a content identifier. The digest is derived from the referenced bytes, which allows a client to verify that it retrieved the intended content. OCI Image Format Specification.
In practical terms, pinning an image by digest means that a change to a tag in the registry does not silently change the image reference in your manifest. The image must still be available in the registry, so retention policies remain important.
Most container registries show a digest in the image details page. CI/CD systems and container tooling can also expose it after an image is pushed.
For example, Docker Buildx can inspect a remote image reference:
docker buildx imagetools inspect registry.example.com/acme/payments-api:1.4.2
Look for the digest associated with the image or manifest list, then record the complete value in your release output.
The exact command and output vary by registry and build tooling. What matters is that the digest comes from the image you have built, scanned, approved and pushed.
A useful release record includes:
This keeps the readable release context while preserving an exact artifact reference.
Here is a simplified Deployment using an image digest:
apiVersion: apps/v1
kind: Deployment
metadata:
name: payments-api
labels:
app.kubernetes.io/name: payments-api
app.kubernetes.io/version: "1.4.2"
spec:
replicas: 3
selector:
matchLabels:
app.kubernetes.io/name: payments-api
template:
metadata:
labels:
app.kubernetes.io/name: payments-api
spec:
containers:
- name: payments-api
image: registry.example.com/acme/payments-api@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
ports:
- containerPort: 8080
The image field now contains an immutable reference. The app.kubernetes.io/version label keeps a human-readable release value for dashboards, logs and operational conversations.
Do not shorten or manually edit a digest. Copy the full value produced by your registry or pipeline.
Kubernetes documents the same image@sha256:... format for ensuring that a Pod starts from the same image version each time. Kubernetes image reference guidance explains why this avoids a tag later resolving to different code.
Das Meta's base Helm chart now supports digest pinning for its main container. Set image.repository and image.digest; when digest is non-empty, the chart renders repository@digest and ignores image.tag. The Das Meta base chart exposes this behavior in its current values and deployment template.
Use a production values file like this:
image:
repository: registry.example.com/acme/payments-api
digest: "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
This gives the release a chart-supported image reference rather than requiring each service chart to assemble one independently.
The digest setting applies to the main container. If a release also uses init or extra containers, configure and verify their image references separately.
Keep the chart version pinned in your delivery configuration. The chart version determines template behavior; the image digest identifies the application artifact that the rendered Deployment will use.
Before deployment, render the exact chart and values file:
helm repo add dasmeta https://dasmeta.github.io/helm
helm template payments-api dasmeta/base --version <approved-chart-version> -f values.production.yaml
Check that the rendered Deployment contains image: registry.example.com/acme/payments-api@sha256:... and the expected digest. Helm values can come from the chart defaults, a supplied values file or explicit parameters, with more specific inputs overriding defaults. Helm's values-file documentation is a useful reference when deciding where a production digest should be set.
There are two useful checks during an incident, deployment review or rollback.
First, inspect the declared image reference in the Deployment:
kubectl get deployment payments-api \
--namespace production \
-o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'
This confirms what Kubernetes has been asked to run.
Then inspect a running Pod:
kubectl get pod <pod-name> \
--namespace production \
-o jsonpath='{.status.containerStatuses[0].imageID}{"\n"}'
The runtime image identifier often includes the resolved digest, sometimes with a runtime-specific prefix such as docker-pullable://. Its exact format can vary between container runtimes and registry configurations.
Compare the declared image digest, the release record and the runtime image identifier. If they agree, you have a much clearer answer to the question: "What is running in production right now?"
This process gives a rollback an exact target. Instead of asking which build was behind 1.4.1, the team can deploy the recorded digest for the previously known-good artifact.
A semantic version tag is useful release context, but it becomes a reliable deployment reference only if the registry and delivery process guarantee immutability. A digest provides the fixed artifact identity directly.
A SHA-256 value is exact but difficult to read. Keep the release version, commit SHA or build number in labels, annotations and release records alongside the digest.
A digest cannot be pulled if the associated image has been deleted or is no longer accessible. Review retention policies before depending on digests for rollback.
A digest change is a deployment change. It should pass through the same reviewable workflow as other production configuration changes.
Digest pinning helps with deployment identity and reproducibility. It does not replace image scanning, signing, access controls, admission policies or runtime security monitoring.
For delivery and operational practices around production infrastructure, explore cloud infrastructure management and our AWS migration case study.