How to Create StatefulSet in Kubernetes: Syntax and Example

To create a StatefulSet in Kubernetes, define a YAML manifest specifying the apiVersion, kind: StatefulSet, metadata, and a spec with a selector, serviceName, replicas, and template for pod specs. Apply this manifest using kubectl apply -f filename.yaml to deploy stateful pods with stable network IDs and persistent storage.

Syntax

A StatefulSet manifest includes these main parts:

• apiVersion: Kubernetes API version, usually apps/v1.
• kind: Must be StatefulSet.
• metadata: Name and labels for the StatefulSet.
• spec: Defines the desired state including:
• serviceName: Headless service managing network IDs.
• replicas: Number of pod replicas.
• selector: Label selector to match pods.
• template: Pod template with containers and volumes.
• volumeClaimTemplates: Defines persistent storage for each pod.

yaml

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: example-statefulset
spec:
  serviceName: "example-service"
  replicas: 3
  selector:
    matchLabels:
      app: example
  template:
    metadata:
      labels:
        app: example
    spec:
      containers:
      - name: example-container
        image: nginx:1.21
        ports:
        - containerPort: 80
  volumeClaimTemplates:
  - metadata:
      name: example-storage
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 1Gi

Example

This example creates a StatefulSet named web with 3 replicas running nginx. Each pod gets a stable network ID and a 1Gi persistent volume.

yaml

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

Output

statefulset.apps/web created

Common Pitfalls

• Not creating a headless service (serviceName) before the StatefulSet causes network identity issues.
• Incorrect selector labels that don't match pod labels prevent pods from being managed.
• Omitting volumeClaimTemplates means pods won't have persistent storage, losing data on restart.
• Using Deployment instead of StatefulSet for stateful apps loses stable network and storage guarantees.

yaml

### Wrong: Missing serviceName
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: wrong-example
spec:
  replicas: 2
  selector:
    matchLabels:
      app: wrong
  template:
    metadata:
      labels:
        app: wrong
    spec:
      containers:
      - name: app
        image: nginx

### Right: Add serviceName and matching labels
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: right-example
spec:
  serviceName: "right-service"
  replicas: 2
  selector:
    matchLabels:
      app: right
  template:
    metadata:
      labels:
        app: right
    spec:
      containers:
      - name: app
        image: nginx

Quick Reference

Remember these key points when creating a StatefulSet:

• serviceName must point to a headless service.
• replicas defines how many pods run.
• selector and pod labels must match exactly.
• volumeClaimTemplates provide persistent storage per pod.
• Use kubectl apply -f yourfile.yaml to create or update.

Key Takeaways

A StatefulSet manages pods with stable network IDs and persistent storage.

Always define a headless service and matching selectors for StatefulSets.

Use volumeClaimTemplates to ensure each pod has its own persistent volume.

Apply the YAML manifest with kubectl to create the StatefulSet in your cluster.

Avoid using Deployments for stateful applications needing stable identity and storage.