kubectl rollout restart: Usage, Options & Common CI Errors

Restart every pod in a workload without editing its spec.

kubectl rollout restart performs a rolling restart of a Deployment, StatefulSet, or DaemonSet, cycling its pods while keeping the spec unchanged. It is the standard way to make pods re-read a rotated Secret or ConfigMap in CI.

What it does

kubectl rollout restart deploy/NAME stamps a restartedAt annotation into the pod template, which Kubernetes treats as a change and rolls out gradually - honouring maxSurge/maxUnavailable so there is no downtime. Nothing about the desired image or env changes; only the pods are replaced.

Common usage

Terminal

kubectl rollout restart deploy/web
kubectl rollout restart statefulset/db
kubectl rollout restart deploy/web && kubectl rollout status deploy/web --timeout=120s

Common errors in CI

A restart can stall exactly like a deploy: if the new pods fail readiness, the rolling restart wedges at maxUnavailable and never completes, so always follow it with kubectl rollout status --timeout so the step fails fast. A common misconception is that restart reloads a mounted ConfigMap automatically - it does, because the new pods re-mount it, but env vars sourced from a ConfigMap at start time only update on restart, which is exactly why this command exists. Restarting a single-replica Deployment briefly drops the service unless you have a surge configured.

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 rollout history: Usage, Options & Common CI Errorskubectl rollout history lists a Deployment's revisions and their change-cause. Inspecting a specific revision… kubectl rollout pause: Usage, Options & Common CI Errorskubectl rollout pause freezes a Deployment so multiple edits batch into one rollout. Canary staging in CI, an… kubectl set env: Usage, Options & Common CI Errorskubectl set env adds, changes, or removes env vars on a workload. Sourcing from ConfigMaps/Secrets, removing…