kubectl rollout history

When to Use kubectl rollout history

kubectl rollout history shows the revision history of a deployment, DaemonSet, or StatefulSet. Each change to the pod template creates a new revision. The history allows you to inspect what changed in each revision and decide which revision to roll back to if needed.

Viewing History

# View the revision list
kubectl rollout history deployment/my-app
# REVISION  CHANGE-CAUSE
# 1         Initial deployment
# 2         Updated image to v1.2
# 3         Updated image to v1.3
# 4         Added resource limits

The CHANGE-CAUSE column shows the value of the kubernetes.io/change-cause annotation at the time of each revision. Without this annotation, the column shows <none>.

Adding Change Causes

Document your changes by annotating the deployment before or after the update:

# Annotate after applying changes
kubectl apply -f deployment.yaml
kubectl annotate deployment/my-app kubernetes.io/change-cause="Deployed v2.1 with new logging config"

# Or set the annotation in the YAML manifest
# metadata:
#   annotations:
#     kubernetes.io/change-cause: "v2.1 release"

Meaningful change causes make the history actionable. When reviewing the history during an incident, you can quickly identify which change might have caused the problem.

Inspecting Specific Revisions

Use --revision to see the full pod template of a specific revision:

# View details of revision 3
kubectl rollout history deployment/my-app --revision=3

# Output includes:
# - Container images
# - Environment variables
# - Resource requests and limits
# - Volume mounts
# - Labels and annotations

# Get the full YAML for a revision
kubectl rollout history deployment/my-app --revision=3 -o yaml

Comparing Revisions

To understand what changed between revisions, inspect each one:

# Compare revision 2 and 3
kubectl rollout history deployment/my-app --revision=2 > rev2.yaml
kubectl rollout history deployment/my-app --revision=3 > rev3.yaml
diff rev2.yaml rev3.yaml

This shows exactly which fields changed, making it clear whether the issue is an image change, an environment variable update, or a resource limit modification.

Revision History Limit

Kubernetes retains old ReplicaSets to enable rollbacks. The revisionHistoryLimit field controls how many are kept:

spec:
  revisionHistoryLimit: 10  # default

Each old ReplicaSet corresponds to a revision. When the limit is reached, the oldest ReplicaSets are garbage collected. Setting this too low limits your rollback options. Setting it too high wastes etcd storage.

# Check the current revision history limit
kubectl get deployment my-app -o jsonpath='{.spec.revisionHistoryLimit}'

# View all ReplicaSets (each is a revision)
kubectl get rs -l app=my-app --sort-by=.metadata.creationTimestamp

Using History for Incident Response

During an incident, the rollout history helps determine when the problem started:

# Step 1: View the history
kubectl rollout history deployment/my-app

# Step 2: Identify the suspicious revision
kubectl rollout history deployment/my-app --revision=4

# Step 3: Compare with the last known good revision
kubectl rollout history deployment/my-app --revision=3

# Step 4: Roll back if needed
kubectl rollout undo deployment/my-app --to-revision=3

History Across Resource Types

Rollout history works with any resource type that supports rolling updates:

# Deployment history
kubectl rollout history deployment/my-app

# DaemonSet history
kubectl rollout history daemonset/node-exporter -n monitoring

# StatefulSet history
kubectl rollout history statefulset/postgresql -n databases

Best Practices

Always annotate deployments with meaningful change causes. Set revisionHistoryLimit to a value that balances storage with rollback flexibility (10 is a reasonable default). Regularly review history during incidents to correlate deployment changes with issues. Include the change cause annotation in your CI/CD pipeline so every automated deployment is documented. Store revision details alongside deployment manifests in your version control for long-term audit trails.