How to fix StatefulSet not ready in Kubernetes

Get the overall status:

kubectl get statefulset <name>
kubectl get statefulset <name> -o yaml
kubectl get pods -l app=<name>
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

Look at the READY column (e.g., "0/3" means no pods ready). The Events section shows recent warnings or errors that blocked pod creation.

Since StatefulSets deploy sequentially, always start with pod-0:

kubectl describe pod <statefulset>-0
kubectl logs <statefulset>-0
kubectl logs <statefulset>-0 --previous  # If pod crashed

The "Events" section of describe shows:
- "Pending": Pod waiting for resources or PVC binding
- "CrashLoopBackOff": Container exits immediately (check logs)
- "ImagePullBackOff": Image pull failed
- "Not Ready": Container running but readiness probe failing

StatefulSets require persistent storage. Check PVC status:

kubectl get pvc
kubectl describe pvc <statefulset>-<ordinal>  # e.g., mysql-data-mysql-0

Look for "Status: Bound". If Status is "Pending":
- No PersistentVolume available (check kubectl get pv)
- Storage provisioner (e.g., EBS, NFS) not configured or failing
- Storage class doesn't exist: kubectl get storageclass

If PVC is stuck, describe it:

kubectl describe pvc <name>

The Events section shows provisioning failures.

Insufficient resources often prevent pod scheduling:

kubectl top nodes
kubectl top pods -n <namespace>
kubectl describe nodes

Look for:
- High CPU/memory utilization
- "Insufficient cpu" or "Insufficient memory" in pod events
- Disk pressure on nodes

If constrained, either:
- Scale down other workloads: kubectl scale deployment <name> --replicas=1
- Add nodes to the cluster
- Reduce StatefulSet replica count for testing: kubectl scale statefulset <name> --replicas=1

StatefulSets require a headless service (clusterIP: None) for DNS:

kubectl get service <statefulset-name>
kubectl describe service <statefulset-name>

The service selector should match the StatefulSet labels. Expected output:
- ClusterIP: None (headless)
- Selector: app=<statefulset-name> (or your label)

If missing, create it:

apiVersion: v1
kind: Service
metadata:
  name: mysql
spec:
  clusterIP: None
  selector:
    app: mysql
  ports:
  - port: 3306
    name: mysql

Misconfigured probes often fail at startup. View current probe settings:

kubectl get statefulset <name> -o yaml | grep -A15 readinessProbe:

Common issues:
- initialDelaySeconds too low (should give app time to start)
- timeoutSeconds too low (app is slow)
- Probe command/endpoint doesn't exist yet

Test the probe manually:

kubectl exec -it <statefulset>-0 -- <probe-command>
# Example: curl http://localhost:8080/health

If it fails, the app isn't ready. Increase delays:

readinessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 60  # Increase from default
  timeoutSeconds: 10
  periodSeconds: 10
  failureThreshold: 3

Image pull failures block StatefulSet startup:

kubectl get statefulset <name> -o yaml | grep image:
kubectl describe pod <statefulset>-0 | grep -i "image"

Test locally:

docker pull <image:tag>  # Fails if unavailable or credentials wrong

For private registries, ensure imagePullSecrets:

kubectl get secret
kubectl create secret docker-registry regcred \
  --docker-server=myregistry.com \
  --docker-username=user \
  --docker-password=pass

Add to StatefulSet:

spec:
  imagePullSecrets:
  - name: regcred

If debugging shows the issue is app-side (e.g., bad config), fix the underlying problem, then delete the pod:

kubectl delete pod <statefulset>-0

The StatefulSet controller will recreate it. Since you fixed the issue (config, image, storage, probe settings), the new pod should become Ready.

Monitor recreation:

kubectl get pods -w  # Watch mode

Once pod-0 is Ready, the StatefulSet will deploy pod-1, pod-2, etc.