12.3 Kubernetes StatefulSet Spec Structure

Kubernetes StatefulSet Spec Structure is the arrangement of fields within a StatefulSet's specification that together define how many ordinal replicas it manages, what each replica's Pods should look like, how their persistent storage is provisioned, and which headless Service provides their stable network identity, forming a structure distinct from simpler workload types due to its additional storage and identity-related fields.

Core Identification Fields

serviceName

The serviceName field references the headless Service responsible for providing network identity to the StatefulSet's Pods, and this field is required specifically because, unlike other workload types, a StatefulSet's stable per-Pod DNS naming depends entirely on this associated Service existing and being correctly configured.

replicas

The replicas field specifies the desired number of ordinal positions the StatefulSet should maintain, functioning similarly to the same field on a ReplicaSet or Deployment, but with the underlying creation and deletion of Pods to reach this count following strict ordinal sequencing rather than unordered parallel reconciliation.

Pod Template Structure

The Embedded template Field

The template field follows the same structure as any Pod template used by other workload controllers, containing the container definitions, volumes, and other Pod-level configuration, but Pods generated from this template additionally receive the ordinal-derived naming and identity unique to StatefulSet management.

Volume Claim Templates

volumeClaimTemplates Array

The volumeClaimTemplates field contains one or more PersistentVolumeClaim templates, each of which is instantiated once per ordinal, generating a dedicated claim for every replica following the same ordinal-based naming convention applied to the Pods themselves, distinguishing this from a Pod template's ordinary volumes field, which would reference a single shared claim rather than generating per-instance ones.

Structural Fields Within Each Claim Template

Each entry within volumeClaimTemplates follows the standard PersistentVolumeClaim specification structure, including access modes, storage class references, and requested storage capacity, with these values applied uniformly to the generated claim for every ordinal rather than varying between individual replicas.

Update Strategy Structure

updateStrategy Field

The updateStrategy field nests either a type of RollingUpdate or OnDelete, and when RollingUpdate is selected, a further nested rollingUpdate object containing the partition and, in more recent versions, maxUnavailable fields that together shape how updates propagate across ordinals.

Pod Management Policy

podManagementPolicy Field

The podManagementPolicy field, accepting either OrderedReady or Parallel, sits alongside the other top-level spec fields and determines whether the strict sequential creation and deletion behavior applies, or whether the controller is permitted to manage multiple ordinals concurrently without waiting for each individually.

Minimum Ready Seconds

minReadySeconds Field

The minReadySeconds field, present on StatefulSets in the same manner as on Deployments, requires a newly created or updated Pod to remain ready for the specified duration before being considered available, applying this same stabilization safeguard to the StatefulSet's own progress tracking during scaling and update operations.

Selector Requirement

selector Field Consistency

As with other workload controllers, the selector field must match the labels present in the Pod template, and this field remains immutable after creation, following the same consistency and immutability rules applied to Deployment and ReplicaSet selectors, ensuring the StatefulSet reliably recognizes the Pods it has created across its own reconciliation cycles.