容器与云原生 / 系统课时

编写 CSI 存储故障 Runbook

编写 CSI 存储故障 Runbook

CSI 故障处理最怕“边查边猜”。本节把一次故障处置固化成可执行 Runbook:从症状入口收集证据,设置停止条件,再按故障边界恢复,并用业务验证与升级交接完成闭环。

学习目标

  • 为常见 CSI 故障定义可检索的症状入口和证据清单。
  • 写清停止条件、恢复前提、回退方式与验证步骤。
  • 建立能直接交接给平台、存储或应用团队的升级路径。

用症状入口约束排查范围

Runbook 的入口应写“看到了什么”,不要先写“可能是什么”。值班人员拿到告警后,先把现象归入少量稳定类别,再沿对应证据链排查。

症状入口 第一批证据 优先判断的边界
PVC 长时间 Pending PVC 事件、StorageClass、provisioner 状态 动态供给、容量、拓扑
Pod 出现 FailedAttachVolume Pod 事件、VolumeAttachment、CSI Controller 日志 attach 控制面、后端卷
Pod 出现 FailedMount Pod 事件、CSINode、CSI Node 日志、kubelet 日志 节点插件、挂载、设备
应用出现 I/O error 或只读 Pod/Node 状态、内核与 CSI Node 日志、后端健康 节点、文件系统、存储后端

每个入口还要声明适用范围,例如“仅适用于通过 PVC 使用的 CSI 持久卷”,并记录负责人、最近一次验证日期和对应驱动版本,避免把同一份 Runbook 生搬到不同驱动。

CSI 存储故障 Runbook 决策闭环

固化一份最小证据包

Runbook 不应只写“执行 kubectl 看看”。证据要能回答五个问题:哪个工作负载受影响、PVC 是否已绑定、PV 由哪个 CSI 驱动管理、Pod 是否已调度到节点、错误最早出现在哪一层。先固定对象身份,再补事件、日志和后端状态。

将占位符替换为现场值后执行下面的主示例。它只读取对象,不修改集群状态,适合作为 Runbook 的第一段采证命令。

bash
NS="default"
POD="<POD>"
PVC="<PVC>"

SC="$(kubectl get pvc "$PVC" -n "$NS" -o jsonpath='{.spec.storageClassName}')"
PV="$(kubectl get pvc "$PVC" -n "$NS" -o jsonpath='{.spec.volumeName}')"
NODE="$(kubectl get pod "$POD" -n "$NS" -o jsonpath='{.spec.nodeName}')"
POD_UID="$(kubectl get pod "$POD" -n "$NS" -o jsonpath='{.metadata.uid}')"
PVC_UID="$(kubectl get pvc "$PVC" -n "$NS" -o jsonpath='{.metadata.uid}')"

echo "pod=$NS/$POD uid=$POD_UID node=${NODE:-<UNSCHEDULED>}"
echo "pvc=$PVC uid=$PVC_UID storageClass=${SC:-<EMPTY>} pv=${PV:-<UNBOUND>}"

if [ -n "$PV" ]; then
  PV_UID="$(kubectl get pv "$PV" -o jsonpath='{.metadata.uid}')"
  DRIVER="$(kubectl get pv "$PV" -o jsonpath='{.spec.csi.driver}')"
  echo "pv=$PV uid=$PV_UID driver=${DRIVER:-<NON_CSI_OR_EMPTY>}"
fi

预期输出

text
pod=default/<POD> uid=<POD_UID> node=<NODE>
pvc=<PVC> uid=<PVC_UID> storageClass=<STORAGE_CLASS_OR_EMPTY> pv=<PV>
pv=<PV> uid=<PV_UID> driver=<CSI_DRIVER>

若 PVC 尚未绑定,pv 会显示 <UNBOUND>,且不会输出第三行;若 Pod 尚未调度,node 会显示 <UNSCHEDULED>。实际对象名与 UID 由现场决定。这里必须使用正确的 kubectl get pod 获取节点名,否则后续节点侧证据链就失去可靠来源。

身份固定后,再把 Pod、PVC、PV 的详细状态与事件、相关 StorageClass、CSIDriver、目标节点的 CSINode、适用时的 VolumeAttachment、CSI Controller/Node 日志、kubelet 日志、后端卷状态和近期变更记录加入同一事件时间线。证据应保留原始时间戳和对象 UID,只截取一条错误文案容易丢失重试顺序,也无法判断错误发生在故障之前还是恢复之后。

把恢复动作写成前提、动作与回退

Runbook 中的恢复动作应按故障边界组织,而不是列一串“常用命令”。每个动作至少写清三件事:什么证据满足时才能执行、执行后期待哪个状态改变、失败时如何回退或停止。

故障边界 可接受的恢复方向 不应作为第一动作
CSI Controller/sidecar 异常 先恢复控制面工作负载与依赖,再观察供给或 attach 是否继续推进 删除 PVC/PV 重新来过
单节点 CSI Node 或 kubelet 异常 先确认影响范围,再恢复节点插件;需要迁移时按工作负载和卷语义评估 未确认挂载状态就强制 detach
存储后端不可用或路径异常 由存储侧恢复卷、链路或服务,并保持 Kubernetes 侧证据 在集群侧反复重建对象制造更多重试
拓扑或调度约束不满足 修正错误的节点标签、亲和性或存储拓扑配置,并重新验证调度条件 为了“让 Pod 跑起来”随意放宽数据安全约束

用验证与升级路径完成闭环

恢复后按同一顺序验证:PVC/PV 关系正常,Pod 调度和 Ready 状态恢复;若驱动需要 attach,相关 attach 状态不再报错;事件中不再产生同类失败;应用使用安全的读写或一致性检查确认数据可用;最后在组织规定的 <WINDOW> 观察窗口内确认错误率、延迟和重试没有重新恶化。

生产验证不要为了“证明能写”随意修改业务数据。优先使用应用已有的健康检查、只读校验或专用测试对象;确需写入时,必须定义测试数据、清理方式和可接受影响。

升级路径要写到“谁接手、带什么证据、为什么现在升级”。交接包至少包含事件编号、首次失败时间、影响范围、Namespace/Pod/PVC/PV、CSI driver、Node、关键事件与日志时间段、近期变更、已执行动作、当前数据风险、命中的停止条件,以及下一位负责人需要回答的问题。

一份可上线的 CSI Runbook,不以“命令很多”为完成标准,而以任何值班人员都能从同一症状入口得到同一证据、在危险动作前停下来、执行可回退恢复,并能证明业务数据真正恢复为验收标准。

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

目录与阅读设置

阅读设置

17

记录一个想法

编写 CSI 存储故障 Runbook

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

登录哪都通