Kubernetes Deployment Image Update Management

Kubernetes Deployment Image Update Management is the practice of changing a Deployment's container image reference in a controlled, traceable way, covering the specific commands used, how image pull behavior interacts with the update, and the discipline needed to keep image references auditable across a fleet of Deployments.

kubectl set image

The Targeted Update Command

kubectl set image updates the image reference for a named container without requiring the full manifest, the most common way an image update is triggered outside of a full manifest reapplication.

kubectl set image deployment/image-update-management-example app=registry.example.com/app:1.4.0

Multi-Container Targeting

For Pods with multiple containers, each container's image can be updated independently or together in a single command, addressing them by name.

kubectl set image deployment/image-update-management-example app=registry.example.com/app:1.4.0 sidecar=registry.example.com/sidecar:2.1.0

imagePullPolicy Interaction

Why Policy Matters More Than It First Appears

imagePullPolicy: Always forces a fresh pull on every new Pod creation, including replacements during a rollout, ensuring the exact bytes referenced by a mutable tag are re-verified each time. IfNotPresent instead reuses a cached image if the node already has one matching that tag, which can silently serve stale content if the tag was overwritten in the registry without a corresponding cluster-side pull.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: image-update-management-example
spec:
  template:
    spec:
      containers:
        - name: app
          image: registry.example.com/app:1.4.0
          imagePullPolicy: Always

Immutable Tagging Discipline

Never Reusing a Tag

Image update management practice strongly favors a build pipeline that never republishes to an already-used tag, treating every tag (or, more robustly, every digest) as permanently bound to one specific image content, which makes IfNotPresent safe and makes rollback behavior fully predictable.

docker push registry.example.com/app:1.4.1

Digest Pinning for Maximum Certainty

Where absolute certainty is required, image update management can reference the digest directly rather than a tag, at the cost of a less human-readable manifest, guaranteeing the exact same image content regardless of any registry-side tag manipulation.

spec:
  template:
    spec:
      containers:
        - name: app
          image: registry.example.com/app@sha256:9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e

Tracking Image Changes Over Time

Change-Cause Annotations for Image Updates

Because an image update is one of the most common rollout triggers, attaching a kubernetes.io/change-cause annotation specifically describing the version change, not just "update," provides a much more useful kubectl rollout history output when investigating a regression weeks later.

kubectl annotate deployment image-update-management-example kubernetes.io/change-cause="app 1.3.0 -> 1.4.0, fixes memory leak in worker pool"

Automated Image Update Pipelines

CI/CD-Driven Updates

In mature setups, image update management is fully automated: a CI pipeline builds and pushes a new image, then patches the Deployment's image field through the same kubectl set image mechanism or a GitOps commit, removing manual image reference editing from the human workflow entirely and reducing the chance of a typo introducing an invalid reference.

kubectl set image deployment/image-update-management-example app=registry.example.com/app:${CI_COMMIT_SHA}

Image Update Management Diagram

Treating every image reference change as a deliberately triggered, traceable event, backed by immutable tagging discipline, is what keeps image update management reliable even as the frequency of deployments scales up across a large number of services.