StatefulSets

A StatefulSet runs Pods that need stable identity and their own persistent storage — databases, message queues, and clustered systems where the replicas are not interchangeable. Where a Deployment's Pods are anonymous and disposable, a StatefulSet's Pods are named, ordered, and each keep their own disk.

It is the right tool for stateful workloads and the wrong tool for almost everything else. Most applications should be stateless Deployments backed by an external or managed data store; a StatefulSet is for when the state genuinely lives in the Pods.

Stable Identity

StatefulSet Pods get stable, predictable names — db-0, db-1, db-2 — that persist across rescheduling. Paired with a headless Service, each Pod also gets a stable DNS name, so db-0 is always reachable at the same address even after it restarts on a new node. Clustered systems rely on this: a database replica needs to know it is replica 0 and find replica 1 at a fixed name.

Per-Pod Storage

A StatefulSet uses volumeClaimTemplates to give each Pod its own PersistentVolumeClaim. db-0 gets its own disk, db-1 another, and that disk follows the Pod identity — when db-0 reschedules, it reattaches its own volume, not a fresh one. This per-replica persistence is the core of what a StatefulSet provides and what a Deployment cannot.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: db
spec:
  serviceName: db          # the headless Service
  replicas: 3
  selector:
    matchLabels:
      app: db
  template:
    metadata:
      labels:
        app: db
    spec:
      containers:
        - name: db
          image: postgres:17
          volumeMounts:
            - name: data
              mountPath: /var/lib/postgresql/data
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 20Gi

Ordered Operations

StatefulSets deploy, scale, and update in order. Pods are created 0, 1, 2 and each waits for the previous to be ready; they are removed in reverse. Updates roll one Pod at a time, and a partition in the update strategy lets you stage a rollout to only the highest-numbered Pods — useful for canarying a database upgrade. This ordering is deliberate: clustered systems often require a stable bootstrap sequence.

When Not to Use One

A StatefulSet is not a database — it is scaffolding for running one. It does not handle replication, failover, or backups; your software or an operator must. For most teams the better answer to "we need a database" is a managed service or an operator (Topic 39), not a hand-rolled StatefulSet. And note that scaling down does not delete the PersistentVolumeClaims by default — the data is kept on purpose, which surprises people expecting cleanup.