Kubernetes StatefulSet Revision Management

Kubernetes StatefulSet Revision Management is the specific internal mechanism, ControllerRevision objects, through which a StatefulSet tracks Pod template history, structurally distinct from a Deployment's ReplicaSet-based revisions, and the resulting status fields that let individual ordinals sit at different revisions simultaneously during a partitioned rollout.

ControllerRevision as the Storage Mechanism

A Generic History Object, Not a Full Controller

Unlike a Deployment, which represents each revision as a complete, independently scalable ReplicaSet, a StatefulSet stores each historical Pod template as a ControllerRevision object, a lightweight, generic Kubernetes resource holding a serialized patch of the template rather than a live, schedulable set of Pods.

kubectl get controllerrevision -l app=db

NAME                            CONTROLLER                              REVISION
revision-management-example-1   statefulset.apps/revision-management-example   1
revision-management-example-2   statefulset.apps/revision-management-example   2

Why This Structural Difference Exists

Because a StatefulSet's Pods are never interchangeable and are always addressed by fixed ordinal identity, there is no need for a full parallel ReplicaSet per revision the way a Deployment uses to manage a pool of anonymous replicas; a lightweight template snapshot is sufficient since the controller applies it directly to specific, already-identified Pods rather than needing to instantiate a separate managed pool.

currentRevision and updateRevision Status Fields

Tracking Two Revisions Simultaneously

status.currentRevision identifies the ControllerRevision that ordinals below the partition value are still running, while status.updateRevision identifies the one ordinals at or above the partition have been updated to, a dual-tracking scheme with no direct Deployment equivalent since a Deployment's ReplicaSets each independently represent a single revision.

kubectl get statefulset revision-management-example -o jsonpath='{.status.currentRevision} vs {.status.updateRevision}'

revision-management-example-7d4b9c8f6d vs revision-management-example-6c9f8b7d5e

Per-Ordinal Revision Coexistence

A Single Point-in-Time Snapshot Spanning Two Revisions

During a partitioned rollout, status.updatedReplicas and the individual Pod's own controller-revision-hash label reveal that some ordinals are genuinely running one revision while others run a different one simultaneously, a state a Deployment never exhibits since its ReplicaSets fully separate old and new Pod populations rather than mixing them within Pods that share a single controller identity.

kubectl get pods -l app=db -L controller-revision-hash

NAME                       CONTROLLER-REVISION-HASH
revision-management-example-0   revision-management-example-7d4b9c8f6d
revision-management-example-1   revision-management-example-7d4b9c8f6d
revision-management-example-2   revision-management-example-6c9f8b7d5e

Revision Retention

Governed by the Same revisionHistoryLimit Field

spec.revisionHistoryLimit bounds retained ControllerRevision objects identically in spirit to a Deployment's retained ReplicaSets, though the objects being pruned are the lighter-weight ControllerRevision resources rather than full ReplicaSets with their own Pod-creation capability.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: revision-management-example
spec:
  revisionHistoryLimit: 10

Revision Management Diagram

Understanding ControllerRevision as the mechanical foundation beneath everything discussed in StatefulSet update and rollback management clarifies why partitioned, mixed-revision states are a normal, fully supported operating mode for StatefulSets in a way that has no direct parallel in Deployment behavior.