What Is a StatefulSet?

Detailed Answer

A StatefulSet is a Kubernetes workload API object used to manage stateful applications. While Deployments treat Pods as interchangeable cattle, StatefulSets treat them as pets — each Pod gets a unique, stable identity that persists across rescheduling.

Why StatefulSets Exist

Many applications need guarantees that Deployments cannot provide:

• Stable network identity: A database replica needs a consistent hostname so peers can find it
• Stable persistent storage: Each replica needs its own volume that follows it across restarts
• Ordered operations: Clustered applications often require Pods to start and stop in a specific sequence

How a StatefulSet Works

When you create a StatefulSet, Kubernetes assigns each Pod an ordinal index starting from 0. Combined with the StatefulSet name, this creates predictable Pod names.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: mysql
spec:
  serviceName: "mysql"
  replicas: 3
  selector:
    matchLabels:
      app: mysql
  template:
    metadata:
      labels:
        app: mysql
    spec:
      containers:
        - name: mysql
          image: mysql:8.0
          ports:
            - containerPort: 3306
          env:
            - name: MYSQL_ROOT_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: mysql-secret
                  key: root-password
          volumeMounts:
            - name: data
              mountPath: /var/lib/mysql
          resources:
            requests:
              cpu: "500m"
              memory: "512Mi"
            limits:
              cpu: "1"
              memory: "1Gi"
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes: ["ReadWriteOnce"]
        storageClassName: "standard"
        resources:
          requests:
            storage: 10Gi

This creates three Pods: mysql-0, mysql-1, and mysql-2. Each Pod gets its own PersistentVolumeClaim named data-mysql-0, data-mysql-1, and data-mysql-2.

Stable Network Identity

StatefulSets require a Headless Service (a Service with clusterIP: None) to provide DNS entries for each Pod. Each Pod becomes addressable at:

<pod-name>.<service-name>.<namespace>.svc.cluster.local

For example, mysql-0.mysql.default.svc.cluster.local always resolves to the first Pod, regardless of which node it runs on.

Ordered Lifecycle

By default, StatefulSets create Pods sequentially — mysql-0 must be Running and Ready before mysql-1 is created. Termination happens in reverse order. This ordering ensures that primary replicas initialize before secondaries.

When Not to Use StatefulSets

If your application is stateless and does not need stable identities or persistent per-Pod storage, use a Deployment instead. StatefulSets add operational complexity — scaling is slower due to ordering, and PersistentVolumeClaims are not automatically deleted when you scale down.

Key Differences from Deployments

| Feature | Deployment | StatefulSet | |---|---|---| | Pod names | Random hash suffix | Ordinal index | | Storage | Shared or no PVC | Per-Pod PVC via volumeClaimTemplates | | Scaling | Parallel | Ordered (by default) | | Pod replacement | New random name | Same name, same PVC | | Headless Service | Optional | Required |