容器与云原生 / 系统课时

排查 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 删除与资源残留证据链

沿删除链路收集证据

先固定 PVC、PV、驱动和后端卷句柄,再检查 attachment 与 snapshot content。下面的命令假设故障 PVC 仍存在;把 demo 和 data 换成实际命名空间与 PVC 名称。

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

预期输出

text
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 与后端卷保留才是正确结果。

bash
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

预期结果

text
Delete 策略且清理完成:三项检查均无匹配输出。
Retain 策略:PVC 无输出;PV 仍存在,后端卷也应按保留策略存在。

最后再用存储后端的管理工具按 <VOLUME_HANDLE> 查询一次。Kubernetes 对象与后端资产必须同时符合既定回收策略;只看 PVC 是否消失,无法证明清理已经完成。

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

目录与阅读设置

阅读设置

17

记录一个想法

排查 PVC 删除与资源残留

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

登录哪都通