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
kubectl rollout restart deploy/web
kubectl rollout restart statefulset/db
kubectl rollout restart deploy/web && kubectl rollout status deploy/web --timeout=120sCommon 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.
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