容器与云原生 / 系统课时
排查 PVC 删除与资源残留
排查 PVC 删除与资源残留
PVC 长时间停在删除中,或 Kubernetes 对象已经消失但后端卷仍存在,通常不是“删不掉”这么简单,而是删除链路中的保护条件、CSI 回收动作或后端依赖尚未完成。本课按证据链区分正常保护、控制器故障与真实资源泄漏,并给出安全的修复顺序。
学习目标
- 根据
deletionTimestamp、finalizer 与引用关系判断 PVC 为什么仍未删除 - 沿 PVC、PV、VolumeAttachment、CSI 控制器与后端卷定位阻塞点
- 在不制造数据丢失或新泄漏的前提下完成清理并验证结果
先区分对象删除与后端回收
删除 PVC 时,API Server 会先写入 metadata.deletionTimestamp。只要 metadata.finalizers 仍有条目,对象就会继续存在。常见的 kubernetes.io/pvc-protection 表示仍有 Pod 使用该 PVC;PV 上的 kubernetes.io/pv-protection 则避免仍与 PVC 绑定的卷被过早删除。
对于回收策略为 Delete 的 CSI PV,Kubernetes 与 external-provisioner 还可能通过 external-provisioner.volume.kubernetes.io/finalizer 等机制,等待后端 DeleteVolume 成功后再移除 PV。因此,“PV 还在且 finalizer 未清”通常是在保存清理状态和故障证据,不应先手工删除 finalizer。
另一类故障恰好相反:Kubernetes 中 PVC/PV 已删除,但存储后端仍能看到卷或快照。这才属于资源残留,需要使用 PV 的 spec.csi.volumeHandle、驱动名以及后端标签或元数据做反向核对。

沿删除链路收集证据
先固定 PVC、PV、驱动和后端卷句柄,再检查 attachment 与 snapshot content。下面的命令假设故障 PVC 仍存在;把 demo 和 data 换成实际命名空间与 PVC 名称。
NS="demo"
PVC="data"
kubectl get pvc "$PVC" -n "$NS" -o custom-columns=NAME:.metadata.name,DELETION:.metadata.deletionTimestamp,FINALIZERS:.metadata.finalizers,PV:.spec.volumeName
PV="$(kubectl get pvc "$PVC" -n "$NS" -o jsonpath='{.spec.volumeName}')"
if [ -z "$PV" ]; then
echo "PVC has no bound PV"
exit 1
fi
kubectl get pv "$PV" -o custom-columns=NAME:.metadata.name,PHASE:.status.phase,RECLAIM:.spec.persistentVolumeReclaimPolicy,DELETION:.metadata.deletionTimestamp,FINALIZERS:.metadata.finalizers
DRIVER="$(kubectl get pv "$PV" -o jsonpath='{.spec.csi.driver}')"
HANDLE="$(kubectl get pv "$PV" -o jsonpath='{.spec.csi.volumeHandle}')"
kubectl get csidriver "$DRIVER" -o custom-columns=DRIVER:.metadata.name,ATTACH_REQUIRED:.spec.attachRequired
kubectl get volumeattachment -o custom-columns=NAME:.metadata.name,PV:.spec.source.persistentVolumeName,NODE:.spec.nodeName,ATTACHED:.status.attached,FINALIZERS:.metadata.finalizers | grep -F "$PV" || true
if kubectl api-resources --api-group=snapshot.storage.k8s.io -o name | grep -q '^volumesnapshotcontents'; then
kubectl get volumesnapshotcontent -o custom-columns=NAME:.metadata.name,VOLUME_HANDLE:.spec.source.volumeHandle,SNAPSHOT_HANDLE:.status.snapshotHandle,POLICY:.spec.deletionPolicy | grep -F "$HANDLE" || true
fi
printf 'driver=%s volumeHandle=%s\n' "$DRIVER" "$HANDLE"预期输出
NAME DELETION FINALIZERS PV
data <TIME> [kubernetes.io/pvc-protection] <PV_NAME>
NAME PHASE RECLAIM DELETION FINALIZERS
<PV_NAME> <VALUE> Delete <TIME> [<FINALIZER_LIST>]
DRIVER ATTACH_REQUIRED
<CSI_DRIVER> <VALUE>
<VOLUME_ATTACHMENT_IF_ANY>
<VOLUME_SNAPSHOT_CONTENT_IF_ANY>
driver=<CSI_DRIVER> volumeHandle=<VOLUME_HANDLE>实际时间、阶段、finalizer 列表以及是否存在 VolumeAttachment/VolumeSnapshotContent 会不同。接着运行 kubectl describe pvc 与 kubectl describe pv 查看 Events。若 attachRequired 为 false,没有 VolumeAttachment 是正常现象;若 CSIDriver 对象不存在,则还应检查驱动注册与控制器部署状态。
按阻塞点修复
如果 PVC 被 kubernetes.io/pvc-protection 挡住,先找到仍引用它的 Pod 或上层工作负载。即使 Pod 已进入 Terminating,只要对象仍存在且引用 PVC,保护条件就可能尚未解除。应先让工作负载真正退出或修改卷引用,再等待保护控制器重试。
如果 VolumeAttachment 仍显示 attached,先确认业务 Pod 已停止使用卷,再检查 CSI controller 中 external-attacher 与驱动日志,以及后端是否仍把卷挂在对应节点。节点失联、detach RPC 失败或 external-attacher 不健康都可能留下 attachment;修复控制器或后端状态后,应优先让控制器自行 reconcile。
如果 PV 使用 Delete 且 provisioner finalizer 长时间存在,重点检查 external-provisioner 与 CSI driver 的 DeleteVolume 失败原因。常见来源包括驱动控制器不可用、凭据失效、后端 API 超时,以及后端仍存在快照、克隆或 attachment 依赖。某些存储系统会拒绝删除仍被这些对象引用的源卷,此时应先处理依赖。
若回收策略本来就是 Retain,PVC 删除后 PV 与后端卷继续存在是设计行为,不应按泄漏处理。真正需要回收时,应按存储系统运维流程确认数据已备份或无保留价值,再手工处理 PV 和后端资产。
验证 Kubernetes 与后端一致
完成修复后,同时验证 API 对象、attachment 和存储后端。对于 Delete,PVC、PV 和相关 VolumeAttachment 最终都应消失,后端卷也应不存在;对于 Retain,PVC 消失而 PV 与后端卷保留才是正确结果。
kubectl get pvc "$PVC" -n "$NS" --ignore-not-found
kubectl get pv "$PV" --ignore-not-found
kubectl get volumeattachment -o custom-columns=NAME:.metadata.name,PV:.spec.source.persistentVolumeName,NODE:.spec.nodeName,ATTACHED:.status.attached | grep -F "$PV" || true预期结果
Delete 策略且清理完成:三项检查均无匹配输出。
Retain 策略:PVC 无输出;PV 仍存在,后端卷也应按保留策略存在。最后再用存储后端的管理工具按 <VOLUME_HANDLE> 查询一次。Kubernetes 对象与后端资产必须同时符合既定回收策略;只看 PVC 是否消失,无法证明清理已经完成。