Managing StatefulSets
1. Creating StatefulSet
| Field | Description | Example |
|---|---|---|
| apiVersion | API version to use | apps/v1 |
| kind | Resource type | StatefulSet |
| metadata.name | Name of the StatefulSet | web |
| spec.replicas | Number of replicas | 3 |
| spec.selector.matchLabels | Label selector for pods | {app: web} |
| spec.template.metadata.labels | Labels for pods | {app: web} |
| spec.template.spec.containers[].name | Name of container | nginx |
| spec.template.spec.containers[].image | Container image | nginx:1.19 |
Example: Basic StatefulSet Configuration
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: web
spec:
replicas: 3
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: nginx
image: nginx:1.19
2. Listing StatefulSets
| Field | Description | Example |
|---|---|---|
| NAME | Name of the StatefulSet | web |
| READY | Number of ready replicas / Total replicas | 3/3 |
| STATUS | Current status of the StatefulSet | Running |
| REVISION | Current revision of the StatefulSet | 1 |
3. Describing StatefulSet Details
| Field | Description | Example Value |
|---|---|---|
| apiVersion | API version of the StatefulSet resource | apps/v1 |
| kind | Type of the Kubernetes resource | StatefulSet |
| metadata.name | Name of the StatefulSet | web |
| spec.replicas | Number of desired pods | 3 |
| spec.selector.matchLabels | Label selector to identify pods managed by this StatefulSet | {app: web} |
| spec.template.spec.containers[].name | Name of the container in the pod template | nginx |
| spec.template.spec.containers[].image | Docker image to use for the container | nginx:1.19 |
| spec.template.spec.containers[].ports.containerPort | Port to expose from the container | 80 |
| spec.volumeClaimTemplates | Template for persistent volumes to be attached to pods | [{metadata: {name: www}, spec: {accessModes: [ReadWriteOnce], resources: {requests: {storage: 1Gi}}}}] |
Example: Basic StatefulSet Definition
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: web
spec:
selector:
matchLabels:
app: web
replicas: 3
template:
metadata:
labels:
app: web
spec:
containers:
- name: nginx
image: nginx:1.19
ports:
- containerPort: 80
volumeMounts:
- name: www
mountPath: /usr/share/nginx/html
volumeClaimTemplates:
- metadata:
name: www
spec:
accessModes: [ "ReadWriteOnce" ]
resources:
requests:
storage: 1Gi4. Scaling StatefulSet
| Field | Description | Values |
|---|---|---|
| spec.replicas | Number of replicas to maintain | 3 |
| status.replicas | Current number of replicas running | 3 |
| status.readyReplicas | Number of ready replicas | 3 |
| status.currentReplicas | Number of replicas currently updated | 3 |
| status.updateRevision | Revision of the current update | v1 |
Example: Scaling StatefulSet
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: web
spec:
serviceName: "nginx"
replicas: <span class="hl-1">5</span>
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.19
Note: Scaling a StatefulSet increases or decreases the number of replicas while maintaining stable network identifiers and persistent storage.
5. Understanding Ordered Pod Creation
| Property | Description | Default Value | Notes |
|---|---|---|---|
| podManagementPolicy | Controls the ordering of Pod creation | Parallel |
Can be Parallel or OrderedReady |
| orderReady | Ensures Pods are created in order and ready before proceeding | false |
Only effective when podManagementPolicy is OrderedReady |
Example: Setting Ordered Pod Creation
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: web
spec:
serviceName: "nginx"
replicas: 3
podManagementPolicy: OrderedReady
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.19
Note: When
podManagementPolicy is set to OrderedReady, Pods are created sequentially and only the next Pod is started after the previous one is ready.
6. Using Parallel Pod Management
Kubernetes StatefulSets support different pod management policies that control how pods are created, updated, and deleted. The parallel pod management policy allows all pods to be created or updated simultaneously, rather than sequentially.
| Policy | Description | Use Case |
|---|---|---|
| Parallel | Pods are created or updated in parallel without waiting for previous pods to become ready. | When pod creation order is not critical and faster deployment is preferred. |
| OrderedReady | Pods are created or updated sequentially, waiting for each pod to reach Ready status before starting the next one. |
When pod order matters and dependencies between pods must be respected. |
Example: Setting Parallel Pod Management
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: web
spec:
serviceName: "nginx"
replicas: 3
podManagementPolicy: Parallel
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.19
Note: The
Parallel policy is useful for StatefulSets where pod order does not matter, such as when pods are independent and can be scaled or updated simultaneously without affecting each other.
7. Configuring Volume Claim Templates
| Field | Description | Example |
|---|---|---|
| spec.volumeClaimTemplates | Defines the template for persistent volumes to be used by StatefulSet pods. | [{"metadata": {"name": "data"}, "spec": {"accessModes": ["ReadWriteOnce"], "resources": {"requests": {"storage": "1Gi"}}}}] |
Example: Volume Claim Template Configuration
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: web
spec:
serviceName: "nginx"
replicas: 2
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.19
ports:
- containerPort: 80
volumeMounts:
- name: www
mountPath: /usr/share/nginx/html
volumeClaimTemplates:
- metadata:
name: www
spec:
accessModes: [ "ReadWriteOnce" ]
resources:
requests:
storage: 1Gi
8. Using Headless Services
| Property | Description | Value |
|---|---|---|
| clusterIP | Specifies the cluster IP address for the Service | None |
| publishNotReadyAddresses | Controls whether to publish not-ready addresses | true |
Example: Headless Service Definition
apiVersion: v1
kind: Service
metadata:
name: nginx-headless
spec:
clusterIP: None
ports:
- port: 80
targetPort: 80
publishNotReadyAddresses: true
selector:
app: nginx
Note: Headless services are used to enable direct access to Pod IPs without load balancing.
9. Understanding Stable Network IDs
Kubernetes StatefulSets provide stable, unique network identifiers for pods, which are crucial for stateful applications that require persistent network identities.
| Identifier | Description | Stability | Usage |
|---|---|---|---|
| Pod DNS Name | Each pod gets a DNS name in the format <pod-name>.<service-name>.<namespace>.svc.cluster.local |
Stable across pod restarts | Used for service discovery and inter-pod communication |
| Headless Service | A service without a cluster IP, allowing direct access to pods via their individual DNS names | Stable network identity for each pod | Used to ensure pods can be reached by their stable DNS names |
| Network ID | Unique identifier for each pod that persists across pod restarts | Stable and persistent | Used in stateful applications to maintain consistent network identity |
Example: Headless Service Configuration
apiVersion: v1
kind: Service
metadata:
name: web
spec:
clusterIP: None
ports:
- port: 80
selector:
app: nginx
Note: The
clusterIP: None setting makes the service headless, ensuring that pods are accessible via their individual DNS names.
10. Updating StatefulSets
| Field | Description | Values | Notes |
|---|---|---|---|
| spec.updateStrategy.type | Update strategy type | "RollingUpdate" or "OnDelete" |
Default is "RollingUpdate" |
| spec.updateStrategy.rollingUpdate.partition | Partition for rolling update | 0 to replicas |
Used for blue-green deployments |
Example: Update Strategy Configuration
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: web
spec:
serviceName: "web"
replicas: 3
updateStrategy:
type: "RollingUpdate"
rollingUpdate:
partition: 2
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.19
Note: When
partition is set to 2, only the last 2 pods (index 2 and 3) are updated. The first pod remains unchanged.11. Deleting StatefulSets
| Command | Description | Notes |
|---|---|---|
| kubectl delete statefulset <name> | Delete a StatefulSet | Deletes the StatefulSet and its associated Pods |
| kubectl delete statefulset <name> --cascade=orphan | Delete StatefulSet without deleting Pods | Pods continue running but are no longer managed by the StatefulSet |
| kubectl delete statefulset <name> --cascade=foreground | Delete StatefulSet with foreground cascading | Deletes the StatefulSet and waits for all Pods to be deleted before removing the StatefulSet |
Example: Delete a StatefulSet with foreground cascading
kubectl delete statefulset my-statefulset --cascade=foreground
Note: When deleting a StatefulSet, the default behavior is to delete all associated Pods and then delete the StatefulSet itself. Use
--cascade=orphan to keep Pods running after deletion.
Warning: Deleting a StatefulSet with
--cascade=orphan does not delete the associated PersistentVolumeClaims (PVCs). You must manually delete them if desired.
12. Troubleshooting StatefulSet Issues
| Issue | Description | Common Causes | Solution |
|---|---|---|---|
| Pod Not Starting | StatefulSet pods fail to start or remain in Pending state. | Insufficient resources, volume mount issues, image pull errors, or missing secrets/configmaps. | Check pod events using kubectl describe pod <pod-name>. Ensure resource limits and requests are appropriate. Verify volume claims and image availability. |
| Volume Not Bound | StatefulSet pods fail to bind to PersistentVolumes (PVs). | PV not created, incorrect StorageClass, or mismatched access modes. | Verify PVs and their status with kubectl get pv. Confirm StorageClass matches the PVC specification. |
| Pods Not Scaling | StatefulSet does not scale up or down as expected. | Incorrect replica count, stuck in update process, or resource constraints. | Check StatefulSet status with kubectl get statefulset <name>. Ensure replica count is correct and no updates are pending. |
| Data Loss or Corruption | StatefulSet pods lose or corrupt data. | Improper volume handling, node failures, or misconfigured storage. | Ensure proper backup and restore procedures. Use kubectl exec to inspect data inside pods. Validate storage configurations. |
Note: Always check
kubectl logs and kubectl describe for detailed diagnostics when troubleshooting StatefulSet issues.