NATS Helm Charts部署时持久存储动态创建失败问题

问题表现 #

部署NATS Helm Chart过程中多资源层级报错，核心调度事件如下：

Warning  FailedScheduling  99s (x4 over 4m4s)  default-scheduler  0/1 nodes are available: 1 pod has unbound immediate PersistentVolumeClaims. preemption: 0/1 nodes are available: 1 Preemption is not helpful for scheduling.

关联异常：

• statefulset/nats 持续阻塞，提示Waiting for statefulset spec update to be observed...
• PVC nats-js-pvc-nats-2 长期处于Pending状态，配置为使用do-block-storage存储类，申请2Gi容量、ReadWriteOnce访问模式的文件系统存储
• nats-0、nats-1、nats-2三个Pod全部因PVC未绑定无法完成调度
• 已附排查材料包含：完整NATS服务配置（客户端端口、监控配置、JetStream配置、全网格集群配置）、StatefulSet生成的Pod完整定义、Helm部署全量计算参数、部署钩子、完整Manifest资源清单、nats-0 Pod的describe详情

排查与修复方案 #

该故障的核心触发逻辑为：NATS JetStream持久化关联的PVC无法完成自动供给与绑定，导致Pod调度前置校验不通过，StatefulSet的更新流程被阻塞。针对使用do-block-storage（DigitalOcean块存储）的场景，按以下顺序排查修复：

1. 校验存储类配置有效性
   执行命令检查目标存储类的运行配置：

   kubectl get sc do-block-storage -o yaml
   

   核心校验点：
   • provisioner字段值必须为dobs.csi.digitalocean.com，字段值异常说明DigitalOcean CSI存储驱动未正确部署
   • 检查存储类是否配置了错误的节点选择器、污点容忍规则，导致CSI驱动组件无法在集群节点上正常运行
2. 检查CSI存储组件运行状态
   do-block-storage的PV自动供给能力完全依赖DigitalOcean CSI控制器与节点插件，执行命令查看CSI组件状态：

   kubectl get pods -n kube-system | grep do-csi
   

   若存在CrashLoopBackOff、Pending状态的CSI组件Pod，直接查看对应Pod日志定位根因，常见触发原因包括：
   • 集群配置的DigitalOcean API访问凭证权限不足，CSI驱动无权创建块存储卷
   • 集群所在DigitalOcean区域块存储资源配额不足，无法创建新的2Gi容量卷
   • CSI驱动版本与当前Kubernetes集群版本不兼容
3. 排查PVC配置兼容性问题
   执行命令查看PVC的事件详情，获取供给失败的直接报错：

   kubectl describe pvc nats-js-pvc-nats-2
   

   核心校验点：
   • 确认PVC未配置do-block-storage不支持的参数，DO块存储仅支持ReadWriteOnce访问模式，不支持ReadWriteMany、ReadOnlyMany多节点挂载模式
   • 确认Helm Values中未传入存储类不支持的自定义参数，比如不存在的卷类型、错误的加密配置
   • 若存储类配置的volumeBindingMode为WaitForFirstConsumer，需确认Pod本身没有配置无法满足的节点亲和、反亲和规则，导致Pod无法调度到可用节点，间接阻塞PVC绑定流程
4. 流程重置验证
   确认上述配置无异常后，删除卡住的PVC并重启StatefulSet滚动流程，触发存储卷重新供给：

   kubectl delete pvc nats-js-pvc-nats-0 nats-js-pvc-nats-1 nats-js-pvc-nats-2
   kubectl rollout restart statefulset/nats
   

   单节点测试集群需额外检查：NATS StatefulSet默认配置的Pod反亲和规则是否阻止多副本调度到单节点，若存在该问题可在Helm Values中关闭强制反亲和配置，适配单节点测试场景。
5. Helm参数校验
   检查传入NATS Helm Chart的Values配置，确认jetstream.persistentStorage块中未错误指定存储类名称、未申请低于DO块存储最小阈值的容量（DO块存储最小支持1Gi容量，本次申请的2Gi符合要求）。

内容的提问来源于stack exchange，提问作者ASG4