A Kubernetes workload API object that manages stateful applications by assigning each pod a stable, unique network identity and persistent storage, with ordered deployment and scaling.

What is StatefulSet? Definition, examples and how it works

A StatefulSet is a Kubernetes controller designed for stateful applications that require stable, unique network identifiers, ordered startup and shutdown, and persistent storage per pod. Unlike a Deployment, which treats pods as interchangeable, a StatefulSet assigns each pod a deterministic ordinal index (for example, web-0, web-1, web-2) and a hostname that persists across rescheduling. This makes it the standard choice for databases, message queues, and clustered systems where pod identity and data durability matter.

When you create a StatefulSet, it uses a Headless Service (a Service with clusterIP: None) to control the network domain for each pod. Each pod gets a DNS name like pod-name.service-name.namespace.svc.cluster.local, which remains stable even if the pod is deleted and recreated. The controller deploys pods in order from index 0 to N, waiting for each pod to become ready before starting the next. Scaling down reverses this order, terminating the highest-index pod first. This ordered behavior is critical for systems like Apache ZooKeeper or etcd, where quorum and leader election depend on predictable pod identities.

StatefulSets also support volumeClaimTemplates, which automatically create a PersistentVolumeClaim for each pod replica. When a pod is rescheduled to a new node, it reattaches to the same persistent volume, preserving its data. This combination of stable identity, ordered lifecycle, and per-pod storage makes StatefulSets the appropriate workload object for any application that cannot tolerate the ephemeral, interchangeable nature of Deployments. As of Kubernetes 1.27, StatefulSets remain a stable GA feature, though they require careful planning for backup, recovery, and scaling operations.

Key facts

Each pod in a StatefulSet gets a stable ordinal index and hostname that persists across rescheduling.
StatefulSets require a Headless Service to control the network identity of each pod.
Deployment and scaling are ordered: pods start from index 0 and terminate from the highest index.
volumeClaimTemplates automatically provision a PersistentVolumeClaim per pod replica.
StatefulSets are the recommended workload for databases, message queues, and clustered systems in Kubernetes.

How it works in practice

A three-node Cassandra cluster is deployed as a StatefulSet named cassandra. The pods become cassandra-0, cassandra-1, and cassandra-2. Each pod mounts its own PersistentVolume for data storage. When cassandra-1 crashes, Kubernetes recreates it with the same hostname and reattaches the original volume, so the node rejoins the cluster without data loss. Scaling to four nodes adds cassandra-3, which joins the ring after becoming ready.

Related terms

Deployment Headless Service PersistentVolumeClaim Pod etcd Apache ZooKeeper

References

More in Containers & Orchestration

ConfigMap

A ConfigMap is a Kubernetes API object used to store non-confidential configuration data in key-value pairs, which pods can consume as environment variables, command-line arguments, or configuration files.

Container

A container is a lightweight, isolated runtime that packages an application with its dependencies using OS-level virtualization, enabling consistent execution across environments.

Container Image

A container image is a lightweight, standalone, executable package that includes everything needed to run a piece of software: code, runtime, system tools, libraries, and settings. It is the unit of distribution in container ecosystems like Docker and Kubernetes.

Container Registry

A container registry is a service that stores and distributes container images, enabling developers to push, pull, and version images across environments.

Container Runtime

A container runtime is the low-level software that creates, starts, and stops containers according to the OCI runtime specification, enabling process isolation and resource management.

Docker

Docker is a platform and toolchain for packaging, distributing, and running applications inside lightweight, portable containers, popularising the technology from 2013 onward.

Helm

Helm is a package manager for Kubernetes that uses charts to define, install, and upgrade complex applications as a single, versioned unit.

Ingress Controller

An Ingress Controller is a Kubernetes component that watches Ingress resources and configures a reverse proxy to route external HTTP and HTTPS traffic to services inside the cluster.

Init Container

An init container is a specialized container in a Kubernetes pod that runs to completion before any regular containers start, performing initialization or setup tasks.

Kubernetes

Kubernetes is an open source platform for automating the deployment, scaling, and management of containerized applications across clusters of hosts.