StatefulSet ordering and naming in Kubernetes - Commands & Configuration

Introduction

When you run multiple copies of an app that need stable names and order, StatefulSet helps. It creates pods with unique names and starts or stops them one by one in order.

When you need to run a database cluster where each node must keep its identity.

When you want to deploy an app that requires stable network IDs for each instance.

When pods must start or stop in a specific order to avoid errors.

When you want to keep data on each pod even if it restarts or moves.

When you need predictable pod names for easier management and monitoring.

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
  template:
    metadata:
      labels:
        app: example
    spec:
      containers:
      - name: example-container
        image: nginx:1.23.3
        ports:
        - containerPort: 80
  volumeClaimTemplates:
  - metadata:
      name: example-storage
    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 and labels.

volumeClaimTemplates: Creates persistent storage for each pod with unique names.

Commands

Create the StatefulSet with 3 pods, each with stable names and storage.

Terminal

kubectl apply -f statefulset.yaml

Expected Output

statefulset.apps/example-statefulset created

Check the pods created by the StatefulSet and see their stable names.

Terminal

kubectl get pods -l app=example

Expected Output

NAME                    READY   STATUS    RESTARTS   AGE

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

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

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

→

-l - Filter pods by label to show only those managed by the StatefulSet

Delete pod 1 to see how StatefulSet recreates it with the same name and storage.

Terminal

kubectl delete pod example-statefulset-1

Expected Output

pod "example-statefulset-1" deleted

Verify the pod example-statefulset-1 is recreated with the same name.

Terminal

kubectl get pods -l app=example

Expected Output

NAME                    READY   STATUS    RESTARTS   AGE

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

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

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

→

-l - Filter pods by label to show only those managed by the StatefulSet

Key Concept

StatefulSet ensures pods have stable, unique names and start or stop in order, keeping their storage intact.

Common Mistakes

Deleting pods manually and expecting new pods to have random names.

StatefulSet always recreates pods with the same stable names, so names are predictable, not random.

Understand that pod names include an ordinal index and are stable for each replica.

Using a Deployment instead of StatefulSet for apps needing stable storage and names.

Deployments create pods with random names and do not guarantee stable storage per pod.

Use StatefulSet when you need stable network IDs and persistent storage per pod.

Not defining volumeClaimTemplates, so pods share storage or lose data on restart.

Without volumeClaimTemplates, pods do not get unique persistent volumes, risking data loss.

Always define volumeClaimTemplates in StatefulSet to give each pod its own persistent storage.

Summary

Apply a StatefulSet YAML to create pods with stable names and storage.

Use labels to list pods and see their predictable names with ordinal numbers.

Deleting a pod causes StatefulSet to recreate it with the same name and storage.

StatefulSet manages pod startup and shutdown order to keep app consistency.