Kubernetes Image Pull Policy: Tags, Digests, Cache Semantics, and Reproducible Rollouts

Kubernetes image references and imagePullPolicy jointly determine which container image a node can start. The policy does not make a mutable tag immutable, replicate a local cache between nodes, or guarantee that a registry is reachable. In production, confusing these behaviors can create mixed application versions, cold-start failures after autoscaling, or rollbacks that do not restore the intended bytes.

The safest mental model is to separate identity from retrieval. A tag is a human-friendly registry reference that can be moved; a digest identifies content. imagePullPolicy controls whether the kubelet asks the runtime to resolve or fetch an image when it starts a container. A reliable rollout therefore needs an explicit artifact identity and a deliberate pull behavior, not a guess based on whether a node probably has a cached layer.

Compare the three pull policies

Policy	Kubelet/runtime behavior	Typical operational consequence
`IfNotPresent`	Use a locally present image; pull it when it is absent	Fast starts from warm nodes, but a mutable tag can resolve differently on different nodes over time
`Always`	Ask the runtime to resolve the image name when starting a container and pull missing layers	A moved tag can resolve to new content; cached layers need not be downloaded again, but registry resolution and access still matter
`Never`	Do not fetch the image; start only if the required image is already local	Suitable only when node image contents are managed and verified as part of the node lifecycle

With Always, the kubelet asks the runtime to pull, and the runtime resolves the reference to a digest. If the required layers are already cached, the runtime can reuse them rather than download them again. This does not mean Always can start while the registry is unreachable: name resolution and authorization may still require a registry request. It also does not mean the bytes behind a tag are frozen.

With IfNotPresent, the local image wins when present. That makes a node’s cache part of runtime behavior. Two nodes can have different images cached under the same mutable tag, so a rescheduled Pod may start different bytes even though its Pod template did not change. Never is stricter: if a replacement node does not already contain the expected image, startup fails instead of falling back to a registry pull.

Understand defaulting and the creation-time trap

When imagePullPolicy is omitted, Kubernetes sets it when the Pod or PodTemplate-bearing object is first created. Current defaults are:

An image using :latest, or an image with no tag, defaults to Always.
An image using a non-latest tag defaults to IfNotPresent.
An image specified by digest defaults to IfNotPresent.

The API does not continuously recalculate that default when the image reference later changes. For example, a Deployment initially created with app:v4 receives IfNotPresent. If a later edit changes its template to app:latest but leaves out the policy, the policy remains IfNotPresent; changing the tag does not retroactively apply the creation-time default. Review the fully rendered PodTemplate rather than assuming omission means the policy most appropriate to its current image.

This detail is especially important for Helm, Kustomize, GitOps, and admission mutation. A chart may omit the field, a controller may default it, and a later template update may preserve the old value. Inspect the rendered manifest and the object served by the API server:

helm template catalog ./chart -f values-production.yaml
kubectl get deployment catalog -n production -o jsonpath='{range .spec.template.spec.containers[*]}{.name}{"\t"}{.image}{"\t"}{.imagePullPolicy}{"\n"}{end}'
kubectl get pods -n production -l app=catalog -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{range .status.containerStatuses[*]}{.imageID}{" "}{end}{"\n"}{end}'

imageID provides useful evidence about what the runtime reports for a running container, while the PodTemplate shows the declared reference and policy. Verify the exact runtime’s reported format and avoid treating a tag string alone as proof of the bytes running.

Prefer immutable deployment identity

Registry tags can be moved. If one node pulls catalog:stable before the registry updates it and another pulls the tag later, the nodes can receive different image content. Under IfNotPresent, a node with the old cached tag may keep using it; under Always, a later container start may resolve the tag to the new digest. This can occur inside a workload whose PodTemplate still says the same tag.

For reproducible deployments, use a digest reference:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: catalog
spec:
  replicas: 3
  selector:
    matchLabels:
      app: catalog
  template:
    metadata:
      labels:
        app: catalog
    spec:
      containers:
        - name: app
          image: registry.example.com/platform/catalog@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
          imagePullPolicy: IfNotPresent

