Kubernetes StatefulSet Storage Management

Kubernetes StatefulSet Storage Management is the practice of provisioning, retaining, resizing, and eventually reclaiming the per-ordinal PersistentVolumeClaims a StatefulSet creates through its volumeClaimTemplates, covering the full storage lifecycle from initial binding through the deliberate cleanup decisions that Kubernetes leaves entirely to the operator by default.

Storage Class Selection

Matching Provisioning Characteristics to Workload Needs

Each entry in volumeClaimTemplates specifies a storageClassName determining the underlying provisioner, IOPS characteristics, and availability zone binding behavior; storage management practice selects this deliberately based on the stateful workload's actual I/O profile rather than defaulting to whatever the cluster's default StorageClass happens to be.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: storage-management-example
spec:
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        storageClassName: high-iops-ssd
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 100Gi

The Retain-by-Default Behavior

Why Claims Survive Pod and Even StatefulSet Deletion

By default, PersistentVolumeClaims created through volumeClaimTemplates are retained even when their owning Pod is deleted, and even when the entire StatefulSet is deleted, a deliberate safety default preventing accidental data loss from a routine scaling or teardown operation.

kubectl delete statefulset storage-management-example
kubectl get pvc -l app=web

data-storage-management-example-0   Bound   pvc-abc123   100Gi
data-storage-management-example-1   Bound   pvc-def456   100Gi

Configurable Retention Policy

whenDeleted and whenScaled

The persistentVolumeClaimRetentionPolicy field allows overriding the default retain behavior separately for two distinct events: whenDeleted governs claim behavior when the StatefulSet itself is deleted, and whenScaled governs claim behavior specifically when scaling down removes an ordinal, each independently settable to Retain or Delete.

spec:
  persistentVolumeClaimRetentionPolicy:
    whenDeleted: Retain
    whenScaled: Delete

Choosing Policy Based on Data Lifecycle Intent

This configuration above retains data if the whole StatefulSet is removed (protecting against accidental full teardown) while automatically cleaning up claims for ordinals removed through routine scale-down (avoiding orphaned storage accumulation from normal capacity adjustments).

Manual Cleanup Under the Default Policy

Explicit Deletion Required

Under the default retain-everything behavior, storage management practice includes an explicit cleanup step whenever data is genuinely meant to be discarded, verifying which claims are safe to remove before issuing deletion, since Kubernetes provides no automatic signal distinguishing "scaled down intentionally, data no longer needed" from "scaled down temporarily, data still valuable."

kubectl delete pvc data-storage-management-example-4

Volume Expansion for Growing Storage Needs

Resizing Without Recreating

Where the underlying StorageClass supports it, existing claims can be resized in place by patching the claim's requested storage upward, avoiding the need to provision new storage and migrate data manually for a workload that has simply outgrown its original allocation.

kubectl patch pvc data-storage-management-example-0 -p '{"spec":{"resources":{"requests":{"storage":"200Gi"}}}}'

Container Restart Requirement for Filesystem Expansion

Depending on the storage driver, the filesystem expansion to actually use the newly available capacity may require the Pod to restart, meaning volume expansion in practice often couples with a coordinated Pod recreation rather than being fully transparent.

Storage Management Diagram

Treating storage as a resource with its own explicit lifecycle policy, separate from and outliving the Pods that use it by default, is the central discipline of StatefulSet storage management, since the cost of getting retention policy wrong ranges from wasted capacity to genuine, unrecoverable data loss.