Mastering Kubernetes StatefulSet: Deploy, Scale, and Upgrade Stateful Apps

Introduction

Stateful applications require persistent disk storage, a stable network identifier for each instance, and deterministic rollout order—requirements that traditional Deployment cannot satisfy. Kubernetes addresses these needs with the StatefulSet controller, a workload designed for reliable stateful app management.

Key Requirements for Stateful Workloads

Persistent storage that survives pod restarts.

Each pod must have a unique, stable hostname and network ID.

Rollout and scaling must follow a defined order.

StatefulSet Overview

StatefulSet creates pods with an ordinal index (0, 1, 2, …). Each pod receives:

A stable hostname derived from the pod name.

A dedicated PersistentVolumeClaim (PVC) created from a volumeClaimTemplates section.

A unique network address that persists across upgrades.

Although originally intended for stateful services, many stateless workloads also benefit from these guarantees.

Example Manifest

A typical StatefulSet deployment includes a headless Service and a StatefulSet definition. The Service provides a stable DNS name, while the StatefulSet specifies the pod template, replica count, and PVC template.

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

Creating Resources

Apply the manifest with kubectl apply -f statefulset.yaml. Verify creation: kubectl get svc nginx – shows the headless Service. kubectl get sts nginx-web -o yaml – displays the StatefulSet status, including READY (e.g., 3/3). kubectl get pod -l app=nginx – lists the three pods (nginx-web-0, nginx-web-1, nginx-web-2) in Running state. kubectl get pvc – shows three PVCs named www-storage-nginx-web-0, www-storage-nginx-web-1, www-storage-nginx-web-2, each bound to a PV.

Pod and PVC Lifecycle

When a StatefulSet creates a pod, the corresponding PVC is created first. The pod then mounts its dedicated PVC. During an upgrade, the pod is deleted and a new pod with the same name is created, re‑using the existing PVC and network identity, so data persists across versions.

Upgrade Process

StatefulSet tracks pod templates via ControllerRevision objects. Updating the container image (e.g., kubectl set image statefulset/nginx-web nginx=nginx:mainline) creates a new ControllerRevision with a new hash. Pods are upgraded in reverse order (largest ordinal first). After the upgrade, controller-revision-hash on each pod reflects the new version.

Status Fields

currentReplica : number of pods running the current version.

currentRevision : hash of the current template.

updateReplicas : number of pods targeted for the new version.

updateRevision : hash of the new template.

When currentReplica equals updateReplicas and the two revision hashes match, the upgrade is complete.

Management Policies

The podManagementPolicy field controls scaling order:

OrderedReady (default): Pods are created and deleted sequentially; a new pod is created only after the previous one reaches Ready . Deletion proceeds in reverse order.

Parallel : Pods are created or deleted concurrently, without waiting for readiness.

If any earlier pod is NotReady , the controller pauses further creation under OrderedReady .

Update Strategies

Two strategies determine how pods are updated:

RollingUpdate : Pods are upgraded one by one (or in batches) according to the partition field.

OnDelete : Pods are only upgraded when they are manually deleted; the controller does not trigger automatic replacement.

The partition value specifies how many pods should remain on the old version during a rolling update. For example, with replicas: 10 and partition: 8, pods 0‑7 stay on the old version while pods 8‑9 are upgraded, enabling a gray‑scale rollout.

Scaling Behavior

When scaling from 1 to 3 replicas, the controller creates pods sequentially (0 → 1 → 2) under OrderedReady . With Parallel , all new pods can be created simultaneously.

Summary

StatefulSet is a core Kubernetes workload that provides ordered creation, stable network identities, and per‑pod persistent storage. It supports both stateful and certain stateless workloads, offers flexible update strategies (RollingUpdate with partition, OnDelete), and allows fine‑grained scaling policies, making it essential for reliable stateful application deployments.