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
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=180sCommon 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.
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 nodes