← All notes

Answer: A StatefulSet manages Pods that need a stable identity: each Pod gets a fixed ordinal name (web-0, web-1, ...), a stable network identity through a headless Service, and its own persistent storage. Pods are created, scaled and deleted in order.

Compared with a Deployment

Both run Pods from one template, but a Deployment's Pods are interchangeable.

Key pieces

• Headless Service: you must create it; it gives each Pod a DNS name like web-0.nginx.
• volumeClaimTemplates: one PersistentVolumeClaim per Pod.

Updates

kubectl patch statefulset web --type=json   -p='[{"op":"replace","path":"/spec/template/spec/containers/0/image","value":"registry.k8s.io/nginx-slim:0.24"}]'

Caution

Deleting or scaling down a StatefulSet does not delete its volumes, which protects data but leaves storage to clean up.

Claims

• id: C1 claim: A StatefulSet maintains a sticky identity for each Pod. source: S1 evidence: "A StatefulSet runs a group of Pods, and maintains a sticky identity for each of"
• id: C2 claim: StatefulSets provide ordered, graceful deployment and scaling. source: S1 evidence: "Ordered, graceful deployment and scaling."
• id: C3 claim: StatefulSets currently require a Headless Service. source: S1 evidence: "StatefulSets currently require a Headless Service"
• id: C4 claim: The tutorial covers examining the Pod's ordinal index. source: S2 evidence: "Examining the Pod's ordinal index"

Sources

• [S1] StatefulSets. Kubernetes Authors. https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/ . License: CC BY 4.0 (kubernetes/website). Accessed 2026-11-04.
• [S2] StatefulSet Basics. Kubernetes Authors. https://kubernetes.io/docs/tutorials/stateful-application/basic-stateful-set/ . License: CC BY 4.0 (kubernetes/website). Accessed 2026-11-04.

License: this note is CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Summary by iinventedlight (AI-assisted).

@misc{iil_note_sz4tfjgs,
  author = {{iinventedlight}},
  title = {{Kubernetes StatefulSets}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-11-04},
  url = {https://iinventedlight.com/library/notes/kubernetes-statefulsets/},
  note = {Permanent ID iil:note:sz4tfjgs. License: CC-BY-4.0.},
}

Markdown

Spotted a mistake? Use the MCP feedback tool or email hello@iinventedlight.com.

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/kubernetes-statefulsets.md.