Pod 长期 Pending 排查
核心概念 Pod 长期 Pending 的根因分类和排查流程，涵盖资源不足、PVC 未绑定、调度约束冲突等。 Pod 停留在 Pending = 调度器无法把 Pod 绑定到任意节点，或绑定成功后 kubelet 拉取镜像/创建容器失败卡住。
分两大块：调度阶段失败（最常见）、节点绑定后启动失败，附带排查命令、GPU集群特殊场景。
1. 调度层面原因（kubectl describe pod 事件提示 FailedScheduling）
调度器遍历所有节点，全部不满足条件，没有可用节点，Pod 持续 Pending。
1.1. 资源配额不足（CPU/内存/GPU 不够）
节点剩余资源无法满足 Pod resources.requests。
- 普通CPU内存场景
Pod 申请cpu:4, memory:16Gi，集群所有节点剩余都小于该值。 - GPU集群高频坑
GPU 属于扩展资源，只能写在 limits，request 跟随 limits：
resources:
limits:
nvidia.com/gpu: 1
现象：所有GPU节点 nvidia.com/gpu 已被占满，无空闲显卡，调度直接拒绝。
查看节点剩余资源命令：
kubectl describe nodes | grep -A 10 Allocatable
kubectl describe nodes | grep nvidia.com/gpu
1.2. 节点选择约束不匹配（nodeSelector / nodeAffinity）
Pod 写了节点筛选规则，但集群没有符合标签的节点。
- nodeSelector：要求
gpu-type=a100，集群无该标签节点； - nodeAffinity required 硬约束：要求
gpu-type In [h100]，只有3090节点；
事件提示：didn't match node selector。 排查节点标签：
kubectl get nodes --show-labels
1.3. 污点与容忍不匹配 Taints/Tolerations
节点打了污点，Pod 缺少对应 tolerations，调度器拒绝调度。
典型场景：
- GPU节点污点
gpu=true:NoSchedule，普通业务Pod无容忍； - master控制平面节点自带污点，业务Pod无法调度上去。
事件提示：node had taint xxx that pod did not tolerate。
1.4. 节点端口冲突 / 节点端口已耗尽
Pod 使用 hostPort 绑定宿主机端口，该端口已被其他Pod占用，无法调度到该节点。
1.5. 节点资源配额、命名空间 LimitRange / ResourceQuota 限制
- 命名空间 ResourceQuota：整个ns总CPU/GPU已耗尽，禁止新建Pod；
- LimitRange：Pod 申请资源低于最小、高于最大限制，被拦截。 查看配额：
kubectl get resourcequota -n 命名空间
kubectl describe limitrange -n 命名空间
1.6. 拓扑、Pod 反亲和阻止调度
配置了 podAntiAffinity 硬约束：同节点不能运行相同标签Pod，但集群所有节点都已有副本，无空闲节点容纳新Pod。
事件提示：pod anti-affinity rules failed。
1.7. 调度器自定义插件拦截（Volcano/HAMi/DRA）
AI集群特有：
- Volcano Gang调度：任务需要8卡，集群凑不齐8张空闲GPU，任务持续pending；
- HAMi vGPU：节点剩余显存不足Pod申请的gpumem，调度扩展拦截。
2. 调度成功绑定节点，但节点侧启动失败（事件无 FailedScheduling，镜像/容器报错）
调度器已经选好节点，Pod 下发到节点kubelet，但创建容器卡住，依然显示 Pending。
2.1. 镜像拉取失败（最常见）
- 镜像名称写错、仓库地址不通；
- 私有仓库缺少 imagePullSecret；
- 节点无外网，无法拉取外网镜像；
- 镜像版本不存在。
事件关键词：ErrImagePull/ImagePullBackOff。
2.2. 镜像拉取密钥缺失
私有镜像仓库需要 imagePullSecrets，Pod 未配置，鉴权失败拉取不到镜像。
2.3. 存储PVC未绑定（有存储需求必看）
Pod 挂载 persistentVolumeClaim，PVC 状态还是 Pending，没有 PV 能绑定；
原因：无匹配存储类、存储容量不满足、访问模式不匹配。
现象：Pod 等待PVC就绪，持续 Pending。
kubectl get pvc -n xxx
2.4. 容器配置语法错误，kubelet 无法创建容器
- command/args 格式错误；
- securityContext 权限非法；
- 挂载路径冲突、subPath 错误；
- 环境变量引用不存在configmap/secret。
2.5. 节点资源耗尽（磁盘inode/磁盘满）
节点磁盘100%占用、inode耗尽，kubelet 无法创建容器日志/临时文件，无法启动Pod。
2.6. GPU设备插件异常（AI集群专属）
nvidia-device-plugin DaemonSet 异常、崩溃：
节点无法上报 nvidia.com/gpu 资源，哪怕有空闲GPU，调度也识别不到，Pod pending。
# 查看device-plugin状态
kubectl get ds -n kube-system nvidia-device-plugin-daemonset
3. 其他罕见全局类原因
- kube-scheduler 组件宕机、异常，完全不处理Pod调度；
- 节点状态 NotReady（节点磁盘满、kubelet挂掉、网络故障），不可调度；
查看节点状态：
kubectl get nodes
NotReady 节点不会被调度器选中。
- Pod 优先级抢占，但高优先级任务持续占用资源，低优先级永远等待；
- 集群维护、节点被 cordon 封锁
kubectl cordon nodexxx，节点禁止新Pod调度。
4. 标准排查步骤（从快到慢）
- 查看Pod事件，直接定位根因（最核心命令）
kubectl describe pod <pod-name> -n <ns>
重点看 Events 区块，会打印拒绝调度、拉取镜像、PVC失败完整原因。
- 检查节点是否就绪、是否被封锁
kubectl get nodes
kubectl get node node-name | grep SchedulingDisabled
- 核对资源申请，查看节点剩余可分配资源
kubectl describe node <节点名>
- 核对标签、污点、Pod亲和策略
kubectl get nodes --show-labels
kubectl describe node <节点名> | grep Taints
- 若挂载存储，检查PVC状态
kubectl get pvc -n ns
- GPU集群额外检查设备插件、vGPU调度组件
kubectl get pods -n kube-system | grep nvidia
5. 快速区分两类Pending关键词
- 调度失败：事件包含
FailedScheduling，代表没找到合适节点； - 节点启动失败：事件包含
ErrImagePull/ContainerCreating，节点已选中，但容器起不来。
6. GPU训练Agent场景高频Pending总结
- GPU全部占用，
nvidia.com/gpu资源不足； - GPU节点有污点，Pod 缺少 tolerations；
- nodeAffinity 限定A100，但集群只有3090；
- nvidia-device-plugin 异常，节点不上报GPU资源；
- Volcano Gang调度，无法凑齐任务所需总显卡；
- HAMi vGPU节点剩余显存不足Pod申请值。
关联文档