容器与云原生 / 系统课时
排查动态供应失败
排查动态供应失败
动态供应失败时,最有效的做法不是遍历所有 CSI 组件,而是把 PVC 事件中的 ProvisioningFailed 作为入口,沿 external-provisioner → CSI Controller CreateVolume → 后端存储逐层收窄。这样可以快速区分 Kubernetes RBAC、后端认证、参数、配额与容量问题。
学习目标
- 从 PVC 事件确认故障已经进入动态供应链,而不是正常的延迟绑定。
- 关联 external-provisioner 与 CSI Driver 日志,定位
CreateVolume的真实错误。 - 根据错误码和后端证据修复权限、凭据、参数或配额,并验证卷成功创建。
先确认故障位于供应阶段
先查看 PVC 事件和 StorageClass 的 provisioner。如果事件只是提示等待首个消费者,应先回到 Pod 调度与拓扑;只有看到反复供应尝试、ProvisioningFailed 或 CSI gRPC 错误,才值得继续追 Controller 日志。
kubectl describe pvc -n <NS> <PVC>
kubectl get sc <SC> -o jsonpath='provisioner={.provisioner}{"\n"}binding={.volumeBindingMode}{"\n"}'预期输出
Events:
Warning ProvisioningFailed <TIME> <PROVISIONER> failed to provision volume with StorageClass "<SC>": rpc error: code = <CODE> desc = <DETAIL>
provisioner=<CSI_DRIVER>
binding=<MODE>不同 CSI 驱动的事件文本会有差异,但应记录三项证据:事件 Reason、gRPC code 和 desc。它们决定下一步是查 Kubernetes 权限、CSI Controller,还是存储后端。

从 external-provisioner 追到 CreateVolume
先找到包含 csi-provisioner 的 Controller Pod,再同时读取 sidecar 和驱动容器日志。external-provisioner 负责把 PVC 转成 CSI 请求;真正访问云盘、阵列或分布式存储 API 的通常是 CSI Driver。
kubectl get pods -A -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,CONTAINERS:.spec.containers[*].name' | grep -E 'csi|provisioner'
kubectl logs -n <CSI_NS> <CONTROLLER_POD> -c csi-provisioner --since=10m
kubectl logs -n <CSI_NS> <CONTROLLER_POD> -c <DRIVER_CONTAINER> --since=10m预期输出
<CSI_NS> <CONTROLLER_POD> csi-provisioner,<DRIVER_CONTAINER>,...
...
CreateVolume <REQUEST_OR_PVC_REFERENCE>
rpc error: code = <CODE> desc = <DETAIL>容器名和日志格式由驱动实现决定;如果 Pod 中的 provisioner sidecar 不是 csi-provisioner 这个容器名,应使用实际名称。关键是用相同时间窗口和 PVC/PV 名称把两侧日志关联起来。
用错误码缩小根因
gRPC code 是分流线索,不是最终结论。最终仍要结合 desc、驱动日志和后端审计确认。
| 线索 | 优先检查 |
|---|---|
Unauthenticated / PermissionDenied |
驱动使用的 Secret、Workload Identity/云 IAM、后端账号权限 |
InvalidArgument |
StorageClass 参数、卷类型、加密或拓扑参数是否被当前驱动支持 |
ResourceExhausted |
租户配额、区域容量、存储池剩余空间、卷数量上限 |
Unavailable / DeadlineExceeded |
Controller 到后端 API 的网络、DNS、TLS、后端健康与过载 |
Kubernetes forbidden |
external-provisioner 的 ServiceAccount、ClusterRole 与 ClusterRoleBinding |
Kubernetes RBAC 与后端认证要分开看。前者通常在 external-provisioner 访问 Kubernetes API 时直接出现 forbidden;后者则多出现在 CSI Driver 调用存储后端、并向 CreateVolume 返回认证或权限错误时。
kubectl auth can-i watch persistentvolumeclaims --all-namespaces --as=system:serviceaccount:<CSI_NS>:<PROVISIONER_SA>
kubectl auth can-i create persistentvolumes --as=system:serviceaccount:<CSI_NS>:<PROVISIONER_SA>
kubectl get secret -n <SECRET_NS> <SECRET_NAME>预期输出
yes
yes
NAME TYPE DATA AGE
<SECRET_NAME> <TYPE> <N> <TIME>Secret 存在只证明 Kubernetes 对象可读,不证明其中凭据仍有效;云 IAM、阵列账号、证书有效期或后端租户权限仍需用该 CSI 驱动对应的后台或审计日志验证。
修复后让原请求完成重试
如果问题是 RBAC,应修正 provisioner 的角色绑定;如果是驱动凭据或云 IAM,应恢复 CSI Controller 使用的身份;如果是参数错误,应改用驱动支持的 StorageClass;如果是配额或容量,则扩容、释放配额或选择有容量的存储池/拓扑区域。
多数 external-provisioner 会对未完成的 PVC 继续重试,因此凭据、网络或配额修复后,通常可以直接观察同一个 PVC 是否转为 Bound。只有 PVC 本身引用了错误的 StorageClass 或声明条件就不合理时,才应按变更方案创建正确的新声明,而不是靠反复删除对象碰运气。
验证 PV 与后端卷已经建立对应关系
最终应看到 PVC 绑定到 PV,并且该 PV 的 CSI 字段指向预期驱动和后端卷句柄。volumeHandle 的格式由驱动定义,实际值可能是云盘 ID、阵列卷 ID 或其他后端标识。
PV_NAME=$(kubectl get pvc -n <NS> <PVC> -o jsonpath='{.spec.volumeName}')
kubectl get pvc -n <NS> <PVC> -o jsonpath='phase={.status.phase}{"\n"}pv={.spec.volumeName}{"\n"}'
kubectl get pv "$PV_NAME" -o jsonpath='driver={.spec.csi.driver}{"\n"}handle={.spec.csi.volumeHandle}{"\n"}'预期输出
phase=Bound
pv=<PV_NAME>
driver=<CSI_DRIVER>
handle=<VOLUME_HANDLE>到这里说明动态供应已经完成。如果 PVC 已 Bound,后续 Pod 仍失败,应把排查边界转向 ControllerPublishVolume、NodeStageVolume 或 NodePublishVolume,不要继续在 CreateVolume 上重复查找根因。