kubectl rollout history: Usage, Options & Common CI Errors

See every revision of a Deployment and what changed.

kubectl rollout history lists the revisions a Deployment, StatefulSet, or DaemonSet has gone through, so you can pick a target to roll back to. In CI it is how you confirm a deploy actually produced a new revision.

What it does

kubectl rollout history deploy/NAME prints the revision numbers and their CHANGE-CAUSE annotation. Add --revision=N to dump the full pod template for one revision so you can diff what that rollout shipped. The number of revisions kept is bounded by spec.revisionHistoryLimit (default 10).

Common usage

Terminal

kubectl rollout history deploy/web
kubectl rollout history deploy/web --revision=3
kubectl rollout history statefulset/db
kubectl annotate deploy/web kubernetes.io/change-cause="deploy ${GIT_SHA}"

Common errors in CI

A CHANGE-CAUSE column showing only "<none>" is the usual surprise: the cause is populated from the kubernetes.io/change-cause annotation, which is no longer set automatically - set it yourself on every deploy so history is meaningful. "error: unable to find specified revision N in history" means that revision aged out past revisionHistoryLimit, so you cannot roll back to it; raise the limit if you need a deeper window. Remember a re-applied identical spec does not create a new revision, so history will not grow on a no-op deploy.

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 undo: Usage, Options & Common CI Errorskubectl rollout undo rolls a Deployment back to its previous or a specific revision. Automated rollback on a… kubectl rollout restart: Usage, Options & Common CI Errorskubectl rollout restart triggers a rolling restart without changing the spec. Picking up rotated secrets and… kubectl annotate: Usage, Options & Common CI Errorskubectl annotate attaches non-identifying metadata to resources. Annotations vs labels, and the change-cause…