10.7 Kubernetes Deployment Revision Control

Kubernetes Deployment Revision Control is the historical tracking mechanism through which a Deployment retains a record of its previous Pod template configurations, represented as retained ReplicaSets, enabling operators to inspect the history of changes applied to a workload and to roll back to a specific prior configuration when a more recent change proves problematic.

Revisions as ReplicaSet Snapshots

Each ReplicaSet Represents a Revision

Every distinct Pod template change applied to a Deployment results in the creation of a new ReplicaSet, and each such ReplicaSet effectively serves as a snapshot of the Deployment's configuration at that point in time, with the ReplicaSet itself retained even after being scaled down to zero replicas following a subsequent update.

Revision Numbering

Each revision is tracked using a monotonically increasing revision number stored as an annotation on the corresponding ReplicaSet, allowing revisions to be referenced and compared in a strict chronological order regardless of how many updates have occurred or how much time has passed between them.

Change Cause Tracking

Recording Why a Revision Was Created

Deployments can record a change cause annotation describing the reason a particular revision was created, such as referencing a specific configuration change or deployment pipeline step, providing human-readable context alongside the otherwise opaque revision number when reviewing history later.

Value for Auditing and Troubleshooting

This recorded context becomes particularly valuable during incident response, when an operator reviewing a Deployment's rollout history needs to quickly correlate a specific revision with the change that produced it, rather than having to cross-reference external deployment logs or version control history separately.

revisionHistoryLimit

Bounding Retained History

The revisionHistoryLimit field caps how many old, scaled-down ReplicaSets are retained for historical and rollback purposes, with older revisions beyond this limit being garbage collected automatically, balancing the operational value of extended history against the accumulation of unused objects in the cluster.

Tradeoffs in Setting This Limit

A higher limit preserves a longer rollback window at the cost of retaining more inactive ReplicaSet objects indefinitely, while a lower limit keeps the cluster tidier but restricts how far back in history an operator can roll back without needing to manually reconstruct an earlier configuration.

Rollback Mechanics

Selecting a Target Revision

A rollback operation selects a specific prior revision, either the immediately preceding one or an explicitly specified earlier revision number, and reapplies that revision's Pod template as the Deployment's current desired template, triggering the standard rolling update process to transition toward it.

Rollback Is Itself a New Revision

Performing a rollback does not erase or rewind history; it generates a new revision whose Pod template matches the old, targeted revision, meaning the revision history continues to grow forward even when the effective configuration is reverting to something previously seen.

Observing Revision History

Inspecting Rollout History

Revision history can be inspected to review the sequence of changes applied to a Deployment over time, including the revision number, associated change cause where recorded, and by cross-referencing the corresponding ReplicaSet, the exact Pod template that revision represents.

Correlating Revisions With Incidents

When diagnosing a regression introduced by a recent change, comparing the currently active revision's template against a previous one using this history provides a precise way to identify exactly what changed between a known-good state and the current, potentially problematic one.

Limitations of Revision Control

No Retention of Non-Template Changes

Revision history in a Deployment tracks changes to the Pod template specifically; adjustments to fields outside the template, such as the replicas count during ordinary scaling, do not themselves generate a new revision, since they do not alter which ReplicaSet is considered the current active version.