kubectl set image: Command Reference for CI/CD

The canonical one-line CI deploy: point a Deployment at a new tag.

kubectl set image updates a container image on a live workload and triggers a rollout. It is the simplest CI deploy step when you build, push, and promote a tag. This reference covers the syntax and the immutable-tag pitfall.

Common flags and usage

• set image deploy/<name> <container>=<image>:<tag>: update one container
• Use the exact container name from the pod template, not the Deployment name
• Multiple container=image pairs update several at once
• --record (deprecated) historically set change-cause; annotate instead
• Triggers a rollout only if the resulting spec actually changes

Example

kubectl set image deploy/web web=myreg/web:${IMAGE_TAG}
kubectl annotate deploy/web \
  kubernetes.io/change-cause="deploy ${GIT_SHA}" --overwrite
kubectl rollout status deploy/web --timeout=180s

In CI

Pin to an immutable tag like the commit SHA. Re-pushing :latest produces an identical spec, so Kubernetes sees no diff and never rolls out the new image. Verify the container name with kubectl get deploy/web -o jsonpath of spec.template.spec.containers, then gate on rollout status.

Key takeaways

• The container name must match the pod template, not the Deployment.
• Use immutable tags (commit SHA); :latest re-pushes do not trigger a rollout.
• Always follow set image with rollout status to gate the deploy.

Related guides