kubectl set image: Update Deployment Images in CI

Change the container image of a workload, triggering a rolling update.

kubectl set image updates the image of a container in a Deployment, StatefulSet, or DaemonSet, which kicks off a rolling update. It is a quick imperative way to ship a new tag in CI without editing manifests. The container name must match exactly.

Common flags

• RESOURCE/NAME - e.g. deployment/api (positional)
• CONTAINER=IMAGE - container name mapped to the new image
• -n NAMESPACE - target namespace
• --record - annotate the change (deprecated but still seen)

Example in CI

Point the api container at a new image tag.

kubectl set image deployment/api \
  api=us-docker.pkg.dev/my-project/repo/api:${GITHUB_SHA} \
  -n prod

Common errors in CI

• unable to find container named "X" - container name does not match the spec
• deployments.apps "api" not found - wrong resource name or namespace
• ImagePullBackOff (seen later) - image tag wrong or registry pull secret missing

Key takeaways

• Imperatively updates a workload image and starts a rolling update.
• The container name in CONTAINER=IMAGE must match the pod spec exactly.
• Follow it with kubectl rollout status to confirm the rollout succeeded.

Related guides