StatefulSets Explained
A StatefulSet is the workload controller for applications that need stable, unique identities and stable storage across restarts — databases, message brokers, and other clustered systems. Unlike a Deployment's interchangeable pods, each StatefulSet pod gets a persistent ordinal name like postgres-0, postgres-1, and its own PersistentVolumeClaim that survives pod rescheduling, so the pod always reattaches to the same data.
Cricket analogy: Like permanently assigned batting positions in a Test lineup — the number 3 batter is always the same designated player with the same role and history, not an interchangeable slot filled by whoever is available that day.
Stable Identity and Headless Services
StatefulSets are paired with a headless Service (clusterIP: None), which gives each pod its own resolvable DNS name in the form <pod-name>.<service-name>.<namespace>.svc.cluster.local instead of a single load-balanced virtual IP. This lets clients or peer pods address a specific member directly — essential for systems like etcd or Cassandra where nodes must discover and talk to specific peers, not a random one.
Cricket analogy: Like a stadium's public address system announcing each fielder by their specific name and position rather than a generic 'a fielder' — the captain can direct instructions to 'Jadeja at deep mid-wicket' specifically, not just any fielder.
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: postgres
spec:
serviceName: postgres-headless
replicas: 3
podManagementPolicy: OrderedReady
selector:
matchLabels:
app: postgres
template:
metadata:
labels:
app: postgres
spec:
containers:
- name: postgres
image: postgres:16.2
ports:
- containerPort: 5432
volumeMounts:
- name: data
mountPath: /var/lib/postgresql/data
volumeClaimTemplates:
- metadata:
name: data
spec:
accessModes: ["ReadWriteOnce"]
storageClassName: fast-ssd
resources:
requests:
storage: 50GiOrdered Deployment, Scaling, and Termination
By default (podManagementPolicy: OrderedReady), StatefulSet pods are created, scaled, and terminated strictly in order: pod-0 must become Ready before pod-1 is created, and on scale-down the highest ordinal terminates first. This matters for systems with bootstrap dependencies, such as a database primary that must exist before replicas start streaming from it. Setting podManagementPolicy to Parallel drops this ordering guarantee to speed up operations when order genuinely doesn't matter.
Cricket analogy: Like a batting order where number 4 cannot walk in until number 3 is either out or the innings situation calls for them — the sequence is enforced, unlike a T10 exhibition where any batter can come in any order.
Set podManagementPolicy: Parallel when your application doesn't require strict startup ordering — for example, stateless-per-shard workers with independent storage — to cut scaling time significantly, since all pods launch concurrently instead of one at a time.
Storage and Update Strategies
Each replica's volumeClaimTemplates entry provisions a dedicated PersistentVolumeClaim named <template>-<pod-name>, which is not deleted when the pod or even the whole StatefulSet is deleted — it persists until you remove it explicitly. For updates, StatefulSets support RollingUpdate with an optional partition field: setting partition: 2 on a 5-replica set updates only pods with ordinal >= 2, letting you canary-test an update on the highest-numbered replicas first.
Cricket analogy: Like a player's personal kit bag staying in the team dressing room even after that player is dropped from the squad for a match — the gear persists independently of the player's current selection status.
PersistentVolumeClaims created via volumeClaimTemplates are never garbage-collected automatically when you scale down or delete a StatefulSet. Orphaned PVCs silently continue consuming storage quota and cost — always audit and manually delete them during cleanup.
- StatefulSets give pods stable ordinal names and dedicated PersistentVolumeClaims that survive rescheduling.
- A headless Service (clusterIP: None) provides per-pod DNS names for direct peer addressing.
- OrderedReady (default) creates/terminates pods sequentially; Parallel drops that guarantee for speed.
- volumeClaimTemplates provisions one PVC per replica, named <template>-<pod-ordinal>.
- The partition field in RollingUpdate lets you canary-update only the highest-ordinal pods first.
- PVCs are never auto-deleted when a StatefulSet or its pods are removed — manual cleanup is required.
- StatefulSets are the right tool for databases, brokers, and any clustered system needing stable identity.
Practice what you learned
1. What distinguishes a StatefulSet pod's name from a Deployment pod's name?
2. What is the purpose of a headless Service in a StatefulSet?
3. What happens to PersistentVolumeClaims created via volumeClaimTemplates when a StatefulSet is deleted?
4. What does setting RollingUpdate partition: 3 on a 5-replica StatefulSet do?
5. When should you set podManagementPolicy to Parallel instead of the default?
Was this page helpful?
You May Also Like
Deployments In Depth
How Kubernetes Deployments manage ReplicaSets to deliver declarative rolling updates, rollbacks, and self-healing for stateless workloads.
Pod Disruption Budgets
How PodDisruptionBudgets protect application availability during voluntary disruptions like node drains, upgrades, and cluster autoscaler actions.
DaemonSets Explained
How DaemonSets guarantee exactly one pod per matching node for node-level infrastructure like log collectors, monitoring agents, and CNI plugins.