Kubernetes StatefulSet Spec Structure

Kubernetes StatefulSet Spec Structure is the field-by-field composition of a StatefulSet's spec, detailing the required and optional fields that distinguish it structurally from a Deployment or ReplicaSet spec, most notably the mandatory serviceName linkage and the volumeClaimTemplates array that has no equivalent in stateless workload types.

Required Top-Level Fields

serviceName

spec.serviceName names the headless Service that provides network identity for the StatefulSet's Pods; this field is required and the API server validates that the reference resolves, since without it the DNS naming that underlies stable network identity would have no home.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: spec-structure-example
spec:
  serviceName: spec-structure-headless
  replicas: 3
  selector:
    matchLabels:
      app: db
  template:
    metadata:
      labels:
        app: db
    spec:
      containers:
        - name: db
          image: registry.example.com/db:1.0.0

selector and template

As with other workload controllers, selector and template are required, with the same label-consistency rule requiring template labels to satisfy the selector, and the same general PodSpec structure inside template.spec.

volumeClaimTemplates

The Field With No ReplicaSet Equivalent

spec.volumeClaimTemplates is an array of PersistentVolumeClaim templates, each producing one claim per ordinal, named by combining the template's own name, the StatefulSet's name, and the ordinal index.

spec:
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes: ["ReadWriteOnce"]
        storageClassName: fast-ssd
        resources:
          requests:
            storage: 50Gi

Multiple Templates for Multiple Volumes

More than one entry in volumeClaimTemplates is valid, useful for workloads needing distinct volumes for different purposes, data storage and write-ahead logs on separate storage classes, for instance, with each producing its own set of per-ordinal claims.

spec:
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        storageClassName: fast-ssd
        resources:
          requests:
            storage: 50Gi
    - metadata:
        name: wal
      spec:
        storageClassName: fast-nvme
        resources:
          requests:
            storage: 10Gi

podManagementPolicy

Controlling Startup and Shutdown Concurrency

spec.podManagementPolicy accepts OrderedReady (the default, strictly sequential) or Parallel (all Pods started or stopped simultaneously without waiting for sibling ordinals), a structural choice made once at spec-authoring time based on whether the workload actually requires ordering.

spec:
  podManagementPolicy: Parallel

updateStrategy

The Field Governing Template Propagation

spec.updateStrategy nests either type: RollingUpdate with a rollingUpdate.partition sub-field, or type: OnDelete, structurally parallel to but functionally distinct from a Deployment's own strategy field.

spec:
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      partition: 0

minReadySeconds and Optional Fields

Shared Fields With Stateless Controllers

minReadySeconds and revisionHistoryLimit appear in StatefulSet spec structure with the same meaning as their Deployment counterparts, availability stabilization windows and retained revision count respectively, demonstrating that not every field is unique to stateful workloads even where the overall spec shape diverges significantly.

spec:
  minReadySeconds: 10
  revisionHistoryLimit: 5

StatefulSet Spec Structure Diagram

Understanding this spec structure precisely, and in particular recognizing volumeClaimTemplates as the single most consequential structural difference from a stateless workload spec, is the prerequisite for correctly authoring any StatefulSet manifest from scratch.