【Rook / CSI】升级闸门：Rook、Ceph 主版本纪律与 CSI Operator 迁移

Rook 把「改镜像标签」包装成声明式升级，并不等于升级风险消失。真正会炸的路径往往是：Ceph 一次跳多个主版本、在 HEALTH_ERR 上强推、或把 v1.20 的 CSI 所有权迁移当成无破发补丁。再叠加 VolumeSnapshot CRD 与 sidecar 错位，会出现「守护进程升级成功、存储 API 面却坏了」。本文钉闸门，不写逐步点击教程。

本文是「Rook / CSI」系列第 11 篇（共 16 篇）。→ 系列目录

篇目	核心内容
第 10 篇 · 对象与 NFS	RGW / NFS 边界
第 11 篇 · 升级闸门	Rook/Ceph/CSI 升级纪律
第 12 篇 · 可观测	toolbox / metrics

版本锚定：Rook v1.20.4；Ceph-CSI v3.17.0；K8s v1.31–v1.36。Ceph 支持：Squid v19.2.0+、Tentacle v20.2.1+；v20.2.0 不推荐（read affinity 损坏风险，见第 7 篇）。ceph/18 点名「自动升级跳过一次一个主版本」在此展开。

一、两本手册，两次升级

顺序原则（社区与文档一贯口径）：先让 Rook 支持目标 Ceph，再滚 Ceph 守护进程。把「最新 Rook + 过旧或不支持的 Ceph」或「跳版本 Ceph」混用，是编排层最贵的自学学费。

flowchart TD
  prep["Read upgrade notes\nbackup / health check"] --> rook["Upgrade Rook\nto v1.20.x"]
  rook --> csi["Verify CSI Operator\nDriver / OperatorConfig"]
  csi --> ceph["Bump cephVersion.image\none major at a time"]
  ceph --> wait["Rolling checks\nquorum / PG / MDS"]
  wait --> tools["Manual toolbox image"]
  tools --> snap["Verify snapshot CRD\nvs sidecar"]

二、Ceph 滚动：谨慎状态机，不是同时杀光

Rook 文档对 Ceph 升级的行为描述：

1. 变更 spec.cephVersion.image 后，Operator 自动化滚动。
2. 逐个守护进程：停之前做可停检查；更新 Deployment 后等待收敛。
3. 收敛条件包括：mon 法定人数、OSD 相关 PG clean、MDS up 等（文档原意：things settle）。
4. HEALTH_ERR 时 Operator 拒绝继续升级——这是硬闸门，不是提示音。

含义：

• 集群已经 HEALTH_ERR 时，先修健康，再谈升镜像。把升级当「修复手段」会在错误上叠加版本混合。
• 滚动期间可能出现短暂存储不可用窗口；文档开篇有风险警告与数据丢失可能——升级是带风险操作，不是日常按钮。

生产镜像标签：优先用完整版本+build 标签（文档示例形如 v20.2.2-20260616），避免浮动 v20 造成异构守护进程。仅测试集群才用主版本浮动标签。

2.1 支持矩阵（本系列钉死）

Toolbox 不受 Operator 自动改镜像：必须手工把 rook-ceph-tools 调到与集群一致的 Ceph 镜像，否则排障命令可能表现怪异。

三、一次一个主版本：对 ceph/18 摩擦的回答

Ceph 项目对跨版本升级有严格纪律：不能指望「从很老的主版本直接跳到当前主版本」仍安全。社区与运维手册的常见表述是：按发布序列前进，一次跨越的主版本数量有限（具体 N→N+1 / 允许的 N-2 规则以你跟的 Ceph 版本文档为准；工程上更稳的默认是 一次一个主版本，并在每一跳后确认健康）。

ceph/18 点名的故障模式是：

Rook 自动升级若跳过 Ceph「一次一个主版本」约束会炸。

展开成可执行纪律：

1. 不要在 cephVersion.image 上一次从相隔多个主版本的旧镜像改到最新。
2. 每一跳：改镜像 → 等 Rook 滚完 → ceph 状态 类检查（toolbox）→ 再下一跳。
3. GitOps 若自动追 latest / 浮动标签，等于把「跳版本」写进流水线——应改成钉死摘要标签 + 人工/门禁批准。
4. Rook 升级与 Ceph 升级分开合并请求，避免一个 PR 同时跳 Operator 大版本与 Ceph 大版本。

「Rook 会滚」≠「Rook 会替你遵守 Ceph 上游升级图」。闸门在人，不在 YAML 幻觉。

四、升级到 v1.20：CSI Operator 是断裂点

Rook v1.20 Breaking Changes（升级指南 / v1.20.0 release notes）核心：

