容器与云原生 / 系统课时
建立 kubectl 存储检查工具链
建立 kubectl 存储检查工具链
存储故障排查最容易浪费时间的地方,是在 PVC、PV、Pod、VolumeAttachment 之间来回猜。这里建立一套固定的 kubectl 采证顺序:先确定对象关系,再看状态、事件和关键字段,最后把证据一次性保存下来。
学习目标
- 用
get和jsonpath串起 Pod、PVC、PV 与 CSI 驱动信息 - 用
describe和events区分绑定、调度、附加与挂载阶段的异常 - 识别 VolumeAttachment 缺失到底是正常行为还是故障信号
从 Pod 建立存储对象链
先固定命名空间、PVC 和 Pod。PVC 绑定后,spec.volumeName 给出 PV 名称;PV 的 spec.csi.driver 和 volumeHandle 指向具体 CSI 驱动与后端卷标识;Pod 则提供最终调度节点。若驱动要求 attach,还会出现指向该 PV 和节点的 VolumeAttachment。

先在同一个 shell 会话中设置变量;后续命令复用这些变量。如果 PVC 还处于 Pending,PV 为空本身就是重要证据,不要随手挑一个 PV 继续查。
# 用业务对象名建立最小排障上下文,并从 PVC 解析绑定的 PV。
NS='<NAMESPACE>'
PVC='<PVC_NAME>'
POD='<POD_NAME>'
PV=$(kubectl get pvc $PVC -n $NS -o jsonpath='{.spec.volumeName}')
printf 'PV=%s\n' "${PV:-<UNBOUND>}"预期输出
PV=<PV_NAME>若尚未绑定,最后一行会是 PV=<UNBOUND>。
用 get 采集状态快照
get 适合回答“现在是什么状态”。先看 PVC 和 Pod,再在 PV 已存在时读取 PV;最后列出 VolumeAttachment 并按 PV 名人工匹配。不要把“没有 VolumeAttachment”直接等同于 attach 失败,因为 CSIDriver.spec.attachRequired=false 时不创建它是正常的。
# 先采集对象当前状态;PVC 未绑定时避免误把所有 PV 当成目标。
kubectl get pvc $PVC -n $NS -o wide
kubectl get pod $POD -n $NS -o wide
if [ -n "$PV" ]; then kubectl get pv $PV -o wide; else echo 'PVC has no bound PV'; fi
kubectl get volumeattachment -o custom-columns=NAME:.metadata.name,PV:.spec.source.persistentVolumeName,ATTACHER:.spec.attacher,NODE:.spec.nodeName,ATTACHED:.status.attached预期输出
NAME STATUS VOLUME STORAGECLASS <OTHER_COLUMNS>
<PVC_NAME> <STATUS> <PV_NAME> <SC_NAME> <VALUE>
NAME READY STATUS NODE
<POD_NAME> <READY> <STATUS> <NODE>
NAME CAPACITY ACCESS MODES STATUS CLAIM
<PV_NAME> <SIZE> <MODES> <STATUS> <NAMESPACE>/<PVC_NAME>
NAME PV ATTACHER NODE ATTACHED
<VOLUMEATTACHMENT> <PV_NAME> <DRIVER_NAME> <NODE> <true|false>实际列会随 Kubernetes 版本和对象状态略有差异;关键是保留名称、状态、绑定关系和节点,不要只截取一句错误信息。
用 describe 与 events 还原时间线
describe 用来补齐 Conditions、挂载信息和对象相关 Events;kubectl get events 则适合按时间排序。PVC 侧常暴露 provisioning 与 binding 问题,Pod 侧更容易看到调度、AttachVolume、MountVolume 等阶段的失败。
# 先看对象详情,再分别按 PVC 与 Pod 名称拉取时间线。
kubectl describe pvc $PVC -n $NS
kubectl describe pod $POD -n $NS
kubectl get events -n $NS --field-selector involvedObject.name=$PVC --sort-by=.lastTimestamp
kubectl get events -n $NS --field-selector involvedObject.name=$POD --sort-by=.lastTimestamp预期输出
Name: <PVC_NAME>
Status: <PVC_STATUS>
Volume: <PV_NAME>
Events:
<PVC_EVENT_LINES>
Name: <POD_NAME>
Node: <NODE>
Status: <POD_STATUS>
Events:
<POD_EVENT_LINES>
<TIME> <TYPE> <REASON> <OBJECT> <MESSAGE>看到 FailedScheduling 时先处理拓扑、容量或绑定条件;看到 FailedAttachVolume 再查 VolumeAttachment 和 controller;看到 FailedMount 或 MountVolume 失败,则重点转向节点上的 CSI Node 插件、kubelet 和后端卷可达性。按阶段定位比只搜“error”更可靠。
用 jsonpath 抽取关键字段
当对象 YAML 很长时,jsonpath 适合把关键关系压缩成几行。下面一次提取 PVC 的阶段、PV、StorageClass,PV 的 CSI driver 与 volumeHandle,以及 Pod 的节点和卷引用。
# 抽取能直接建立因果链的字段,避免在整份 YAML 中手工查找。
kubectl get pvc $PVC -n $NS -o jsonpath='{.status.phase}{"\t"}{.spec.volumeName}{"\t"}{.spec.storageClassName}{"\n"}'
if [ -n "$PV" ]; then kubectl get pv $PV -o jsonpath='{.spec.csi.driver}{"\t"}{.spec.csi.volumeHandle}{"\n"}'; fi
kubectl get pod $POD -n $NS -o jsonpath='{.spec.nodeName}{"\n"}{range .spec.volumes[*]}{.name}{"\t"}{.persistentVolumeClaim.claimName}{"\n"}{end}'预期输出
<PVC_PHASE> <PV_NAME> <STORAGE_CLASS>
<DRIVER_NAME> <VOLUME_HANDLE>
<NODE>
<VOLUME_NAME> <PVC_NAME>
<OTHER_VOLUME> <EMPTY>Pod 中非 PVC 类型的卷没有 persistentVolumeClaim.claimName,所以第二列为空是正常现象。这里要关注的是业务卷是否指向预期 PVC,以及该 PVC 最终是否落到正确的 CSI driver。
固化一份证据包
交给同事或进入下一轮排查前,把同一时刻的状态保存为文本,避免后续对象变化导致证据互相矛盾。下面的命令不会导出 Secret 内容,只保存本课需要的资源状态和命名空间事件。
# 将同一时刻的核心对象和事件写入一个可复查的证据文件。
OUT=storage-evidence-$(date +%Y%m%d-%H%M%S).txt
{ kubectl get pvc $PVC -n $NS -o wide; kubectl get pod $POD -n $NS -o wide; [ -z "$PV" ] || kubectl get pv $PV -o wide; kubectl get volumeattachment -o wide; kubectl get events -n $NS --sort-by=.lastTimestamp; } > $OUT
echo $OUT预期输出
storage-evidence-<TIME>.txt这套工具链的价值在于顺序固定:先确定 PVC 是否绑定,再确定 Pod 被调度到哪里,然后判断是否应该存在 VolumeAttachment,最后用事件把失败落到 provisioning、scheduling、attach 或 mount 的具体阶段。