K8s PVC 无法绑定导致 Pod Pending 的排查与解决

问题现象与背景原因

Pod 卡在 Pending，describe 事件提示 persistentvolumeclaim "xxx" not bound。查看 PVC 状态是 Pending 而非 Bound，Pod 因此一直起不来。

常见根因：

• PVC 申请的 storageClassName 在集群中不存在；
• 对应的 StorageClass 的 provisioner（动态供给器）异常或已下线；
• 云盘场景：PVC 申请的 zone 与 Pod 调度节点不在同一可用区；
• 静态供给时，PV 的 capacity / accessModes / selector 与 PVC 不匹配；
• 集群没设置默认 StorageClass，而 PVC 未显式指定。

排查过程（思路与定位方法）

# 1. 看 PVC 状态与事件
kubectl get pvc -n <ns>
kubectl describe pvc <pvc> -n <ns>
# 事件里通常会直接说 "no persistent volumes available" 或 "storageclass not found"

# 2. 看 StorageClass 是否存在
kubectl get storageclass
kubectl get sc

# 3. 看动态供给器（provisioner）Pod 是否健康（如 ceph-csi、ebs-csi）
kubectl -n kube-system get pods | grep csi

# 4. 静态 PV 是否匹配
kubectl get pv

解决方法

动态供给：确保 StorageClass 存在且 provisioner 正常

# 设置默认 StorageClass（若缺失）
kubectl patch storageclass <sc-name> -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

跨可用区问题，StorageClass 加 waitForFirstConsumer：

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: ssd-sc
provisioner: ebs.csi.aws.com
volumeBindingMode: WaitForFirstConsumer   # 等 Pod 调度确定后再绑定，自动对齐 zone

静态供给：确保 PV 与 PVC 匹配

# PV 端
apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-nfs-001
spec:
  capacity:
    storage: 10Gi
  accessModes:
  - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: manual
  nfs:
    server: 10.0.0.10
    path: /data
---
# PVC 端 storageClassName / accessModes / capacity 必须对应
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-nfs-001
spec:
  accessModes:
  - ReadWriteOnce
  storageClassName: manual
  resources:
    requests:
      storage: 10Gi

操作命令速查

kubectl get pvc,pv,sc -n <ns>
kubectl describe pvc <pvc> -n <ns>
kubectl patch storageclass <sc> -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

经验总结

• PVC 不绑定 90% 是 StorageClass 或 zone 问题，先 kubectl describe pvc 看事件，多半直接给答案。
• 云环境务必用 WaitForFirstConsumer，避免 PV / Pod 跨可用区。
• 没默认 SC 且 PVC 不显式指定，会直接 Pending，新集群建议设默认 SC。
• 静态 PV 要注意 capacity / accessModes / storageClassName 三方一致。