kubectl rollout undo: Command Reference for CI/CD

By Kaveh Alemi·Latchkey

Revert a bad deploy to the last known-good revision.

kubectl rollout undo reverts a Deployment to its previous revision, or to a specific one you name. It is the rollback half of a safe CI deploy. This reference covers undo, history, and the change-cause annotation that makes history readable.

Common flags and usage

rollout undo deploy/<name>: revert to the previous revision
--to-revision=N: revert to a specific revision number
rollout history deploy/<name>: list revisions and change-causes
rollout history --revision=N: show one revision in detail
Annotate kubernetes.io/change-cause so history is meaningful

Example

shell

kubectl rollout history deploy/web
kubectl rollout undo deploy/web --to-revision=3
kubectl rollout status deploy/web --timeout=120s

In CI

Wire undo into the failure branch of your deploy gate so a rollout that misses its deadline auto-reverts. Set the change-cause annotation on each deploy (e.g. the commit SHA) so rollout history tells you exactly which revision to roll back to.

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.

Terminal

# 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

Key takeaways

undo reverts to the previous revision; --to-revision targets a specific one.
rollout history is only useful if you set change-cause annotations.
Chain undo into the failure path of rollout status for auto-rollback.

Frequently asked questions

kubectl rollout undo: Command Reference for CI/CD?

In CI?