容器与云原生 / 系统课时

建立 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。

kubectl 存储排障对象与证据链

先在同一个 shell 会话中设置变量;后续命令复用这些变量。如果 PVC 还处于 Pending,PV 为空本身就是重要证据,不要随手挑一个 PV 继续查。

bash
# 用业务对象名建立最小排障上下文,并从 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>}"

预期输出

text
PV=<PV_NAME>

若尚未绑定,最后一行会是 PV=<UNBOUND>。

用 get 采集状态快照

get 适合回答“现在是什么状态”。先看 PVC 和 Pod,再在 PV 已存在时读取 PV;最后列出 VolumeAttachment 并按 PV 名人工匹配。不要把“没有 VolumeAttachment”直接等同于 attach 失败,因为 CSIDriver.spec.attachRequired=false 时不创建它是正常的。

bash
# 先采集对象当前状态;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

预期输出

text
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 等阶段的失败。

bash
# 先看对象详情,再分别按 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

预期输出

text
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 的节点和卷引用。

bash
# 抽取能直接建立因果链的字段,避免在整份 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}'

预期输出

text
<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 内容,只保存本课需要的资源状态和命名空间事件。

bash
# 将同一时刻的核心对象和事件写入一个可复查的证据文件。
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

预期输出

text
storage-evidence-<TIME>.txt

这套工具链的价值在于顺序固定:先确定 PVC 是否绑定,再确定 Pod 被调度到哪里,然后判断是否应该存在 VolumeAttachment,最后用事件把失败落到 provisioning、scheduling、attach 或 mount 的具体阶段。

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

目录与阅读设置

阅读设置

17

记录一个想法

建立 kubectl 存储检查工具链

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

登录哪都通