Skip to main content

存储排障与 Week 6 收口

实验环境:三节点 K8s v1.36.3 + Calico,NFS 后端 192.168.0.241:/K8SStorage SC: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 的 ReasonMessage
1没有默认 SC,PVC 也没指定FailedBindingno persistent volumes available for this claim and no storage class is set
2SC 名字不存在ProvisioningFailed(Warning)storageclass.storage.k8s.io "xxx" not found
3provisioner 不在 / 名字不对ExternalProvisioningWaiting for a volume to be created either by the external provisioner 'xxx' or manually...
4WaitForFirstConsumer 在等 PodWaitForFirstConsumerwaiting for first consumer to be created before binding
5容量不满足(静态匹配)FailedBindingno persistent volumes available for this claim
6accessModes 不匹配(静态匹配)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 subPath volume 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 volumeRWO 卷被多个节点同时挂载
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。


七、复习自测题​

排障

  1. PVC Pending 时,第一步该做什么?看什么字段?
  2. Type: Normal + Reason: FailedBinding 说明什么?
  3. 修复后 STATUS 还是 Pending,怎么判断是否修好?
  4. Multi-Attach error 的原因是什么?StatefulSet 会不会遇到?

不可变字段

  1. PVC 的哪些字段不可变?唯一能改的是什么?
  2. 为什么 kubectl patch 和 kubectl apply 也改不了?
  3. 已 Bound 且有数据的 PVC 需要换 SC,应该怎么做?

subPath

  1. subPath 挂载的 ConfigMap 为什么不更新?
  2. 三种让配置生效的方案,各自的代价是什么?
  3. 什么情况下必须用 subPath?

权限

  1. 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主题核心产出
Day1PV / PVC 生命周期供需模型 + 绑定四条件 + 三种回收策略
Day2StorageClass + 动态供给三个 provisioner + 归档 vs 真删
Day3绑定模式 + 扩容WFFC + 「许可 ≠ 能力」
Day4StatefulSet + 持久化三个稳定 + PVC 不自动删
Day5存储排障Reason 分诊 + subPath 的坑

★ 贯穿五天的一条主线​

K8s 存储的所有设计,都是「声明」与「实现」的分层。

而所有"哑巴故障",都源于这两层的错位 —— 且 K8s 不会主动告诉你。

你的声明谁来实现错位时的表现
PVC 要 5Giprovisioner 造 PVExternalProvisioning(工人在不在)
SC 的 parametersprovisioner 自己解释参数写错静默生效(archiveOnDelete 那次)
reclaimPolicy: Deleteprovisioner 决定归档还是真删日志说删了,实际只是改名
allowVolumeExpansion: trueprovisioner 实现 ExpandVolume卡在 ExternalExpanding,状态仍 Bound
volumeClaimTemplatesStatefulSet 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 volumesDay1 / Day2 ✅
Understand volume mode, access modes and reclaim policiesDay1 ✅
Understand persistent volume claims primitiveDay1 / Day3 ✅
Know how to configure applications with persistent storageDay4 ✅

Storage 域的四条要求全部覆盖,可以进入下一个域。