Kubernetes CSI快照恢复失败排查-4步定位

Kubernetes CSI快照恢复失败时，先不要删除 VolumeSnapshot 或 PVC 重试。快照恢复链路包含 VolumeSnapshot、VolumeSnapshotContent、VolumeSnapshotClass、CSI driver、StorageClass 和 PVC 绑定，任一环节不匹配都可能让恢复卡住。正确做法是先确认对象状态，再看事件和驱动能力。

如果你的问题发生在普通 PVC 绑定阶段，可先参考站内关于 PVC Pending 与 StorageClass 的排查文章；本文只聚焦 CSI 快照恢复链路。

图1：从 VolumeSnapshot 状态到 PVC 绑定失

第一步：确认快照 Ready

Kubernetes CSI Volume Snapshots 官方文档[1]说明，快照能力依赖 CRD、snapshot controller 和 CSI driver。排查时先看对象状态，而不是只看 YAML 是否创建成功。

kubectl get volumesnapshot -A
kubectl describe volumesnapshot my-snapshot -n app
kubectl get volumesnapshotcontent
kubectl describe volumesnapshotcontent <content-name>

重点看：

• `readyToUse` 是否为 true。
• `VolumeSnapshotContent` 是否已绑定。
• 事件中是否出现 driver、class 或 deletionPolicy 相关错误。
• 快照所在 namespace 与恢复 PVC 所在 namespace 是否符合预期。

如果快照没有 Ready，PVC 恢复通常不会成功。此时应先查 snapshot controller 和 CSI driver 日志。

第二步：核对快照类

VolumeSnapshotClass 指定快照由哪个 driver 处理。如果 class 与实际存储驱动不匹配，或者集群里没有对应 driver，快照对象可能创建出来但无法完成。

图2：VolumeSnapshot、VolumeSnapsho

kubectl get volumesnapshotclass
kubectl describe volumesnapshotclass <class-name>
kubectl get csidriver
kubectl get pods -A | grep -i snapshot

Kubernetes CSI external-snapshotter 官方文档[3]说明，Kubernetes 快照能力通常由 snapshot controller、CRD 和 CSI 驱动侧组件协同完成；不同存储厂商的支持能力和参数可能不同，应以具体 driver 文档为准。

常见问题包括：

• VolumeSnapshotClass 的 driver 名称写错。
• 存储驱动只支持创建快照，不支持从快照恢复。
• snapshot CRD 或 controller 版本与集群版本不匹配。
• 删除策略不符合恢复预期。

第三步：检查恢复 PVC

从快照恢复 PVC 时，需要在 PVC 中指定 dataSource。恢复后的 PVC 还要通过 StorageClass 创建实际卷，因此 StorageClass、访问模式、容量和拓扑约束都可能影响绑定；PVC 与 PV 的绑定行为可参考 Kubernetes Persistent Volumes 官方文档[2]。

示例：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: restore-pvc
spec:
  storageClassName: fast-csi
  dataSource:
    name: my-snapshot
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi

上线前至少检查：

• PVC 的 `storageClassName` 是否与恢复目标一致。
• 请求容量是否不小于源卷快照容量。
• accessModes 是否被驱动支持。
• 目标节点拓扑是否满足存储后端约束。
• PVC 事件是否提示 dataSource、provisioning 或 binding 错误。

第四步：验证恢复后的数据和应用挂载

PVC 绑定成功不等于恢复完成。还要验证数据是否符合预期、应用是否能挂载、权限和文件系统是否正常。

图3：从快照 Ready、PVC 创建、Pod 挂载到数据验证

可以用一个临时 Pod 挂载恢复后的 PVC 做只读检查，确认目录结构、关键文件和应用启动前置条件。不要在确认前让生产应用直接写入恢复卷，否则可能破坏排查现场。

关键结论：Kubernetes CSI 快照恢复的验收对象是“恢复后的卷可被应用安全使用”，不是 PVC 进入 Bound 状态。

小结

Kubernetes CSI快照恢复失败可以按 4 步定位：快照对象是否 Ready，VolumeSnapshotClass 是否匹配 driver[3]，恢复 PVC 的 StorageClass 和 dataSource 是否正确[2]，恢复后数据是否能被应用安全挂载。不同 CSI driver 行为存在差异，涉及参数和能力边界时必须回到对应官方文档确认[3]。

参考资料

• [1] Kubernetes Volume Snapshots – 官方文档
• [2] Kubernetes Persistent Volumes – 官方文档
• [3] Kubernetes CSI external-snapshotter – 官方文档

常见问题

1. 可以删除 VolumeSnapshotContent 吗？

不建议在未确认删除策略和后端快照状态前删除。VolumeSnapshotContent 可能关联真实后端快照，误删可能影响恢复来源。应先导出对象状态和事件，再按存储驱动文档处理。

2. VolumeSnapshot Ready 了，为什么 PVC 仍然 Pending？

Ready 只说明快照创建完成。PVC 仍然需要 StorageClass、容量、访问模式和拓扑满足要求。如果 provisioner 无法从 dataSource 创建卷，PVC 仍会 Pending。

3. 快照能跨 namespace 恢复吗？

通常要看快照对象、引用方式和集群策略。不要默认跨 namespace 可用。生产环境建议先在同 namespace 验证，再按平台策略设计跨命名空间恢复流程。

4. CSI 快照能替代备份吗？

不能完全替代。快照通常更适合快速恢复某个卷状态，但备份还涉及跨集群、跨区域、保留周期、应用一致性和恢复演练。关键业务应同时设计备份和恢复演练。