• Ceph-CSI Operator 成为配置 CSI 的唯一支持路径。
• Rook 不再部署/拥有旧式「一切都在 rook-ceph-operator-config 里改 CSI」的模型；CSI 相关键从该 ConfigMap 与 rook-ceph chart 中移除（迁移叙述见官方 Upgrade）。
• 管理员通过 OperatorConfig 与 Driver CR（以及 ImageSet ConfigMap 等）管理驱动；Helm 用户需安装 ceph-csi-drivers chart，且应用 Rook 推荐的 values（含正确的命名空间前缀驱动名），否则会出现 ServiceAccount 缺失、CSI 控制器失败。
• v1.18–v1.19 过渡期 Rook 曾自动生成 CR；升级到 v1.20 后这些 CR 仍可用，但后续修改归管理员，Rook 不再代管。升前应导出/确认现有 OperatorConfig/Driver，避免升后丢失定制。

这与第 5 篇是同一断裂：把 v1.20 当成「小版本 Operator 镜像替换」而不读 Breaking Changes，会得到「Ceph 守护进程还在、PVC 却供给不了」的现场。

五、快照 sidecar / CRD 错位：升级检查单必填项

第 9 篇已述：csi-snapshotter 与 Volume Group Snapshot CRD（v1beta1 vs v1beta2）错位，可导致普通 VolumeSnapshot 失败（Rook issue 与 upstream external-snapshotter 讨论）。升级 Rook/CSI 镜像后：

1. 列出集群 snapshot 相关 CRD 的 served 版本；
2. 对照 CSI Pod 内 snapshotter 镜像版本与上游兼容说明；
3. 确认 snapshot-controller 与 feature gate 配置一致；
4. 在维护窗口做一次「建 VolumeSnapshot → Ready → 删」的冒烟，而不是只看 ceph -s。

Ceph 健康与 K8s 存储 API 健康是两轴；升级验收必须双轴。

六、与 Tentacle read affinity 的交叉闸门

若计划进入 Tentacle：

• 避开 v20.2.0 作为生产目标；
• 若曾启用 csi.readAffinity，按第 7 篇：关特性或直达修复版本，并重启仍持旧挂载选项的应用；
• 不要把「Rook 内部自动禁用」理解成「无需重启、无需确认」。

七、谱系、争论与开放问题

谱系：分布式存储升级闸门来自「混合版本 quorum / 特性位 / on-disk 格式」的长期工程传统（不只 Ceph）。Kubernetes Operator 模式把滚动自动化，但不能自动化掉上游版本图。CSI 配置外置到独立 Operator（v1.20）是所有权清晰化，也是升级面变宽。

争论：GitOps 自动升级是否适用于数据面？一派要安全补丁尽快落地；一派坚持数据面变更必须人工门禁。本系列立场偏后者：Rook/Ceph 数据面升级默认人工批准；自动化最多到「开 PR + 强检查」，不要到「合入即跳主版本」。

开放问题：

1. Operator 能否在改 cephVersion 时解析语义化版本并拒绝跨越多主版本的单次变更？
2. CSI sidecar 默认追上游 latest 与发行版冻结 CRD 之间的缺口，能否在 Rook 安装图里变成显式兼容性资源？

八、升级前短清单（可贴进变更单）

1. 读 v1.20 Rook Upgrade + Ceph Upgrade 全文 Breaking/Supported。
2. 确认当前 Ceph 健康非 HEALTH_ERR；规划 一主版本一跳。
3. 导出并确认 OperatorConfig/Driver；Helm 准备 ceph-csi-drivers。
4. 核对 snapshot CRD ↔︎ controller ↔︎ sidecar。
5. 钉死目标镜像完整标签；准备 toolbox 同步。
6. 若 Tentacle：目标 ≥ 20.2.1（推荐按文档写明的 20.2.2+ 策略），审查 read affinity。
7. 维护窗口冒烟：RBD PVC 供给/挂载、CephFS RWX、一次 VolumeSnapshot。

九、自动化升级的反模式清单

把 ceph/18 的警告落成可检查反模式：

1. 单 PR 跳多个 Ceph 主版本，依赖 Rook「会滚」当作安全网。
2. 浮动镜像标签（v19/v20/digest 未钉）进入生产 GitOps 主分支。
3. HEALTH_ERR 时强改 image，指望升级治病。
4. 升 Rook v1.20 不装/不对齐 ceph-csi-drivers，假设旧 ConfigMap 键继续生效。
5. 只跑 ceph -s 验收，不做 PVC 与 VolumeSnapshot 冒烟。
6. Toolbox 镜像遗留旧版本，用过期客户端解释新集群行为。
7. Tentacle 目标写成 20.2.0，或忽略 read affinity 交互。

