K8s Pod 一直 Pending 的全套排查 checklist

kubectl get pods 看到 Pending，新手最容易蒙圈。本文按出现频率排了 8 类原因，配定位命令，照着走一遍基本能搞定。

万能起手式

kubectl describe pod <pod> -n <ns> | tail -30
kubectl get events -n <ns> --sort-by=.lastTimestamp | tail -20

describe 底部的 Events 是最直接的线索，80% 的 Pending 看这里就够了。

1. 资源不足（FailedScheduling: Insufficient cpu/memory）

0/10 nodes are available: 10 Insufficient cpu

检查：

kubectl top nodes
kubectl describe node <node> | grep -A5 "Allocated resources"

注意 Allocated 是 requests 之和，不是实际用量。Pod requests 写得太大也会卡：

kubectl get pod <pod> -o jsonpath='{.spec.containers[*].resources}'

2. 没有合适 node（NodeAffinity / NodeSelector 不匹配）

0/10 nodes are available: 10 node(s) didn't match Pod's node affinity/selector

kubectl get pod <pod> -o yaml | grep -A20 "nodeSelector\|affinity"
kubectl get nodes --show-labels

经常是 nodeSelector 写了 node-role.kubernetes.io/worker: "true" 但节点上压根没这个 label。

3. 污点未容忍（Taints / Tolerations）

0/10 nodes are available: 10 node(s) had untolerated taint

kubectl describe node <node> | grep Taint

修复有两种：要么给 Pod 加 toleration，要么去掉 taint。生产建议加 toleration，taint 通常是有意打的。

4. PVC 还没 bound

pod has unbound immediate PersistentVolumeClaims

kubectl get pvc -n <ns>
kubectl describe pvc <pvc> -n <ns>

可能问题：

• StorageClass 不存在或者拼错
• provisioner 挂了（如 ebs-csi-controller）
• PV 静态绑定时 selector 不匹配

5. 镜像拉不下来

Pod 状态可能是 ImagePullBackOff 或 ErrImagePull，但有时候表现为 ContainerCreating + Events 里报错：

Failed to pull image "xxx": rpc error: code = Unknown

• 私有镜像没配 imagePullSecrets
• 镜像 tag 写错（:latest vs :v1.2.3）
• 国内拉 docker.io 慢/不通 → 用 mirror

6. ResourceQuota / LimitRange 拦住了

exceeded quota: compute-resources

kubectl describe quota -n <ns>
kubectl describe limitrange -n <ns>

经常是 namespace 加了 LimitRange 强制要求 requests/limits，而 Pod 没写。

7. PodSecurityAdmission 拦截（1.25+）

violates PodSecurity "restricted:v1.28"

kubectl get ns <ns> -o jsonpath='{.metadata.labels}'

namespace 加了 pod-security.kubernetes.io/enforce=restricted，Pod 里有 privileged: true 或者 hostNetwork: true 都会被拦。

8. CNI 还没就绪 / Webhook 阻塞

罕见但很坑：

• 节点 Ready 了但 CNI 插件还没 ready，Pod 调度上去后卡在 ContainerCreating
• ValidatingWebhook 挂了，Pod 创建 API 都过不了，根本不会 schedule

kubectl get pods -A | grep -v Running | grep -v Completed
kubectl get validatingwebhookconfigurations

Debug 神器

如果 events 都没有，开个 ephemeral container 看节点视角：

kubectl debug node/<node> -it --image=busybox

或者直接看 kubelet 日志：

ssh <node> 'journalctl -u kubelet -f | grep <pod-name>'

教训一句话：Pending 看 describe 的 Events 永远是第一步，不要直接翻 controller-manager 日志。