Kubernetes StorageClass 怎么用:动态制备一块 PVC,附 Pending 排查
技术教程 · K8s · 存储 · 2026-10-05
Kubernetes StorageClass 怎么用:动态制备一块 PVC,附 Pending 排查
一句话开头
管理 K8s 集群的人大概都遇到过这个场景:Pod 起不来,kubectl describe pod 里写着 pod has unbound immediate PersistentVolumeClaims,回头看 PVC,状态一直是 Pending。
多数时候不是存储坏了,而是 StorageClass 没配对。这篇把 StorageClass 怎么用、PVC 为什么 Pending 一次讲清。
前置准备
-
一个能跑的 K8s 集群(1.24 以上,CSI 是主流做法)
-
集群里已装对应存储的 CSI 驱动(云上一般自带;自建集群要自己装,比如 NFS subdir provisioner、Ceph CSI、Longhorn)
-
kubectl 已连上集群
步骤 1:先看集群有哪些 StorageClass,谁是默认
kubectl get storageclass
# 简写
kubectl get sc
名字后面带 (default) 的那个就是默认存储类。PVC 不写 storageClassName 时,会绑定到它。
如果这个列表是空的,说明集群里没有可用的制备器(CSI 驱动没装,或者压根没建 SC)—— 这种情况下 PVC 一定会 Pending。
建一个 StorageClass:
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: fast-storage
provisioner: ebs.csi.aws.com # 换成你集群的 CSI 驱动名
reclaimPolicy: Retain # 默认是 Delete,存重要数据建议显式写 Retain
allowVolumeExpansion: true # 允许后续扩容量
volumeBindingMode: WaitForFirstConsumer
parameters:
type: gp3
三个字段最值得说:
-
provisioner:谁负责去创建卷。云上用各家 CSI(ebs.csi.aws.com、disk.csi.azure.com、pd.csi.storage.gke.io),自建集群填 NFS / Ceph / Longhorn 的驱动名。
-
reclaimPolicy:PVC 被删除后 PV 怎么办。Delete(默认)连卷一起删;Retain 只解绑,数据留着。
-
volumeBindingMode:Immediate(默认)是创建 PVC 就立刻建卷;WaitForFirstConsumer 是等 Pod 被调度之后再建卷,能避免「卷在 A 可用区、Pod 想调度到 B 可用区」这类冲突。
步骤 2:创建 PVC,验证动态制备
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: my-pvc
spec:
accessModes:
- ReadWriteOnce
storageClassName: fast-storage # 引用上面的 StorageClass
resources:
requests:
storage: 10Gi
kubectl apply -f pvc.yaml
kubectl get pvc my-pvc -w
注意:如果 SC 用的是 WaitForFirstConsumer,此时 PVC 停在 Pending 是正常的,不是故障。要等到有 Pod 用它,才会触发卷制备。
步骤 3:写个 Pod 挂载它
apiVersion: v1
kind: Pod
metadata:
name: pvc-demo
spec:
containers:
- name: app
image: busybox
command: ["sh", "-c", "echo hello > /data/hello.txt && sleep 3600"]
volumeMounts:
- name: data
mountPath: /data
volumes:
- name: data
persistentVolumeClaim:
claimName: my-pvc
apply 之后再查:
kubectl get pvc # 状态应变成 Bound
kubectl get pv # 能看到自动创建的 PV,名字类似 pvc-<uuid>
到这一步,StorageClass 的动态制备链路就通了:PVC → 触发 provisioner → 自动建 PV → 绑定。
常见坑
-
- PVC 一直是 Pending,事件里写 storageclass not found:storageClassName 拼错了,或者这个名字在当前集群不存在。最快的定位方式是 kubectl describe pvc my-pvc,直接看 Events。
-
- PVC Pending,但没有任何报错、没有事件:如果 SC 是 WaitForFirstConsumer,说明还没有 Pod 来触发制备。检查挂载它的 Pod 是否创建成功、是否被调度。
-
- 用了 WaitForFirstConsumer,Pod 里还写了 nodeName —— 会一直 Pending。这个坑很隐蔽:nodeName 会直接绕过调度器,调度器不参与,卷就不会被制备。要指定节点就改用 spec.nodeSelector,例如 kubernetes.io/hostname: kube-01。
-
- Pod 报 volume node affinity conflict:云盘这类存储只在单个可用区可用。如果 SC 是 Immediate,卷可能建在 A 区而 Pod 被调度到 B 区。解法就是给 SC 加上 volumeBindingMode: WaitForFirstConsumer,让卷跟着 Pod 走。
-
- 想把 PVC 改小 —— 改不动:allowVolumeExpansion 只管扩容,不能缩容。想缩小只能新建一个更小的 PVC,再把数据迁过去。扩容则直接 patch PVC:kubectl patch pvc my-pvc -p '{"spec":{"resources":{"requests":{"storage":"20Gi"}}}}'
-
- 扩容之后 Pod 里 df 还是老容量:部分 CSI 驱动需要重建 Pod 才会完成文件系统层扩容,kubectl delete pod 让它重建一次即可。
-
- reclaimPolicy 用了 Delete,删 PVC 顺手把数据删了:新建 SC 如果不写 reclaimPolicy,默认就是 Delete。用 Retain 时删掉 PVC,PV 会变成 Released,数据还在,但不能被新 PVC 直接复用,需要管理员手动清理后重新创建。
作者补充:见过一次真实事故——存储类 SC 用的是默认 Delete,测试同学清理命名空间时顺手删了 PVC,PV 跟着被删,快照又没配,数据直接没了。生产集群的 StorageClass 建议一开始就把 reclaimPolicy: Retain 写死。事后改 SC 不会影响已经创建出来的 PV,补救是来不及的。
一句话总结
StorageClass 就是「按需自动买盘」的模板,PVC 引用它,K8s 就动态制备 PV。遇到 Pending 先 kubectl describe pvc 看 Events:九成是 SC 名字错、集群没有默认 SC,或者 WaitForFirstConsumer 正在等 Pod。