存储排障与 Week 6 收口
实验环境:三节点 K8s v1.36.3 + Calico,NFS 后端
192.168.0.241:/K8SStorageSC:nfs-client(WaitForFirstConsumer+allowVolumeExpansion: true+Delete) 本篇是 Week6 的收口,末尾附五天全景总结。
核心认知
存储故障的特点是「沉默」 —— 不报错、不崩溃,只是卡住。
| 表现 | 常见的错误第一反应 | 应该看的 |
|---|---|---|
PVC 一直 Pending | "存储坏了?" | describe pvc → Events 的 Reason |
Pod 卡在 ContainerCreating | "镜像拉不下来?" | describe pod → Events |
| Pod 起来了但写不进数据 | "应用有 bug?" | ls -ln 看 uid |
| 改了 ConfigMap 配置没变 | "K8s 出问题了?" | 是不是用了 subPath |
共同点:kubectl get 看不出任何异常,答案全在 Events 或实际存储里。
一、PVC Pending 的六种原因(Events 对照表)
| # | 原因 | Events 的 Reason | Message |
|---|---|---|---|
| 1 | 没有默认 SC,PVC 也没指定 | FailedBinding | no persistent volumes available for this claim and no storage class is set |
| 2 | SC 名字不存在 | ProvisioningFailed(Warning) | storageclass.storage.k8s.io "xxx" not found |
| 3 | provisioner 不在 / 名字不对 | ExternalProvisioning | Waiting for a volume to be created either by the external provisioner 'xxx' or manually... |
| 4 | WaitForFirstConsumer 在等 Pod | WaitForFirstConsumer | waiting for first consumer to be created before binding |
| 5 | 容量不满足(静态匹配) | FailedBinding | no persistent volumes available for this claim |
| 6 | accessModes 不匹配(静态匹配) | FailedBinding | 同上 |
实测:一次制造三个坏 PVC
# A:不写 storageClassName(集群无默认 SC)
# B:引用不存在的 SC
# C:WFFC 模式,不建 Pod
实测 Events:
─── bad-a-no-sc ───
Normal FailedBinding no persistent volumes available for this claim and no storage class is set
─── bad-b-sc-missing ───
Warning ProvisioningFailed storageclass.storage.k8s.io "not-exist-sc" not found
─── bad-c-wffc ───
Normal WaitForFirstConsumer waiting for first consumer to be created before binding
二、★ 最重要的一条:Reason 才是分诊码,Type 不可靠
看上面三个事件的 Type:
bad-a-no-sc Normal FailedBinding ← 真故障,但是 Normal
bad-b-sc-missing Warning ProvisioningFailed ← 真故障,是 Warning
bad-c-wffc Normal WaitForFirstConsumer ← 正常,也是 Normal
bad-a-no-sc 是永远绑不上的真故障,K8s 却标成了 Normal。
所以靠 Type 判断完全不可靠。
排障纪律
kubectl describe里真正该看的是Reason,不是Type。
Reason 的语义表(Week6 累计):
| Reason | 含义 | 性质 |
|---|---|---|
FailedBinding | 静态匹配失败 | ❌ 故障 |
ProvisioningFailed | 动态供给失败 | ❌ 故障 |
ExternalProvisioning | 在等 provisioner 动手 | ❌ 故障(除非刚创建) |
ExternalExpanding | 在等 provisioner 扩容 | ❌ 故障(Day3 的坑) |
WaitForFirstConsumer | 在等 Pod | ✅ 正常 |
Provisioning / ProvisioningSucceeded | 正常供给流程 | ✅ 正常 |
★ 修复成功的判断标准
不要只看 STATUS:
修复前: Pending + Reason=FailedBinding
修复后: Pending + Reason=WaitForFirstConsumer
↑ STATUS 没变,但 Reason 变了 = 修好了
很多人看到还是 Pending 就以为没修好,继续乱改 —— 这是排障中最常见的时间浪费。
三、不可变字段:唯一的修复路径是「删了重建」
实测:kubectl edit 改不动
想给一个没写 storageClassName 的 PVC 补上,kubectl edit 会报:
The PersistentVolumeClaim "xxx" is invalid:
spec: Forbidden: spec is immutable after creation
except resources.requests for bound claims
注意后半句:except resources.requests for bound claims —— 唯一允许改的字段。
为什么换 patch / apply / replace 都没用
kubectl edit → 编辑器改完 → 提交 UPDATE → apiserver 校验拒绝
kubectl patch → JSON Patch → 提交 UPDATE → 拒绝
kubectl apply → 计算 diff → 提交 UPDATE → 拒绝
kubectl replace → 整对象替换 → 提交 UPDATE → 拒绝
这些工具最终都调用同一个 API(UPDATE),限制在 apiserver 的 ValidatePersistentVolumeClaimUpdate 层,与客户端无关。
只有 create 走不同的校验路径 —— 所以删除重建是唯一方法。
PVC 的不可变字段清单
| 字段 | 可改? |
|---|---|
spec.accessModes | ❌ |
spec.storageClassName | ❌ |
spec.volumeName | ❌ |
spec.selector | ❌ |
spec.volumeMode | ❌ |
spec.dataSource / dataSourceRef | ❌(除特定场景) |
spec.resources.requests.storage | ✅ 只能增大(需 allowVolumeExpansion) |
metadata.labels / annotations | ✅ |
分情况处理
| 场景 | 做法 |
|---|---|
| Pending 的空 PVC | 直接删了重建,零损失(没绑过 PV,没数据) |
| 已 Bound 且有数据的 PVC | 删 PVC 会触发 reclaimPolicy,可能丢数据 |
| 有数据、要换 SC | 新建正确 SC 的 PVC → cp -a / rsync 迁移 → 切应用 → 删旧的 |
| 有数据、只是改容量 | 用 resources.requests.storage(唯一允许的修改) |
⚠️ PV 的 storageClassName 同样不可变 —— 换 SC 时,PVC 和 PV 两个对象都得重建。
一个容易忽略的细节:默认化不追溯
PVC 创建时没写 SC,集群也没有默认 SC → 落脚为 ""
↓ 之后你设置了默认 SC
↓
这个已存在的 PVC 不会自动获得 SC
↓ 只能删了重建
默认化(defaulting)只发生在对象创建的那一刻,不追溯历史对象。
四、★ subPath 不接收 ConfigMap 更新
现象
改了 ConfigMap,整卷挂载的 Pod 更新了,subPath 挂载的 Pod 没变。
实测结论:整卷挂载会更新,subPath 挂载不会更新。
机制:subPath 是「文件级 bind mount」
整卷挂载(kubelet 更新的是符号链接):
/var/lib/kubelet/pods/<uid>/volumes/kubernetes.io~configmap/app-config/
..data → ..data_tmp_1697xxxx ← 每次更新指向新目录
app.conf → ..data/app.conf ← 符号链接
容器里 /etc/config/app.conf 是符号链接 → ..data 一换就读到新内容 ✅
subPath 挂载(绑定的 inode 不变):
mount --bind .../app-config/app.conf /容器/etc/app.conf
绑定的是那个文件的 inode。
ConfigMap 更新 → kubelet 创建新的 ..data 目录
→ 但容器里的 /etc/app.conf 仍绑在旧 inode ❌
官方文档原话
kubernetes.io/docs → Concepts → Configuration → ConfigMaps,在 "Mounted ConfigMaps are updated automatically" 一节末尾:
"A container using a ConfigMap as a
subPathvolume mount will not receive ConfigMap updates."
同样的限制适用于 Secret 的 subPath 挂载。
四种解决方案
| 方案 | 做法 | 代价 |
|---|---|---|
| ① 挂整个目录(推荐) | mountPath: /etc/config,应用读 /etc/config/app.conf | 需调整应用配置路径 |
| ② 主动重启 | 改完 ConfigMap 后 kubectl rollout restart deploy/xxx | 短暂中断 |
| ③ Sidecar 同步 | configmap-reload 之类,监听变化并通知应用 | 多一个容器 |
| ④ 应用自己 watch | 应用内部监听文件 mtime | 依赖应用能力 |
⚠️ 第 ③ 种注意:subPath 下文件本身不变,sidecar 也读不到变化 —— 用 sidecar 时同样不能配 subPath。
什么时候必须用 subPath
/etc/nginx/conf.d/ 目录里有镜像自带的 default.conf
你只想覆盖其中一个文件,不想覆盖整个目录
→ 只能 subPath
→ 代价:这个文件不随 ConfigMap 更新
这是一个明确的取舍。
生产选择逻辑
配置改完能接受重启吗?
├─ 能 → kubectl rollout restart(最简单)
└─ 不能 → 挂整个目录 + 应用支持热加载(nginx -s reload / SIGHUP)
└─ 还不行 → sidecar 监听 + 通知
五、其他存储故障场景
① Pod 卡在 ContainerCreating
kubectl describe pod <name> | grep -A10 Events
常见 Reason:
| Reason | 含义 |
|---|---|
FailedMount | 挂载失败(路径不存在、NFS 不通、权限) |
FailedAttachVolume | 卷附加失败(块存储场景) |
Multi-Attach error for volume | RWO 卷被多个节点同时挂载 |
FailedScheduling | 调度失败(节点资源不足、PVC 不可用) |
② Multi-Attach error(RWO 的典型故障)
Multi-Attach error for volume "pvc-xxx" Volume is already used by pod(s) ...
原因:ReadWriteOnce 的卷被两个不同节点上的 Pod 同时挂载。
排查:
kubectl get pod -A -o wide | grep <pvc-name> # 还有谁在用
kubectl get volumeattachment | grep <pv-name> # 附着关系
解决:确认旧的 Pod 已终止、或删除 volumeattachment(谨慎)。
注意:StatefulSet 不会遇到这个问题 —— 每个 Pod 有独立 PVC。
③ 权限问题(NFS root_squash)
Pod 能挂载,但写入报 Permission denied
排查三步:
# 1. 看 NFS 上的实际属主(用 -n 看数字 uid)
ls -ln /mnt/nfs/<目录>/
# 2. 看容器内的运行用户
kubectl exec <pod> -- id
# 3. 对照:容器是 root(0),NFS 上是 nobody(65534) → root_squash 生效
解决:
spec:
securityContext:
fsGroup: 1000 # 挂载后的属组
containers:
- name: app
securityContext:
runAsUser: 1000 # 非 root 运行,不被 squash
④ 节点侧排查
卷在节点上到底挂在哪:
kubectl get pod <name> -o jsonpath='{.metadata.uid}'
# /var/lib/kubelet/pods/<uid>/volumes/
节点磁盘被谁吃了:
du -sh /var/lib/kubelet/*
df -h /var/lib/kubelet
注意区分:
| 现象 | 排查位置 |
|---|---|
容器内 df 显示满 | 卷所在的存储后端 |
节点 df 显示满 | /var/lib/kubelet、镜像层、/var/log |
Pod 报 no space left on device | 先分清是哪个文件系统 |
这也是 Day2 那个"容器内 df 看到的是 NFS 整个容量(30G),不是 PVC 的 1Gi"的实用价值 —— 排查磁盘问题时必须知道自己在看哪一层的数字。
六、踩坑实录
坑 1:以为 Type: Normal 就是正常
FailedBinding 也是 Normal。只看 Type 会漏掉真故障。
坑 2:修复后看到还是 Pending 就以为没修好
看 Reason,不看 STATUS。 FailedBinding → WaitForFirstConsumer 就是修复成功的证据。
坑 3:试图用 kubectl edit 改不可变字段
storageClassName / accessModes / volumeMode 都不可变。任何修改命令都会被 apiserver 拒绝,只能删了重建。
坑 4:以为设置默认 SC 会让已有 PVC 自动获得 SC
默认化不追溯,只影响新创建的 PVC。
坑 5:subPath 挂载的 ConfigMap 改了不生效
官方已知行为,不是 bug。见第四节。
坑 6:用 sidecar 做配置热加载,却还配了 subPath
文件本身不变,sidecar 也读不到变化。 必须挂整个目录。
坑 7:NFS 上 Permission denied,以为是 K8s 问题
先 ls -ln 看 uid。 看到 65534 就是 root_squash,属主映射问题,不是 RBAC 也不是挂载失败。
坑 8:kubectl get pvc 显示 Bound 但容量/数据不对
Bound 只表示"有 PV 绑上了",不代表一切正常。 扩容卡住时(Day3)也是 Bound。
七、复习自测题
排障
- PVC
Pending时,第一步该做什么?看什么字段? Type: Normal+Reason: FailedBinding说明什么?- 修复后
STATUS还是Pending,怎么判断是否修好? Multi-Attach error的原因是什么?StatefulSet 会不会遇到?
不可变字段
- PVC 的哪些字段不可变?唯一能改的是什么?
- 为什么
kubectl patch和kubectl apply也改不了? - 已 Bound 且有数据的 PVC 需要换 SC,应该怎么做?
subPath
subPath挂载的 ConfigMap 为什么不更新?- 三种让配置生效的方案,各自的代价是什么?
- 什么情况下必须用
subPath?
权限
- NFS 上文件属主是 65534,说明什么?怎么解决?
八、速记卡片
【存储故障的特点】
沉默:不报错,只是卡住
入口永远是 Events,不是 get
【PVC Pending 六因】
FailedBinding → 无 SC 且无匹配 PV / 静态匹配失败
ProvisioningFailed → SC 不存在
ExternalProvisioning → provisioner 不在 / 名字不对
WaitForFirstConsumer → 正常,等 Pod
(容量/accessModes 不匹配也归 FailedBinding)
【★ Reason 才是分诊码】
FailedBinding 竟然是 Normal
Type 不可靠,只看 Reason
【★ 修复成功的判断】
STATUS 可能还是 Pending
Reason 从故障类变成 WaitForFirstConsumer = 修好了
【不可变字段】
accessModes / storageClassName / volumeName / selector / volumeMode
唯一能改:resources.requests.storage(只能增大)
edit / patch / apply / replace 全部被拒 → create 是另一条路径
→ 唯一的修复方法:delete + apply
【默认化不追溯】
只影响新创建的 PVC,已存在的不会自动获得 SC
【★ subPath 不更新】
整卷挂载 → 更新的是符号链接 → 能更新
subPath → 文件级 bind mount 绑 inode → 不更新
官方原话:will not receive ConfigMap updates
【subPath 的替代】
挂整个目录(推荐)/ rollout restart / sidecar(但不能配 subPath)
【NFS 权限】
ls -ln 看到 65534 → root_squash
解决:runAsUser + fsGroup 用非 root
【Node 侧排查】
/var/lib/kubelet/pods/<uid>/volumes/
du -sh /var/lib/kubelet/*
分清容器内 df 和节点 df
Week6 全景总结
五天主线
| Day | 主题 | 核心产出 |
|---|---|---|
| Day1 | PV / PVC 生命周期 | 供需模型 + 绑定四条件 + 三种回收策略 |
| Day2 | StorageClass + 动态供给 | 三个 provisioner + 归档 vs 真删 |
| Day3 | 绑定模式 + 扩容 | WFFC + 「许可 ≠ 能力」 |
| Day4 | StatefulSet + 持久化 | 三个稳定 + PVC 不自动删 |
| Day5 | 存储排障 | Reason 分诊 + subPath 的坑 |
★ 贯穿五天的一条主线
K8s 存储的所有设计,都是「声明」与「实现」的分层。
而所有"哑巴故障",都源于这两层的错位 —— 且 K8s 不会主动告诉你。
| 你的声明 | 谁来实现 | 错位时的表现 |
|---|---|---|
| PVC 要 5Gi | provisioner 造 PV | ExternalProvisioning(工人在不在) |
SC 的 parameters | provisioner 自己解释 | 参数写错静默生效(archiveOnDelete 那次) |
reclaimPolicy: Delete | provisioner 决定归档还是真删 | 日志说删了,实际只是改名 |
allowVolumeExpansion: true | provisioner 实现 ExpandVolume | 卡在 ExternalExpanding,状态仍 Bound |
volumeClaimTemplates | StatefulSet controller 生成 PVC | 删 sts 后 PVC 残留(设计如此) |
subPath 挂载 | kubelet 做 bind mount | 配置永不更新 |
贯穿五天的判据(考前重点)
1. 看 Reason,不看 Type
FailedBinding 是 Normal
WaitForFirstConsumer 也是 Normal
→ 只有 Reason 能区分
2. 信实际存储,不信日志
日志 volume deleted → 可能只是改名 archived-*
日志无异常 → 可能底层根本没扩
→ 必须 ls 实际存储
3. 分清「正常等待」与「真的坏了」
WaitForFirstConsumer → 正常
ExternalExpanding → 坏了
Pending 本身不代表故障
4. 分清「许可」与「能力」
allowVolumeExpansion: true → 许可(apiserver 允许)
provisioner ExpandVolume → 能力(能不能真做)
只有许可没有能力 = 静默失败
Week6 的实验资产(可复用)
PV/PVC pv-day1 / pvc-day1-reuse(静态,Retain)
provisioner nfs-client-provisioner(k8s-node01)
SC nfs-client(WFFC + allowVolumeExpansion + Delete)
StatefulSet web(3 副本)/ recon-db(3 副本)
NFS /K8SStorage(30G,无配额,root_squash)
考纲对照(Storage 10%)
| 考纲要求 | 覆盖 |
|---|---|
| Understand storage classes, persistent volumes | Day1 / Day2 ✅ |
| Understand volume mode, access modes and reclaim policies | Day1 ✅ |
| Understand persistent volume claims primitive | Day1 / Day3 ✅ |
| Know how to configure applications with persistent storage | Day4 ✅ |
Storage 域的四条要求全部覆盖,可以进入下一个域。