容器与云原生 / 系统课时
排查扩容与快照失败
排查扩容与快照失败
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 驱动还必须支持快照能力。

从 PVC 状态判断扩容卡点
先看期望容量、当前容量、StorageClass 开关和 Events。不要只盯着 PVC 的 spec:spec 表示用户想要什么,status.capacity 才表示 Kubernetes 当前确认的容量。
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"预期输出
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。
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预期输出
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、驱动能力或存储后端中的具体一环。