Kubernetes StatefulSet Controller

Kubernetes StatefulSet Controller is the control loop responsible for managing Pods that require stable, unique identity, stable network naming, and stable per-instance storage across restarts and rescheduling, in direct contrast to the interchangeable, identity-agnostic Pods a ReplicaSet manages. It is the workload controller of choice for databases, message queues, and any application where "which specific instance this is" matters as much as how many instances exist.

Ordinal-Based Identity

Predictable Naming

Each Pod created by a StatefulSet receives a name formed from the StatefulSet's name and a zero-based ordinal index, web-0, web-1, web-2, rather than a randomly generated suffix. This name is stable for the life of that ordinal slot: if web-1 is deleted, its replacement is also named web-1, not a new randomly suffixed name.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: web
spec:
  serviceName: web-headless
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: app
          image: registry.example.com/app:1.0.0

Stable Network Identity

Paired with a headless Service (clusterIP: None), each Pod receives a predictable DNS entry of the form <pod-name>.<service-name>.<namespace>.svc.cluster.local, allowing other components to address a specific ordinal directly rather than through arbitrary load-balanced selection.

Ordered Pod Management

Sequential Creation and Deletion

By default (podManagementPolicy: OrderedReady), the controller creates Pods in strict ascending ordinal order, waiting for each to become Ready before starting the next, and deletes them in descending order, waiting for each termination to complete before proceeding to the previous ordinal.

spec:
  podManagementPolicy: OrderedReady

Parallel Alternative

Setting podManagementPolicy: Parallel relaxes this ordering, allowing the controller to launch or terminate all Pods simultaneously, appropriate for stateful applications whose instances do not depend on each other's startup sequence.

Per-Pod Persistent Storage

volumeClaimTemplates

A StatefulSet defines volumeClaimTemplates rather than a shared volumes entry, causing the controller to provision one distinct PersistentVolumeClaim per ordinal, named to match, data-web-0, data-web-1, and to reattach that same claim to the corresponding Pod whenever it is replaced.

spec:
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi

Storage Survives Pod Deletion

Deleting a StatefulSet Pod does not delete its associated PersistentVolumeClaim; the claim persists so that a replacement Pod at the same ordinal reattaches to the same underlying data, a deliberate difference from the ephemeral-by-default storage model of a ReplicaSet.

Update Strategy

Rolling Update in Reverse Ordinal Order

When the Pod template changes, the StatefulSet controller replaces Pods one at a time in descending ordinal order by default, waiting for each replacement to become ready before proceeding to the next lower ordinal.

spec:
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      partition: 0

Partitioned Updates

The partition field restricts the rolling update to ordinals greater than or equal to its value, leaving lower ordinals untouched, a mechanism commonly used for canary-style validation of a subset of stateful replicas before committing to a full rollout.

StatefulSet Controller Diagram

This combination of ordinal identity, stable networking, and per-instance storage is what makes StatefulSets suitable for exactly the class of workloads a ReplicaSet cannot serve: distributed systems where each member must be individually addressable and reconnect to its own persistent state after any restart.