kubectl rollout: Usage, Options & Common CI Errors
Watch, gate, roll back, and restart deployments.
kubectl rollout is the control surface for Deployments, StatefulSets, and DaemonSets. In CI, rollout status is the canonical way to make a pipeline wait for - and fail on - a bad deploy.
What it does
rollout status blocks until a rollout completes or its progress deadline is exceeded, returning non-zero on failure - the ideal CI gate. rollout undo reverts to the previous (or a specific) revision. rollout restart triggers a fresh rollout without changing the spec (useful to pick up a rotated secret). rollout history and pause/resume round it out.
Common usage
kubectl rollout status deploy/web --timeout=120s
kubectl rollout restart deploy/web
kubectl rollout undo deploy/web
kubectl rollout undo deploy/web --to-revision=3
kubectl rollout history deploy/webCommon errors in CI
"error: deployment \"web\" exceeded its progress deadline" is the headline CI failure: new pods never became Ready within progressDeadlineSeconds (default 600s) - usually a failing readiness probe, ImagePullBackOff, or insufficient resources. rollout status exits non-zero here, which correctly fails the pipeline; pair it with kubectl describe and logs --previous to find the cause, then rollout undo to restore service. Always pass --timeout so the step fails fast instead of hanging until the job-level timeout.
Options
| Subcommand | Use |
|---|---|
| status | Block until rollout completes (CI gate) |
| undo | Roll back to previous/specific revision |
| restart | Trigger a fresh rollout, spec unchanged |
| history | List revisions |
| pause / resume | Halt and continue a rollout |