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=180sIn 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.
Using this in CI
A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods
# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info
# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodesKey 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.