StatefulSet Fundamentals

A StatefulSet manifest looks similar to a Deployment with a few critical additions. The most important is serviceName: the name of a headless Service that provides stable DNS for each Pod. Without this Service, the stable hostname guarantee cannot be fulfilled.

nano web-statefulset.yaml

apiVersion: v1
kind: Service
metadata:
  name: web-headless
  labels:
    app: web
spec:
  clusterIP: None
  selector:
    app: web
  ports:
    - port: 80
      name: web
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: web
spec:
  serviceName: web-headless
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: busybox:1.36
          command: ['sh', '-c', 'echo "pod: $HOSTNAME" && sleep 3600']

kubectl apply -f web-statefulset.yaml

Observing ordered startup

kubectl get pods --watch

Watch the Pods appear in order: web-0 starts and becomes Running before web-1 starts, and web-1 runs before web-2 starts. This ordered startup is a core StatefulSet guarantee.

Stop the watch with Ctrl+C. Check the final state:

kubectl get pods -l app=web

All three Pods are named web-0, web-1, web-2. The ordinal suffix is the stable identity.

The HOSTNAME environment variable

kubectl exec web-0 -- sh -c 'echo $HOSTNAME'
kubectl exec web-1 -- sh -c 'echo $HOSTNAME'

Each Pod’s HOSTNAME is set to its stable name: web-0, web-1. Applications running inside the Pod can use $HOSTNAME to know their own identity, which is critical for distributed systems where each instance needs a unique ID (node ID in a Kafka broker, replica ID in MongoDB).

The serviceName field

serviceName must match an existing headless Service (one with clusterIP: None). The headless Service is what creates DNS entries for each Pod.

Without the headless Service, the StatefulSet still creates Pods with stable names, but there are no stable DNS names for other workloads to reach them. Headless Services are covered in detail in the next lesson.

kubectl describe statefulset web

Look at the Service Name field. It shows web-headless. The Events section shows the ordered creation of each Pod.

Scaling a StatefulSet

kubectl scale statefulset web --replicas=5
kubectl get pods --watch

Pods are added in order: web-3 then web-4. Similarly, scaling down removes the highest-ordinal Pod first: web-4 is deleted, then web-3.

kubectl scale statefulset web --replicas=3

The serviceName field, stable Pod names, and ordered lifecycle are the three mechanics that distinguish a StatefulSet from a Deployment. The next lesson covers headless Services and the DNS that makes stable addressing possible.