10.11 Kubernetes StatefulSet Controller

Kubernetes StatefulSet Controller is the workload controller designed to manage stateful applications requiring stable, unique network identities and persistent storage that survives Pod replacement, distinguishing itself from ReplicaSets and Deployments by preserving ordinal-based Pod identity and enforcing strict, ordered creation and deletion semantics across its managed Pods.

Stable Pod Identity

Ordinal-Based Naming

Each Pod managed by a StatefulSet receives a name derived from the StatefulSet's own name combined with a numeric ordinal, starting at zero, such that a StatefulSet named web produces Pods named web-0, web-1, and so on, with this naming convention preserved consistently even as individual Pods are replaced over time.

Stable Network Identity

Combined with a headless Service, each StatefulSet Pod receives a stable, predictable DNS hostname derived from its ordinal name, allowing other components in the cluster to address a specific Pod instance directly and reliably, rather than relying on a load-balanced virtual IP that could route to any interchangeable replica.

Ordered Pod Management

Sequential Creation

When scaling up, the StatefulSet controller creates Pods one at a time in strict ordinal order, waiting for each Pod to become running and ready before proceeding to create the next, ensuring that Pod web-1 is never created before web-0 has successfully started.

Sequential Termination

When scaling down, Pods are terminated in strict reverse ordinal order, meaning the highest-numbered Pod is removed first, preserving a predictable, ordered reduction that mirrors the ordered creation process rather than removing Pods in an arbitrary or parallel fashion.

Persistent Storage Association

Per-Ordinal PersistentVolumeClaims

Through volumeClaimTemplates, a StatefulSet automatically generates a distinct PersistentVolumeClaim for each Pod ordinal, ensuring that each Pod instance has its own dedicated persistent volume rather than sharing storage with its sibling Pods.

Volume Retention Across Pod Replacement

When a StatefulSet Pod is replaced, whether due to failure or deliberate deletion, its associated PersistentVolumeClaim is retained and reattached to the newly created replacement Pod carrying the same ordinal, preserving access to previously written data despite the Pod object itself being entirely new.

Update Strategies

RollingUpdate With Ordinal Ordering

The default RollingUpdate strategy updates Pods in reverse ordinal order, tearing down and recreating the highest-numbered Pod first and proceeding downward, ensuring updates respect the same ordering discipline applied to scaling operations.

Partitioned Rollouts

The partition field allows a rolling update to be constrained so that only Pods with an ordinal greater than or equal to the partition value are updated, leaving lower-ordinal Pods untouched, a mechanism commonly used to stage or canary a change across a subset of replicas before committing to a full rollout.

PodManagementPolicy

OrderedReady as the Default

Under the default OrderedReady policy, the strict sequential creation and termination behavior described above is enforced, prioritizing predictability and safety for applications sensitive to ordering, such as those forming a cluster with leader election dependent on startup sequence.

Parallel Policy for Independent Replicas

The Parallel policy relaxes this constraint, allowing the controller to create or delete multiple Pods simultaneously without waiting for each to individually reach a ready or terminated state, appropriate for stateful applications whose replicas do not depend on strict startup ordering relative to one another.

Headless Service Requirement

Enabling Direct Pod Addressability

StatefulSets are typically paired with a headless Service, one configured without a cluster IP, which allows DNS queries against the Service name to resolve directly to the individual Pod IP addresses of its members, a prerequisite for the stable per-Pod network identity that distinguishes StatefulSet-managed workloads from stateless alternatives.