StatefulSets for stateful applications in Kubernetes - Commands & Configuration

Introduction

StatefulSets help run applications that need to keep data or identity even if restarted. They make sure each app copy has its own storage and name, so data is safe and consistent.

When running a database that needs to keep its data even if the pod restarts or moves.

When deploying a messaging system like Kafka that requires stable network IDs.

When you want to run multiple copies of an app but each needs its own storage.

When you need to upgrade apps one by one without losing data or connections.

When you want to keep the order of app startup and shutdown for proper coordination.

Config File - statefulset.yaml

statefulset.yaml

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

serviceName: Links pods to a headless service for stable network IDs.

replicas: Number of pod copies to run.

selector: Matches pods managed by this StatefulSet.

template: Defines pod content like containers and labels.

volumeClaimTemplates: Creates persistent storage for each pod copy.

Commands

This command creates the StatefulSet and its pods with persistent storage as defined in the YAML file.

Terminal

kubectl apply -f statefulset.yaml

Expected Output

statefulset.apps/example-statefulset created

This command lists all pods created by the StatefulSet to verify they are running.

Terminal

kubectl get pods -l app=example-app

Expected Output

NAME                 READY   STATUS    RESTARTS   AGE

example-statefulset-0 1/1     Running   0          30s

example-statefulset-1 1/1     Running   0          25s

example-statefulset-2 1/1     Running   0          20s

→

-l app=example-app - Filters pods by label to show only those managed by the StatefulSet

This command shows detailed information about the first pod, including its storage and network identity.

Terminal

kubectl describe pod example-statefulset-0

Expected Output

Name:           example-statefulset-0

Namespace:      default

Priority:       0

Node:           node-1/192.168.1.10

Start Time:     Thu, 01 Jun 2024 10:00:00 +0000

Labels:         app=example-app

Annotations:    <none>

Status:         Running

IP:             10.244.1.10

Containers:

  example-container:

    Image:      nginx:1.23.3

    Port:       80/TCP

    Mounts:

      /usr/share/nginx/html from data (rw)

Volumes:

  data:

    Type:       PersistentVolumeClaim (a reference to a PVC in the same namespace)

    ClaimName:  data-example-statefulset-0

    ReadOnly:   false

Key Concept

StatefulSets give each pod a stable name and storage so stateful apps keep their data and identity across restarts.

Common Mistakes

Using a Deployment instead of a StatefulSet for stateful apps

Deployments do not provide stable network IDs or persistent storage per pod, causing data loss or conflicts.

Use StatefulSet to ensure each pod has its own persistent volume and stable identity.

Not creating a headless service matching the StatefulSet's serviceName

Without the headless service, pods won't get stable network identities needed for stateful communication.

Create a headless service with the same name as serviceName in the StatefulSet spec.

Sharing a single PersistentVolumeClaim among all pods

All pods would write to the same storage, causing data corruption and conflicts.

Use volumeClaimTemplates to create separate PersistentVolumeClaims for each pod.

Summary

Create a StatefulSet YAML with volumeClaimTemplates for persistent storage per pod.

Apply the StatefulSet with kubectl apply and verify pods with kubectl get pods.

Use kubectl describe pod to check each pod's storage and network identity.