任一反模式出现，变更单应被打回。平台可以用 CI 策略检测：cephVersion.image 的主版本号相对当前 status 是否跳变超过 1；Helm values 是否仍含已移除的 CSI ConfigMap 键。检测不完美，但比纯靠记忆强。

升级窗口的沟通模板建议包含：预期滚动的守护进程集合、可接受的短暂中断面（RBD 与 CephFS 可能不同）、回滚条件（例如何种健康检查失败则停下一跳）。没有回滚条件的升级，只是把赌博写成日历事件。

十、Rook 升级与 K8s 版本的交叉约束

Rook v1.20 发行说明钉死支持的 Kubernetes 为 v1.31–v1.36。Ceph 升级闸门之外，还有第三条轴：集群升级 K8s 次要版本时，确认仍落在 Rook 支持矩阵内。先升 K8s 越界再升 Rook，或相反，都可能造成 CRD/webhook/CSI 与 API 服务器行为不兼容。

变更规划建议按「矩阵交汇」而不是按「各升各的日历」：

1. 查目标 Rook 支持的 K8s 与 Ceph 集合；
2. 选同时落在集合内的版本三元组；
3. 再拆成多个维护窗口（K8s / Rook / Ceph 分离）。

CSI Operator 迁移窗口应避免与「大规模节点排水」同一天，否则供给失败与调度压力叠加，现场无法归因。

关于「自动升级跳主版本」的组织成因：很多团队把 Renovate/Dependabot 对应用镜像的策略复制到 quay.io/ceph/ceph。数据面镜像不是无状态应用；依赖更新机器人默认 PR 频率与合并策略都不适用。应单独规则：Ceph/Rook 镜像变更要求人工审批 + 升级检查单模板。把这写成仓库 CODEOWNERS 或策略比写在博客里更有效——但博客先把机制说清。

回滚预期也要诚实：Ceph 主版本回滚通常不在「随便改回旧标签」的支持面上。真正的回滚计划往往是「停在下一跳之前」或「从备份恢复」，而不是「Operator 自动降级」。因此门禁应前置在发起跳版本之前，而不是幻想事后一键回退。

与第 7、9 篇交叉：升级验收必须覆盖 read affinity 状态、Tentacle 精确小版本、以及一次 VolumeSnapshot 冒烟。缺这三项的「升级成功」报告，本系列视为无效验收。

十一、变更窗口里的观察顺序

升级进行中，建议固定观察顺序，避免被单个红项带着跑：

1. Operator 日志是否卡在健康检查拒绝（HEALTH_ERR）；
2. mon quorum 是否在滚动中恢复；
3. OSD 部署的 ceph-version 标签是否逐步归一（官方 jsonpath 示例语义）；
4. MDS/RGW 是否在所属步骤完成；
5. CSI provisioner/node 插件是否 Ready，Driver CR 是否预期；
6. 冒烟：RBD PVC、CephFS PVC、VolumeSnapshot。

前四项偏 Ceph 守护进程；后两项偏编排 API 面。只做前四项就宣布成功，是把第 9 篇的 CRD 事故留给明天的值班。观察顺序写成 runbook 比写在聊天记录里可靠。

若中途失败，优先停止下一跳，而不是连续改 image 标签碰运气。混合版本停留本身需要健康确认；在混合版本上再开业务发布，等于扩大未知面。

收束：升级闸门是纪律问题，不是新 RPC。Rook 把滚动做完，人要把版本图、CSI 所有权迁移、快照控制面与 Tentacle 小版本雷区做完。ceph/18 点名的「跳主版本会炸」在此落地为反模式清单与检查单；做不到清单，就不要启用自动追新。下一篇转入可观测，解决「闸门触发时看什么」。

参考资料

官方文档 / Release（A）

• Rook v1.20 — Rook Upgrades — Breaking changes in v1.20；CSI Operator 迁移
• Rook v1.20 — Ceph Upgrades — 支持版本、HEALTH_ERR 拒绝、滚动检查、toolbox、v20.2.0 警告
• Rook v1.20.0 Release notes — K8s v1.31–v1.36；CSI Operator required
• Rook Blog — Travis Nielsen，Rook v1.20 Storage Enhancements（B 级，迁移叙事）

站内

• ceph/18 · 自动升级跳版本摩擦
• 第 5 篇 · Ceph-CSI Operator
• 第 7 篇 · read affinity / Tentacle
• 第 9 篇 · snapshot CRD 错位

→ 上一篇：对象与 NFS · 系列目录 · 下一篇：可观测