Kubernetes StatefulSet Identity Control

Kubernetes StatefulSet Identity Control is the specific set of guarantees a StatefulSet enforces around Pod naming, network addressing, and storage binding, ensuring that each ordinal position represents a single, consistent identity over time rather than a rotating cast of interchangeable instances. This is narrower than the StatefulSet controller's overall behavior: it is specifically the invariants around what "identity" means and how strictly they are enforced, including the at-most-one guarantee that distinguishes a StatefulSet from every other workload controller.

The Three Facets of Identity

Naming Identity

Each Pod's name is deterministically derived as <statefulset-name>-<ordinal>, and this name is reused for any replacement Pod occupying that ordinal slot, giving external systems a stable handle to refer to "the same" logical instance across replacements.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: identity-control-example
spec:
  serviceName: identity-headless
  replicas: 3

Network Identity

Combined with a headless Service, each Pod's hostname and subdomain are set to match its Pod name and the StatefulSet's serviceName, producing a stable DNS record. The Pod's own spec.hostname and spec.subdomain fields are populated automatically by the controller to support this.

kubectl exec identity-control-example-0 -- hostname -f

identity-control-example-0.identity-headless.default.svc.cluster.local

Storage Identity

Each ordinal is bound to its own PersistentVolumeClaim, provisioned once from volumeClaimTemplates and reattached to whichever Pod object currently occupies that ordinal, ensuring the data associated with "instance 0" always follows instance 0, never instance 1.

The At-Most-One Guarantee

No Duplicate Identity, Ever

Unlike a ReplicaSet, which may briefly run more Pods than desired during scale-down races, a StatefulSet guarantees that at most one Pod for a given ordinal is ever running at a time. The controller will not create a replacement for a given ordinal until it has confirmed, through the API server, that the previous occupant has fully terminated.

kubectl get pod identity-control-example-0 -o jsonpath='{.status.phase}'

Why This Matters for Stateful Workloads

This guarantee exists specifically to prevent two processes from simultaneously believing they are "the same" replica and concurrently writing to the same attached storage or claiming the same network identity, a correctness requirement for many distributed stateful systems that assume single-writer semantics per identity slot.

Node Failure and Identity Ambiguity

Manual Intervention When Node Status Is Unknown

If a node hosting a StatefulSet Pod becomes unreachable, the controller cannot safely assume the Pod has actually stopped running, since the node might still be executing it despite being unreachable from the control plane. To preserve the at-most-one guarantee, the controller will not create a replacement until the Pod object is confirmed deleted, which for an unreachable node may require manual force-deletion by an operator who has independently verified the node is truly down.

kubectl delete pod identity-control-example-0 --grace-period=0 --force

Identity Control Diagram

Together, these three bound facets are what allow a StatefulSet Pod to be replaced entirely, a new container, a new UID, potentially a new node, while still functioning as a continuous identity from the perspective of the rest of the system.