容器与云原生 / 系统课时

排查动态供应失败

排查动态供应失败

动态供应失败时,最有效的做法不是遍历所有 CSI 组件,而是把 PVC 事件中的 ProvisioningFailed 作为入口,沿 external-provisioner → CSI Controller CreateVolume → 后端存储逐层收窄。这样可以快速区分 Kubernetes RBAC、后端认证、参数、配额与容量问题。

学习目标

  • 从 PVC 事件确认故障已经进入动态供应链,而不是正常的延迟绑定。
  • 关联 external-provisioner 与 CSI Driver 日志,定位 CreateVolume 的真实错误。
  • 根据错误码和后端证据修复权限、凭据、参数或配额,并验证卷成功创建。

先确认故障位于供应阶段

先查看 PVC 事件和 StorageClass 的 provisioner。如果事件只是提示等待首个消费者,应先回到 Pod 调度与拓扑;只有看到反复供应尝试、ProvisioningFailed 或 CSI gRPC 错误,才值得继续追 Controller 日志。

bash
kubectl describe pvc -n <NS> <PVC>
kubectl get sc <SC> -o jsonpath='provisioner={.provisioner}{"\n"}binding={.volumeBindingMode}{"\n"}'

预期输出

text
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,还是存储后端。

CSI 动态供应失败证据链

从 external-provisioner 追到 CreateVolume

先找到包含 csi-provisioner 的 Controller Pod,再同时读取 sidecar 和驱动容器日志。external-provisioner 负责把 PVC 转成 CSI 请求;真正访问云盘、阵列或分布式存储 API 的通常是 CSI Driver。

bash
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

预期输出

text
<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 返回认证或权限错误时。

bash
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>

预期输出

text
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 或其他后端标识。

bash
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"}'

预期输出

text
phase=Bound
pv=<PV_NAME>
driver=<CSI_DRIVER>
handle=<VOLUME_HANDLE>

到这里说明动态供应已经完成。如果 PVC 已 Bound,后续 Pod 仍失败,应把排查边界转向 ControllerPublishVolume、NodeStageVolume 或 NodePublishVolume,不要继续在 CreateVolume 上重复查找根因。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查动态供应失败

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通