The digest above is illustrative and is not a valid published image reference. Obtain the real digest from the registry or build pipeline, verify it as part of release promotion, and preserve the mapping from source commit and build provenance to that digest. A digest pins the content identity even if a human-friendly tag later points elsewhere.

A digest does not itself prove who built the image, whether it passed policy, or whether it is safe. It makes the artifact identity stable; signing, provenance verification, vulnerability policy, and release authorization remain separate controls. Record the exact digest in the deployment artifact and rollback record so that a rollback restores the old content rather than a tag that may have been moved.

For multi-platform images, a reference may identify an image index whose platform-specific manifests differ. Ensure the build and promotion pipeline records the index digest and validates the expected architecture-specific output on every node platform in scope. Do not assume an image digest makes x86-64 and arm64 container filesystems byte-identical; it ensures the same referenced index or manifest identity is resolved according to platform.

Choose policy based on the delivery and recovery contract

Digest plus IfNotPresent is a common production combination: immutable identity prevents a warm cache from masking tag changes, and the node can reuse the exact content if already present. A cold node still needs registry access unless the image is deliberately preloaded and Never is selected. A digest with Always can be useful when policy requires an authenticated registry check on each container start, but it still resolves the same immutable content and may reuse cached layers.

Mutable tags with Always are sometimes used in development or controlled environments where starting a container should discover a moved tag. They trade reproducibility for freshness-at-start and may introduce registry availability into restart behavior. Mutable tags with IfNotPresent are particularly easy to misoperate: a tag update may affect some nodes but not others, and an ordinary Pod restart may not fetch the new bytes from a warm node.

Never should be used only with a verifiable preload process. The node image or bootstrap workflow must provide the exact image for every workload that can land on the node, keep those images during node upgrades, and validate architecture and digest. Managed autoscaling usually replaces nodes from a base image; unless preloading is part of that supported lifecycle, a new node may lack the image and fail to start the Pod. Kubernetes documents pre-pulled images as unsuitable when a cloud provider replaces nodes automatically unless image availability is reliably controlled.

Separate pull policy from image garbage collection and credentials

Image pull policy does not decide which unused images the kubelet later removes. Kubelet image garbage collection has its own thresholds and age settings. A Never workload can fail after node replacement or cache cleanup even though it worked previously. A workload using IfNotPresent can also require a pull after the image is removed from local storage. Design cache retention and node replacement around the same recovery requirements as the pull policy.

Pull policy is also separate from authorization. imagePullSecrets, node credentials, or an exec credential provider determine whether the registry permits a pull; imagePullPolicy determines whether a pull attempt is requested. Always cannot fix an expired credential, an incorrect repository scope, or a registry outage. IfNotPresent may appear to hide a credential problem while a warm cache exists, then fail on a cold node. Test with a fresh node and the same identity path used in production.

Validate the rollout on warm and cold nodes

Before a release, record the intended image digest, the rendered policy, registry authorization scope, and the nodes’ architecture/runtime set. Test at least:

A warm-node start where the exact digest is present locally.
A cold-node start that must authenticate and download the image.
A replacement or autoscaled node created from the supported node image.
A rollback to the previous digest after a failed rollout.
A moved mutable tag in a non-production environment, if mutable tags are intentionally used.
Registry unavailability or credential expiry, with a clear expected failure and alert.

Inspect Pod events, node assignment, image reference, policy, and runtime-reported image ID. Measure registry resolution latency, download time, backoff, and application readiness separately. If Always is intended, verify a cold-node registry check succeeds and a warm-node start reuses cached layers. If Never is intended, prove every replacement node has the exact image before the workload can schedule there.

Make the rendered PodTemplate explicit in production. An explicit imagePullPolicy avoids relying on defaults that were fixed when the object was first created. Promote immutable digests, canary the exact artifact, verify status after rollout, and keep the previous digest retrievable until the rollback window expires. This yields a rollout whose artifact identity, pull attempt, and recovery behavior can all be reviewed independently.

Related:

Sources: