Deployments treat Pods as interchangeable cattle. But some workloads — databases, message queues, distributed consensus systems — need stable identity: a fixed name, persistent storage that follows the Pod, and ordered startup. That's what StatefulSets provide.

1. The Problem StatefulSets Solve

Consider a 3-node PostgreSQL cluster with streaming replication:

• Node 0 is the primary (accepts writes)
• Nodes 1 and 2 are replicas (read-only, stream WAL from primary)
• Each node has its own data directory (can't share storage)
• Replicas need to find the primary by a stable DNS name
• If a Pod restarts, it must get the same storage back

A Deployment can't do this. It gives Pods random names (web-8b2c-xk4j9), shares no identity across restarts, and provides no ordering guarantees.

StatefulSet Guarantees

2. StatefulSet Anatomy

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
spec:
  serviceName: postgres-headless    # ← REQUIRED: headless Service name
  replicas: 3
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
        - name: postgres
          image: postgres:16
          ports:
            - containerPort: 5432
          volumeMounts:
            - name: data
              mountPath: /var/lib/postgresql/data
          env:
            - name: PGDATA
              value: /var/lib/postgresql/data/pgdata
  volumeClaimTemplates:             # ← PVC per Pod
    - metadata:
        name: data
      spec:
        accessModes: ["ReadWriteOnce"]
        storageClassName: fast-ssd
        resources:
          requests:
            storage: 50Gi
  podManagementPolicy: OrderedReady # ← sequential (default)
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      partition: 0                  # ← for canary updates

Key Differences from Deployment

3. Stable Network Identity

Pod Naming

Pods are named {statefulset-name}-{ordinal}:

# StatefulSet "postgres" with replicas=3 creates:
postgres-0
postgres-1
postgres-2

# If postgres-1 dies, it's rescheduled as postgres-1 (same name, same PVC)

Headless Service & DNS

A headless Service (ClusterIP: None) is required. It doesn't load-balance — instead, it creates DNS records for each Pod individually:

# Headless Service definition:
apiVersion: v1
kind: Service
metadata:
  name: postgres-headless
spec:
  clusterIP: None           # ← This makes it headless
  selector:
    app: postgres
  ports:
    - port: 5432

DNS Records Created

# From any Pod in the cluster:
nslookup postgres-0.postgres-headless.default.svc.cluster.local
# → 10.244.1.5 (Pod IP — may change on reschedule, but DNS name stays)

# Replicas can find the primary by name:
# postgresql.conf: primary_conninfo = 'host=postgres-0.postgres-headless ...'

4. Persistent Storage — volumeClaimTemplates

The volumeClaimTemplates field creates a unique PVC for each Pod, named {template-name}-{statefulset-name}-{ordinal}:

# For StatefulSet "postgres" with volumeClaimTemplate named "data":
kubectl get pvc
# NAME              STATUS   VOLUME         CAPACITY   STORAGECLASS
# data-postgres-0   Bound    pv-abc123      50Gi       fast-ssd
# data-postgres-1   Bound    pv-def456      50Gi       fast-ssd
# data-postgres-2   Bound    pv-ghi789      50Gi       fast-ssd

Storage Lifecycle

PVC Retention Policy (K8s 1.27+)

# New: control PVC lifecycle explicitly
spec:
  persistentVolumeClaimRetentionPolicy:
    whenDeleted: Delete    # Delete PVCs when STS is deleted
    whenScaled: Retain     # Keep PVCs when scaling down (default)

5. Ordered Operations

podManagementPolicy: OrderedReady (default)

Why? Many distributed systems require this:

• A primary (index 0) must start first before replicas can connect
• Shutting down the primary last ensures failover happens cleanly
• Rolling updates from highest ordinal first = update replicas before primary

podManagementPolicy: Parallel

All Pods start/stop simultaneously — no ordering. Use when Pods are independent (e.g., each is a standalone cache shard that doesn't need to discover peers at startup).

spec:
  podManagementPolicy: Parallel
  # All Pods created at once during scale-up
  # Faster, but no startup ordering guarantee

6. Update Strategies

RollingUpdate (default)

Updates Pods in reverse ordinal order (highest first): 2 → 1 → 0. Each Pod must become Ready before the next is updated.

Partition — Canary Updates

The partition parameter is powerful: only Pods with ordinal ≥ partition are updated. Pods below the partition keep the old version.

spec:
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      partition: 2    # Only postgres-2 gets the new version

# After verifying postgres-2 is healthy:
# Set partition: 1 → updates postgres-2, postgres-1
# Set partition: 0 → updates all (full rollout)

OnDelete Strategy

spec:
  updateStrategy:
    type: OnDelete
  # Pods are NOT automatically updated
  # You must manually delete each Pod to trigger an update
  # Gives maximum control for critical stateful workloads

7. When to Use StatefulSets vs Deployments

Summary