What is StatefulSet in Kubernetes: Explained with Example

StatefulSet in Kubernetes is a controller that manages stateful applications by providing stable, unique network IDs and persistent storage for each pod. It ensures pods are created, deleted, and scaled in order, maintaining their identity and storage across restarts.

How It Works

A StatefulSet works like a manager for pods that need to remember their identity and data. Imagine you have a row of mailboxes, each with a fixed number and address. Even if you replace a mailbox, it keeps the same number and location. Similarly, each pod in a StatefulSet gets a unique name and stable storage that stays the same even if the pod restarts or moves.

Unlike regular pods that are interchangeable, StatefulSet pods start and stop in a specific order. This helps applications like databases that need to start carefully and keep their data safe. The controller also keeps track of the pods’ network names, so other parts of the system can always find them reliably.

Example

This example shows a simple StatefulSet for a web application with three replicas. Each pod will have a unique name and persistent storage.

yaml

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: web
spec:
  serviceName: "web"
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
      - name: nginx
        image: nginx:1.21
        ports:
        - containerPort: 80
        volumeMounts:
        - name: www
          mountPath: /usr/share/nginx/html
  volumeClaimTemplates:
  - metadata:
      name: www
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 1Gi

Output

kubectl get pods
NAME      READY   STATUS    RESTARTS   AGE
web-0     1/1     Running   0          1m
web-1     1/1     Running   0          1m
web-2     1/1     Running   0          1m

When to Use

Use StatefulSet when you need pods with stable identities and persistent storage. This is important for databases like MySQL, MongoDB, or Cassandra, where each pod stores unique data and must keep its name for replication and recovery.

Also use StatefulSet for applications that require ordered deployment and scaling, such as clustered services or distributed systems that depend on pod identity and stable network addresses.

Key Points

• Stable network IDs: Each pod gets a unique, consistent name.
• Persistent storage: Storage volumes stick to pods even after restarts.
• Ordered deployment: Pods start and stop in a defined sequence.
• Use cases: Stateful apps like databases and clustered services.

Key Takeaways

StatefulSet manages pods with stable identities and persistent storage in Kubernetes.

It ensures pods start, stop, and scale in order, preserving their data and network names.

Use StatefulSet for stateful applications like databases and clustered services.

Each pod in a StatefulSet has a unique name and stable storage volume.

StatefulSet is essential when pod identity and data persistence matter.