12.19 Kubernetes StatefulSet Revision Management

Kubernetes StatefulSet Revision Management is the technical mechanism by which a StatefulSet tracks historical versions of its Pod template using ControllerRevision objects, and separately tracks which specific revision each individual ordinal is currently running, providing a per-instance view of update state that differs structurally from the ReplicaSet-based revision tracking used by Deployments.

ControllerRevision as the Underlying Object

A Shared Revision Mechanism Across Controller Types

Unlike Deployments, which track revisions implicitly through separate ReplicaSet objects, StatefulSets rely on a dedicated ControllerRevision object type, also shared with DaemonSets, to capture a snapshot of the Pod template's state at each point a change is introduced, functioning as a compact, purpose-built revision record rather than reusing a full workload object for this purpose.

Revision Hash and Content Storage

Each ControllerRevision stores a serialized representation of the Pod template alongside a revision number and a hash uniquely identifying its content, allowing the controller to efficiently detect whether a given ordinal's current configuration matches an existing known revision or represents a genuinely new template state requiring a new revision to be recorded.

Per-Ordinal Revision Tracking

currentRevision and updateRevision Status Fields

The StatefulSet's status includes currentRevision, identifying the revision most ordinals are expected to be running, and updateRevision, identifying the newest revision introduced by the most recent template change, with these two fields diverging during an active rollout and converging once every ordinal has been updated.

Individual Ordinal Revision Association

Beyond these aggregate status fields, each Pod itself carries a label or annotation identifying which specific ControllerRevision it was created from, allowing precise determination of exactly which ordinals have been updated to the new revision and which remain on the previous one at any point during a partitioned or in-progress rollout.

Revision History Retention

revisionHistoryLimit Field

The revisionHistoryLimit field, present on StatefulSets in the same manner as on Deployments, bounds how many historical ControllerRevision objects are retained, with older revisions beyond this limit being garbage collected once no ordinal is currently associated with them.

Retention Tied to Active Ordinal Usage

Because a ControllerRevision remains relevant only as long as some ordinal is still running that specific template state, revision cleanup for StatefulSets is influenced both by the configured history limit and by whether any ordinal continues to reference an older revision, distinguishing this from the more straightforward ReplicaSet-based retention used by Deployments.

Using Revision Information for Rollback

Manual Reapplication Rather Than Automated Rollback Commands

While the underlying ControllerRevision objects contain sufficient information to identify a previous template state, StatefulSets do not expose the same built-in, automated rollback command available for Deployments, meaning reverting to a previous revision requires manually extracting and reapplying that revision's stored template content as a new template change.

Inspecting Revision Content for Historical Reference

Directly inspecting the stored content of a retained ControllerRevision provides a reliable way to recover the exact Pod template configuration from an earlier point in the StatefulSet's history, useful both for manual rollback purposes and for auditing exactly what configuration was in effect at a given past revision.

Revision Consistency During Partitioned Rollouts

Coexistence of Two Revisions Across Ordinals

During a partitioned rollout, ordinals above the partition boundary run the updateRevision while those below continue running the currentRevision, meaning revision management during this period involves tracking two simultaneously active revisions across different subsets of ordinals until the partition value is lowered and the rollout fully completes.