容器与云原生 / 系统课时

排查扩容与快照失败

排查扩容与快照失败

CSI 扩容和快照都跨越 Kubernetes API、sidecar、CSI 驱动与存储后端,扩容还多一个节点文件系统阶段。排障的关键不是反复重建 PVC,而是先判断请求卡在哪一层,再检查对应控制器、驱动能力和后端限制。本课给出一条可直接执行的定位路径。

学习目标

  • 把 PVC 扩容拆成控制面扩容与节点扩容两个阶段定位
  • 根据 VolumeSnapshot、VolumeSnapshotContent 与 VolumeSnapshotClass 判断快照卡点
  • 结合 sidecar、CSI 能力、后端限制和文件系统状态选择正确修复动作

把扩容与快照拆成明确阶段

PVC 扩容首先要求 StorageClass 的 allowVolumeExpansion 为 true。用户增大 spec.resources.requests.storage 后,external-resizer 观察到变化并与 CSI 驱动协作执行控制面扩容;成功后,PV 容量会更新。对于需要节点侧处理的文件系统卷,kubelet 还会调用 CSI NodeExpandVolume,使设备或文件系统看到新容量。

因此,请求容量已经变大但 PV/PVC 实际容量没变,优先看 external-resizer、ControllerExpandVolume 与后端限制;PV 容量已经变大但容器内文件系统仍是旧大小,则优先看 kubelet、CSI Node 插件与 NodeExpandVolume。Kubernetes 支持的常见文件系统扩容包括 XFS、Ext3 和 Ext4;原始 Block 卷没有“扩文件系统”这一步。

快照则是另一条链路:VolumeSnapshot 由 snapshot-controller 处理并绑定 VolumeSnapshotContent,驱动侧的 csi-snapshotter 根据 content 调用 CSI CreateSnapshot 或 DeleteSnapshot。要成功创建动态快照,集群必须安装快照 CRD/控制器,VolumeSnapshotClass 的 driver 要与源 PV 的 CSI driver 匹配,CSI 驱动还必须支持快照能力。

CSI 扩容与快照故障阶段

从 PVC 状态判断扩容卡点

先看期望容量、当前容量、StorageClass 开关和 Events。不要只盯着 PVC 的 spec:spec 表示用户想要什么,status.capacity 才表示 Kubernetes 当前确认的容量。

bash
NS="demo"
PVC="data"

SC="$(kubectl get pvc "$PVC" -n "$NS" -o jsonpath='{.spec.storageClassName}')"
PV="$(kubectl get pvc "$PVC" -n "$NS" -o jsonpath='{.spec.volumeName}')"
DRIVER="$(kubectl get pv "$PV" -o jsonpath='{.spec.csi.driver}')"

kubectl get storageclass "$SC"   -o custom-columns=NAME:.metadata.name,ALLOW_EXPANSION:.allowVolumeExpansion,PROVISIONER:.provisioner

kubectl get pvc "$PVC" -n "$NS"   -o custom-columns=NAME:.metadata.name,REQUESTED:.spec.resources.requests.storage,CAPACITY:.status.capacity.storage,ALLOCATED:.status.allocatedResources.storage,RESIZE_STATUS:.status.allocatedResourceStatuses.storage

kubectl describe pvc "$PVC" -n "$NS"
printf 'pv=%s driver=%s\n' "$PV" "$DRIVER"

预期输出

text
NAME        ALLOW_EXPANSION   PROVISIONER
<SC_NAME>   true              <CSI_DRIVER>
NAME   REQUESTED   CAPACITY   ALLOCATED   RESIZE_STATUS
data   <VALUE>     <VALUE>    <VALUE>     <VALUE>
...
Events:
  <RESIZE_RELATED_EVENTS>
pv=<PV_NAME> driver=<CSI_DRIVER>

健康配置下 ALLOW_EXPANSION 应为 true。扩容过程中 REQUESTED 可以暂时大于 CAPACITY;具体的 ALLOCATED、RESIZE_STATUS 与 Events 会随 Kubernetes 版本和扩容阶段变化。若修改 PVC 时直接被拒绝,先修正 StorageClass 或驱动支持问题,不要删除重建 PVC。

控制面失败时,查看 CSI controller Pod 中 resizer 容器和驱动容器的同一时间段日志,重点寻找 ControllerExpandVolume、权限、配额、最大卷大小和后端错误。节点阶段失败时,转而查看运行该 PVC 的 Pod Events、对应节点 kubelet 日志与 CSI Node 插件日志,重点定位 NodeExpandVolume、设备识别和文件系统扩展错误。

如果一次请求因为后端容量限制失败,当前 Kubernetes 允许把失败的扩容请求改成一个比“上一次请求值”更小、但仍大于当前 status.capacity 的值后重试。Kubernetes 不支持把 PVC 缩到当前实际容量以下。

用对象关系定位快照失败

