kubectl set image: Usage, Options & Common CI Errors

Promote a workload to a freshly built image tag in one command.

kubectl set image updates a container's image on a live Deployment and triggers a rolling update. It is the single most common imperative CI deploy step: point a workload at the tag you just built.

What it does

kubectl set image deploy/NAME container=image:tag patches the named container's image, which Kubernetes treats as a template change and rolls out. You can update multiple containers in one call, and use *=image:tag to set every container at once.

Common usage

Terminal

kubectl set image deploy/web web=myreg/web:${GIT_SHA}
kubectl set image deploy/web web=myreg/web:${GIT_SHA} sidecar=myreg/proxy:${GIT_SHA}
kubectl set image deploy/web '*=myreg/web:${GIT_SHA}'
kubectl set image deploy/web web=myreg/web:${GIT_SHA} && \
  kubectl rollout status deploy/web --timeout=180s

Common errors in CI

"error: unable to find container named \"X\"" means the name before the = does not match the Deployment's container name - list it with kubectl get deploy/web -o jsonpath='{.spec.template.spec.containers[*].name}'. The silent CI bug: setting the same tag the Deployment already runs (e.g. re-pushed :latest) is a no-op - Kubernetes sees no spec diff and does NOT roll out, so the "new" image never deploys. Pin to an immutable tag like the commit SHA so every deploy is a real change, and always gate on kubectl rollout status.

Related guides

kubectl Cheat Sheet: Commands for Everyday KubernetesA kubectl cheat sheet - get, describe, logs, apply, rollout, debug, and context commands for daily Kubernetes… kubectl set env: Usage, Options & Common CI Errorskubectl set env adds, changes, or removes env vars on a workload. Sourcing from ConfigMaps/Secrets, removing… kubectl set resources: Usage, Options & Common CI Errorskubectl set resources patches CPU and memory requests and limits on a workload. Right-sizing in CI, the unsch… kubectl rollout history: Usage, Options & Common CI Errorskubectl rollout history lists a Deployment's revisions and their change-cause. Inspecting a specific revision…