StatefulSet

Stateful applications such as Kafka, PostgreSQL, Elasticsearch and Redis clusters need stable network identity and persistent storage. A Deployment would replace a failed pod with a new, interchangeable one, which breaks cluster membership. A StatefulSet guarantees identity instead.

How it works

Each pod gets an ordinal index, so pods are named web-0, web-1 and so on, and that identity survives rescheduling. A StatefulSet requires a headless Service, which you must create yourself, to provide stable DNS names for the pods. Storage comes from volumeClaimTemplates, which create a separate PersistentVolumeClaim for each pod, provided the StorageClass supports dynamic provisioning or matching volumes already exist.

By default pods are created in order and each must be Running and Ready before the next starts, and they are removed in reverse order. Setting podManagementPolicy: Parallel removes that ordering. Updates default to RollingUpdate, which proceeds in reverse ordinal order, and a partition value allows staged rollouts. Deleting or scaling down a StatefulSet does not delete its volumes by default.

A practical example

apiVersion: v1
kind: Service
metadata:
  name: nginx
spec:
  clusterIP: None
  selector:
    app: nginx
  ports: [{port: 80, name: web}]
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: web
spec:
  serviceName: "nginx"
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers: [{name: nginx, image: "registry.k8s.io/nginx-slim:0.24", volumeMounts: [{name: www, mountPath: /usr/share/nginx/html}]}]
  volumeClaimTemplates: [{metadata: {name: www}, spec: {accessModes: [ReadWriteOnce], resources: {requests: {storage: 1Gi}}}}]

This creates web-0, web-1 and web-2, each with its own 1Gi volume. Each pod is reachable at a stable DNS name such as web-0.nginx, so peers can find one another after a restart. The Kubernetes documentation recommends ReadWriteOncePod rather than ReadWriteOnce for production use.

Common mistakes

• Forgetting the headless Service, or naming it differently from serviceName.
• Assuming deleting the StatefulSet removes the data. Volumes are kept, which protects data but can leave orphaned storage and cost.
• Running a single replica and expecting high availability.
• Ignoring that a failed rolling update with ordered management can need manual repair.
• Skipping backups because storage is persistent. Persistence is not a backup.

When to use it and when not to

Use a StatefulSet when each replica needs its own identity or its own volume, typically for clustered databases and brokers. For stateless services use a Deployment. For databases, consider a managed service such as RDS before taking on the operational burden, or use a Kubernetes operator that encodes the operational knowledge. Our Kubernetes consulting team can help assess the trade-offs.

See also

• DaemonSet
• Persistent Volume
• Kubernetes Operator
• Pod Disruption Budget
• Kubernetes