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 |
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