zesheng 的数字花园

Kubernetes PV 挂载失败排查

Properties1
tagskubernetes, 运维, 故障复盘, 排障手册

4分钟阅读

Kubernetes PV 挂载失败排查

现象

Pod 无法正常启动，事件中出现 PVC 未绑定、Volume attach/mount 失败、StorageClass 不存在或存储后端不可用等信息。

kubectl get pods -A
kubectl get pvc -A

常见影响：

  • Pod 长时间 Pending。
  • StatefulSet 无法扩容或滚动更新。
  • 应用数据目录无法挂载。
  • 业务启动失败或数据不可写。

环境

  • 集群：Kubernetes
  • 对象：PV / PVC / Pod / StorageClass
  • 常用命令：kubectl describe pvc, kubectl describe pod

排查过程

  1. 查看 Pod 状态和事件。
kubectl get pod <pod-name> -n <namespace> -o wide
kubectl describe pod <pod-name> -n <namespace>
  1. 查看 PVC 状态。
kubectl get pvc -n <namespace>
kubectl describe pvc <pvc-name> -n <namespace>
  1. 查看 PV 状态。
kubectl get pv
kubectl describe pv <pv-name>
  1. 查看 StorageClass。
kubectl get storageclass
kubectl describe storageclass <storageclass-name>
  1. 如果使用 CSI，查看 CSI 组件状态。
kubectl get pods -A | grep -i csi
kubectl get events -A --sort-by=.lastTimestamp

常见根因

根因典型表现排查方向
PVC 未绑定PVC 为 PendingStorageClass、PV、动态供给
StorageClass 不存在事件提示 storageclass not found检查 PVC 中的 storageClassName
容量不匹配PVC 请求容量大于 PV调整 PVC 或创建更大 PV
accessModes 不匹配绑定失败或挂载失败ReadWriteOnce、ReadOnlyMany、ReadWriteMany
节点无法访问存储mount timeout / attach failed网络、权限、存储后端
CSI 插件异常CSI Pod CrashLoop 或事件报错CSI controller/node 日志

解决方法

PVC 未绑定

kubectl describe pvc <pvc-name> -n <namespace>
kubectl get storageclass
kubectl get pv

处理方式：

  • 确认 storageClassName 是否存在。
  • 确认是否有满足容量和 accessModes 的 PV。
  • 如果使用动态供给，检查 CSI provisioner 是否正常。

StorageClass 配置问题

kubectl describe storageclass <storageclass-name>

处理方式：

  • 修正 PVC 中的 storageClassName。
  • 创建正确的 StorageClass。
  • 检查默认 StorageClass 是否符合预期。

挂载到节点失败

kubectl describe pod <pod-name> -n <namespace>
kubectl describe node <node-name>

处理方式：

  • 检查节点到存储后端的网络。
  • 检查存储权限、账号、Secret。
  • 检查 kubelet 和 CSI node 插件日志。

CSI 组件异常

kubectl get pods -A | grep -i csi
kubectl logs <csi-pod-name> -n <namespace>

处理方式：

  • 修复 CSI controller 或 node 组件。
  • 检查 CSI 版本和 Kubernetes 版本兼容性。
  • 检查存储后端是否可用。

验证结果

kubectl get pvc -n <namespace>
kubectl get pv
kubectl get pod <pod-name> -n <namespace> -o wide

确认点：

  • PVC 状态变为 Bound。
  • Pod 从 Pending/ContainerCreating 变为 Running。
  • Pod 事件中不再出现新的 mount/attach 错误。
  • 应用可以正常读写挂载目录。

预防措施

  • 为常用存储类型维护清晰的 StorageClass。
  • PVC 模板里显式写明 storageClassName 和 accessModes。
  • 对 CSI 组件状态建立告警。
  • 对存储后端容量、权限、网络连通性做监控。
  • StatefulSet 上线前先用测试 Pod 验证 PVC 挂载。

相关笔记