kubectl set image: Update a Container Image
kubectl set image changes the image of one or more containers in a workload, which the controller rolls out automatically.
The most common deploy action is bumping an image tag. set image does exactly that and kicks off the rollout in one command.
What it does
kubectl set image updates spec.template.spec.containers[].image for the named container(s) using <container>=<image> pairs. The change to the pod template triggers a rolling update on a Deployment, StatefulSet, or DaemonSet. Use *=<image> to set every container in the workload.
Common usage
kubectl set image deployment/api api=ghcr.io/acme/api:v2
# multiple containers at once
kubectl set image deploy/api api=acme/api:v2 sidecar=acme/proxy:v2
# CI: set, then wait for the rollout
kubectl set image deploy/api api=acme/api:$SHA
kubectl rollout status deploy/api --timeout=180sOptions
| Syntax / Flag | What it does |
|---|---|
| <container>=<image> | Set a specific container image |
| *=<image> | Set the image on every container |
| --record | Record the command in change-cause (deprecated) |
| -l, --selector | Apply to all workloads matching a label |
| --dry-run=client -o yaml | Preview the change without applying |
In CI
Set a unique tag (an immutable digest or the commit SHA), not :latest; reusing a tag means the pod template does not change and no rollout is triggered. Always follow with kubectl rollout status --timeout so a failed image bump fails the job. Record the cause with an annotation since --record is deprecated.
Common errors in CI
"error: unable to find container named \"<name>\"" means the container name in the pair does not match the spec; list it with kubectl get deploy api -o jsonpath=\'{.spec.template.spec.containers[*].name}\'. If nothing rolls out, the new image string equals the old one (same tag). A subsequent rollout that hangs with ImagePullBackOff usually means a bad tag or a missing pull secret.