10.12 Kubernetes StatefulSet Identity Control

Kubernetes StatefulSet Identity Control is the specific set of mechanisms a StatefulSet uses to assign, preserve, and reapply a stable, ordinal-derived identity to each of its managed Pods, ensuring that despite Pods being replaced as disposable objects like any other Pod, the identity they present to the rest of the cluster remains consistent and predictable across replacements.

Ordinal Index Assignment

Sequential Numbering From Zero

Each Pod within a StatefulSet is assigned a unique ordinal index starting at zero and incrementing sequentially up to one less than the configured replica count, with this ordinal forming the basis for nearly every other identity-related property the Pod carries, including its name, hostname, and associated storage.

Ordinal Stability Across Replacement

If a Pod at a given ordinal position fails or is deleted, its replacement is created carrying the exact same ordinal, rather than being assigned the next available number in sequence, preserving the conceptual continuity of that specific position within the StatefulSet even though the underlying Pod object is entirely new.

Name-Based Identity

Deterministic Pod Naming

A StatefulSet Pod's name is constructed by concatenating the StatefulSet's own name with a hyphen and the Pod's ordinal index, producing predictable, deterministic names that remain stable across replacements and that can be referenced directly by other systems without needing to discover a dynamically generated name.

Contrast With ReplicaSet Naming

This deterministic naming stands in direct contrast to ReplicaSet-managed Pods, whose names incorporate a randomly generated suffix, making individual Pod names unpredictable and unsuitable for any system that needs to reference a specific replica by a fixed, known identifier.

Network Identity

Stable DNS Hostnames

When paired with a headless Service, each StatefulSet Pod's hostname becomes resolvable through a predictable DNS record combining the Pod's own name, the headless Service's name, and the namespace, allowing other components to address a specific ordinal instance directly through DNS rather than relying on Service-level load balancing.

Persistence of Network Identity Through Replacement

Because a replacement Pod carries the same ordinal and therefore the same derived name, its DNS-resolvable identity remains identical to its predecessor's, meaning any external system that had cached or configured a reference to a specific ordinal's hostname continues to reach the correct, though replaced, Pod without reconfiguration.

Storage Identity

Ordinal-Bound PersistentVolumeClaims

Each ordinal position is associated with its own PersistentVolumeClaim, generated from the StatefulSet's volumeClaimTemplates and named using the same ordinal-based convention applied to Pod names, ensuring a one-to-one, stable mapping between a given ordinal and a specific piece of durable storage.

Reattachment Rather Than Recreation

When a Pod at a given ordinal is replaced, the StatefulSet controller reattaches the existing PersistentVolumeClaim associated with that ordinal to the new Pod rather than provisioning a new one, preserving the storage identity alongside the naming and network identity already established for that position.

Identity Preservation During Scaling

New Ordinals on Scale-Up

Scaling a StatefulSet up introduces new ordinals beyond the current highest, each receiving a freshly created PersistentVolumeClaim following the same template, extending the set of stable identities without disturbing the existing ones already in use.

Highest-Ordinal Removal on Scale-Down

Scaling down removes the highest-numbered ordinals first, preserving the lower-numbered, typically longer-established identities, and by default leaves the corresponding PersistentVolumeClaims in place rather than deleting them, guarding against accidental data loss from a scale-down operation that might later be reversed.