highAdvancedSymptom-first#statefulset#pvc#headless-service#ordered

StatefulSet stuck — ordered readiness, PVC pending, or headless service issue

StatefulSet pods stuck in Pending or ContainerCreating sequentially

Likely source:availabilitydeployment

Focused incident mode — strips away everything but this runbook.

Symptoms

  • StatefulSet pods stuck in Pending or ContainerCreating sequentially
  • kubectl rollout status statefulset hangs on pod ordinal N
  • StatefulSet never reaches desiredReady count

StatefulSet pods start in order (0, 1, 2...). If pod 0 is stuck, no subsequent pod will start. Fix the root cause of pod 0 first.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • StatefulSet status

    kubectl describe statefulset <name> -n <namespace>

  • PVC status for StatefulSet pods

    kubectl get pvc -n <namespace> | grep <statefulset>

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • kubectl get pvc shows Pending for <name>-0
  • Pod stuck in ContainerCreating waiting for volume

Confirm before fixing

kubectl describe pvc <name>-<ordinal> -n <namespace>
READ

Read PVC events

Fix

kubectl get storageclass -o wide
READ

Ensure the StorageClass provisioner is running and defaults are set (follow pvc-pending runbook)

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
kubectl rollout status statefulset <name> -n <namespace>
READ

Identify which ordinal is stuck

2
kubectl get pvc -n <namespace> | grep <name>
READ

Check PVC status for all pods

3
kubectl get svc <name> -n <namespace> -o jsonpath='{.spec.clusterIP}'
READ

Confirm headless service exists (clusterIP=None)

4
kubectl describe pod <name>-0 -n <namespace> | tail -20
READ

Read events for the stuck pod

Prevention

  • Ensure PVC storage is provisioned before deploying the StatefulSet.
  • Always create the headless Service before the StatefulSet.
  • Use parallel podManagementPolicy if ordering is not required.
  • Monitor PVC binding and StatefulSet readyReplicas as part of the deploy pipeline.

Related runbooks

Same stack, same failure family — worth a skim.

PersistentVolumeClaim stuck in Pending — no provisionerhigh

kubectl get pvc shows Pending

KubernetesAdvanced2 causes
Open runbook
Deployment rollout stuck — progress deadline exceededhigh

kubectl rollout status hangs on 'Waiting for rollout to finish'

KubernetesIntermediate2 causes
Open runbook
PV reclaim slow or stuck — controller not picking up Released volumeshigh

PV stays in Released state for hours after PVC deletion

KubernetesAdvanced3 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.