Debug: Kubernetes pod stuck in Pending state

Kubernetes pod stays in Pending state and never gets scheduled to a node.

Diagnose why a pod is stuck in Pending:

# 1. Describe the pod for events
kubectl describe pod <pod-name> -n <namespace>
# Look at the 'Events' section at the bottom

# 2. Common reasons and fixes:

# Insufficient resources
# Event: 'Insufficient cpu' or 'Insufficient memory'
kubectl describe nodes | grep -A5 'Allocated resources'
# Fix: Reduce resource requests, add nodes, or remove other pods

# No matching node (nodeSelector, affinity, tolerations)
# Event: 'didn't match Pod's node affinity/selector'
kubectl get pod <pod> -o yaml | grep -A10 nodeSelector
kubectl get nodes --show-labels
# Fix: Match labels or remove selector

# PVC not bound
# Event: 'persistentvolumeclaim is not bound'
kubectl get pvc -n <namespace>
# Fix: Create the PV or check StorageClass

# Image pull issues (stuck in ContainerCreating, not Pending)
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

# Taints preventing scheduling
kubectl describe nodes | grep Taints
# Fix: Add tolerations to pod spec

# 3. Check cluster capacity
kubectl top nodes
kubectl get pods --all-namespaces | grep -c Running

# 4. Check scheduler health
kubectl get pods -n kube-system | grep scheduler
kubectl logs -n kube-system kube-scheduler-<node>

Pending means the scheduler cannot find a suitable node for the pod. The describe command's Events section almost always reveals the exact reason.

Kubernetes pods that fail to schedule