Stateful workload — the cluster's data layer

A StatefulSet buys three guarantees a Deployment does not offer: each Pod keeps its ordinal identity across restarts, each keeps the same PVC, and each is individually addressable by DNS through a headless Service. Those guarantees have costs that surface later — the rollout is ordered, so a single Pod that never reaches Ready halts it at that ordinal and leaves the set half-upgraded, and the PVCs outlive the StatefulSet by default, so deleting and reapplying it quietly rebinds the old data. This lesson covers wiring the four objects together and the retention behaviour that decides what survives a delete.

The stateful workload

The stateful workload is the cluster’s data layer. The stateful workload is composed of:

• StatefulSet. The cluster’s stateful workload.
• PVC (volumeClaimTemplates). The cluster’s persistent storage.
• Headless Service. The cluster’s DNS for the Pods.
• Init containers. The cluster’s startup logic.
• Readiness probes. The cluster’s readiness check.

flowchart TB
    subgraph WS["Stateful Workload"]
        SS["StatefulSet"]
        VCT["volumeClaimTemplates"]
        PVC1["PVC-0"]
        PVC2["PVC-1"]
        PVC3["PVC-2"]
        HS["Headless Service"]
        POD1["Pod-0"]
        POD2["Pod-1"]
        POD3["Pod-2"]
    end
    SS --> POD1
    SS --> POD2
    SS --> POD3
    POD1 --> PVC1
    POD2 --> PVC2
    POD3 --> PVC3
    VCT --> PVC1
    VCT --> PVC2
    VCT --> PVC3
    SS --> HS
    HS --> POD1
    HS --> POD2
    HS --> POD3

The stateful workload is the cluster’s data layer.

The StatefulSet

The StatefulSet is the cluster’s stateful workload. The StatefulSet is composed of:

• replicas. The number of replicas.
• selector. The selector for the Pods.
• template. The Pod template.
• volumeClaimTemplates. The PVC template.
• serviceName. The headless Service name.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
spec:
  replicas: 3
  serviceName: postgres
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
      - name: postgres
        image: postgres:15
  volumeClaimTemplates:
  - metadata:
      name: data
    spec:
      accessModes: [ReadWriteOnce]
      storageClassName: fast-ssd
      resources:
        requests:
          storage: 100Gi

The StatefulSet is the cluster’s stateful workload.

The PVC

The PVC is the cluster’s persistent storage. The PVC is created by the StatefulSet’s volumeClaimTemplates.

flowchart LR
    A[StatefulSet] --> B[volumeClaimTemplates]
    B --> C[PVC-0]
    B --> D[PVC-1]
    B --> E[PVC-2]

The PVC is the cluster’s persistent storage.

The headless Service

The headless Service is the cluster’s DNS for the Pods. The headless Service has clusterIP: None.

apiVersion: v1
kind: Service
metadata:
  name: postgres
spec:
  clusterIP: None
  selector:
    app: postgres
  ports:
  - port: 5432

The headless Service is the cluster’s DNS for the Pods.

The deployment

The deployment is the canonical stateful workload deployment:

# Substitute your own namespace:
NS=data

# 1. Apply the headless Service
kubectl apply -f headless-service.yaml

# 2. Apply the StatefulSet
kubectl apply -f statefulset.yaml

# 3. Verify the StatefulSet
kubectl get statefulset -n "$NS"

# 4. Verify the PVCs
kubectl get pvc -n "$NS"

The deployment is the stateful workload.

The production discipline

The stateful workload is the cluster’s hypothesis. The discipline is to walk the 11-step methodology applied to the stateful workload, identify the cause, apply the remediation. The cluster’s discipline is the same scale-free: every component is justified.

Quiz

Production discipline

• Walk the 11-step methodology. The methodology is the diagnostic.
• Identify the gaps. The gaps are the cluster’s missing components.
• Deploy the stateful workload. The deployment is the cluster’s recovery.
• Verify the StatefulSet. The verification is the cluster’s evidence.
• Document the stateful workload. The runbook is the cluster’s reference.