快照 API 不是仅靠 CSI 驱动就会自动出现;先确认 snapshot.storage.k8s.io 资源已经注册。随后检查 VolumeSnapshot 是否绑定 content、是否 readyToUse,再核对 VolumeSnapshotClass 与源 PV 的 driver。

bash
NS="demo"
PVC="data"
SNAP="data-snapshot"

kubectl api-resources --api-group=snapshot.storage.k8s.io

if kubectl api-resources --api-group=snapshot.storage.k8s.io -o name | grep -q '^volumesnapshots'; then
  PV="$(kubectl get pvc "$PVC" -n "$NS" -o jsonpath='{.spec.volumeName}')"
  PV_DRIVER="$(kubectl get pv "$PV" -o jsonpath='{.spec.csi.driver}')"

  kubectl get volumesnapshot "$SNAP" -n "$NS" -o custom-columns=NAME:.metadata.name,CLASS:.spec.volumeSnapshotClassName,CONTENT:.status.boundVolumeSnapshotContentName,READY:.status.readyToUse,ERROR:.status.error.message

  CONTENT="$(kubectl get volumesnapshot "$SNAP" -n "$NS" -o jsonpath='{.status.boundVolumeSnapshotContentName}')"
  CLASS="$(kubectl get volumesnapshot "$SNAP" -n "$NS" -o jsonpath='{.spec.volumeSnapshotClassName}')"

  if [ -n "$CONTENT" ]; then
    kubectl get volumesnapshotcontent "$CONTENT" -o custom-columns=NAME:.metadata.name,SOURCE_VOLUME:.spec.source.volumeHandle,SNAPSHOT_HANDLE:.status.snapshotHandle,READY:.status.readyToUse,ERROR:.status.error.message
  else
    echo "content=<none>"
  fi

  if [ -n "$CLASS" ]; then
    kubectl get volumesnapshotclass "$CLASS" -o custom-columns=NAME:.metadata.name,DRIVER:.driver,DELETION_POLICY:.deletionPolicy
  else
    echo "class=<none>"
  fi

  printf 'sourcePVDriver=%s\n' "$PV_DRIVER"
else
  echo "snapshot-api=missing"
fi

预期输出

text
NAME                                                SHORTNAMES   APIVERSION                    NAMESPACED   KIND
volumesnapshotclasses.snapshot.storage.k8s.io       <VALUE>      snapshot.storage.k8s.io/<VERSION>   false   VolumeSnapshotClass
volumesnapshotcontents.snapshot.storage.k8s.io      <VALUE>      snapshot.storage.k8s.io/<VERSION>   false   VolumeSnapshotContent
volumesnapshots.snapshot.storage.k8s.io             <VALUE>      snapshot.storage.k8s.io/<VERSION>   true    VolumeSnapshot
NAME            CLASS          CONTENT            READY   ERROR
data-snapshot   <CLASS_NAME>   <CONTENT_NAME>     <VALUE> <VALUE>
NAME             SOURCE_VOLUME     SNAPSHOT_HANDLE     READY   ERROR
<CONTENT_NAME>   <VOLUME_HANDLE>   <SNAPSHOT_HANDLE>   <VALUE> <VALUE>
NAME           DRIVER         DELETION_POLICY
<CLASS_NAME>   <CSI_DRIVER>   <Delete_OR_Retain>
sourcePVDriver=<CSI_DRIVER>

如果第一条命令没有列出三类 snapshot 资源,先补齐快照 CRD 与 snapshot-controller;如果 VolumeSnapshot 一直没有 content,查看 snapshot-controller Events/日志;如果已有 content 但 readyToUse 不成立,重点查 csi-snapshotter、CSI driver 的 CreateSnapshot 以及后端快照限制。VolumeSnapshotClass 的 driver 必须与源卷 CSI driver 对应。

deletionPolicy 还决定删除快照对象后的资源归宿:Delete 会要求删除关联的 VolumeSnapshotContent 与后端快照,Retain 则保留 content 和后端快照。把 Retain 后仍存在的快照误判成泄漏,会导致错误清理。

按阶段修复并做闭环验收

扩容修复后,应同时满足三层结果:PVC 的 status.capacity 达到目标值、后端卷容量已经扩大、容器或节点看到的可用容量也已更新。若前两项成功而文件系统仍旧,问题仍在节点阶段,不能因为 PVC 显示新容量就结束排障。

快照修复后,VolumeSnapshot 应最终 readyToUse=true,VolumeSnapshotContent 也应具备有效的 snapshot handle,且后端能查询到对应快照。删除测试则必须按 VolumeSnapshotClass 的 deletionPolicy 验收:Delete 期望后端快照消失,Retain 期望它继续存在。

扩容和快照的共同排障原则是:先确定失败阶段,再只检查负责该阶段的组件。这样可以把“CSI 存储失败”从一个笼统结论,收敛为 external-resizer、kubelet/NodeExpandVolume、snapshot-controller、csi-snapshotter、驱动能力或存储后端中的具体一环。

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

目录与阅读设置

阅读设置

17

记录一个想法

排查扩容与快照失败

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

登录哪都通