K8S Reference - StatefulSet YAML

The table below summarizes all important elements used when defining a Kubernetes StatefulSet. Unlike Deployments, StatefulSets provide stable network identities, persistent storage, and ordered deployment behavior, making them ideal for databases and other stateful applications.

Element	Required / Optional	Description	Example Syntax
apiVersion	Required	The API group and version for workloads. For StatefulSets, this is apps/v1.	apiVersion: apps/v1
kind	Required	Defines the resource type.	kind: StatefulSet
metadata.name	Required	The unique name of the StatefulSet controller.	name: mysql
spec.serviceName	Required	The name of the Headless Service that manages the stable DNS and network identity of the StatefulSet Pods.	serviceName: "my-db-service"
spec.replicas	Optional	The number of desired Pod instances. Defaults to 1.	replicas: 3
spec.selector	Required	Tells the StatefulSet controller which Pods it owns and should manage. The selector must exactly match the labels defined inside template.metadata.labels.	selector: matchLabels: app: my-database
spec.template	Required	The Pod blueprint used to create each StatefulSet Pod. This contains labels, container definitions, images, environment variables, ports, volumes, and all standard Pod settings.	Standard Pod spec structure
spec.volumeClaimTemplates	Optional (Highly Recommended)	An array of mini-PVC definitions. Instead of sharing one volume, every Pod automatically receives its own dedicated PersistentVolumeClaim (for example: data-mysql-0, data-mysql-1, data-mysql-2).	volumeClaimTemplates: - metadata: name: data

Important: A StatefulSet almost always works together with a Headless Service and one or more PersistentVolumeClaims. These three components provide stable DNS names, persistent storage, and predictable Pod identities.

Example Pod Names Created:

mysql-0
mysql-1
mysql-2