【Rook / CSI】升级闸门：Rook、Ceph 主版本纪律与 CSI Operator 迁移
内容提要
本文讨论Rook/Ceph/CSI升级纪律，强调升级需遵循一次一个主版本、避免HEALTH_ERR强推、注意CSI Operator迁移和快照CRD错位。列出升级前检查清单和反模式，主张数据面升级人工审批，确保版本兼容和健康检查，防止跳版本导致故障。
延伸解读
升级纪律的核心：一次一个主版本
文章强调，Ceph 升级必须一次跨越一个主版本，不能从很老的主版本直接跳到最新。Rook 的自动滚动只负责执行，不负责替你遵守上游版本图。每一跳后都要确认健康，再继续下一跳。GitOps 若自动追 latest 或浮动标签，等于把跳版本写进流水线，应改为钉死摘要标签并加人工门禁。
CSI Operator 迁移是 v1.20 的断裂点
Rook v1.20 起，Ceph-CSI Operator 成为配置 CSI 的唯一支持路径，旧式 ConfigMap 键被移除。升级前必须导出并确认现有 OperatorConfig/Driver，Helm 用户需安装 ceph-csi-drivers chart 并应用推荐 values，否则会出现 ServiceAccount 缺失、CSI 控制器失败，导致 PVC 供给不了。
快照 CRD 与 sidecar 错位：验收必查项
csi-snapshotter 与 Volume Group Snapshot CRD 版本错位可导致普通 VolumeSnapshot 失败。升级后应列出 snapshot 相关 CRD 的 served 版本，对照 CSI Pod 内 snapshotter 镜像版本与上游兼容说明，确认 snapshot-controller 与 feature gate 配置一致，并在维护窗口做一次建快照、Ready、删的冒烟测试。
数据面升级应默认人工审批
文章立场是数据面变更必须人工门禁，自动化最多到开 PR 和强检查，不要到合入即跳主版本。Ceph 主版本回滚通常不在支持面上，真正的回滚计划是停在下一跳之前或从备份恢复。因此门禁应前置在发起跳版本之前，而不是幻想事后一键回退。
Q&A
Rook 升级 Ceph 时，为什么必须一次只升级一个主版本？
因为 Ceph 项目对跨版本升级有严格纪律，跳多个主版本可能导致故障。Rook 的自动升级若跳过 Ceph 的“一次一个主版本”约束会出问题。因此应逐版本升级，每跳一次后确认健康。
在 HEALTH_ERR 状态下，Rook 会如何处理 Ceph 升级？
当集群处于 HEALTH_ERR 状态时，Rook Operator 会拒绝继续升级，这是硬性闸门。必须先修复健康问题，再考虑升级镜像，不能把升级当作修复手段。
升级到 Rook v1.20 时，CSI Operator 迁移需要注意什么？
Rook v1.20 中，Ceph-CSI Operator 成为配置 CSI 的唯一支持路径，旧式 ConfigMap 键被移除。管理员需通过 OperatorConfig 和 Driver CR 管理驱动，Helm 用户需安装 ceph-csi-drivers chart 并应用推荐 values，否则会出现 ServiceAccount 缺失或 CSI 控制器失败。
升级后如何验证 VolumeSnapshot 功能是否正常？
需要检查集群中 snapshot 相关 CRD 的 served 版本，对照 CSI Pod 内 snapshotter 镜像版本与上游兼容说明，确认 snapshot-controller 与 feature gate 配置一致，并在维护窗口做一次“建 VolumeSnapshot → Ready → 删”的冒烟测试。
Rook 升级到 v1.20 支持哪些 Kubernetes 版本？
Rook v1.20 发行说明钉死支持的 Kubernetes 版本为 v1.31–v1.36。升级 K8s 时需确认仍落在 Rook 支持矩阵内，避免 CRD/webhook/CSI 与 API 服务器行为不兼容。
为什么生产环境不建议使用浮动镜像标签（如 v20）？
浮动标签可能导致异构守护进程，因为不同时间拉取的镜像可能不同。生产环境应优先使用完整版本+build 标签（如 v20.2.2-20260616），仅测试集群才用主版本浮动标签。
升级 Ceph 到 Tentacle 时，为什么 v20.2.0 不推荐？
Tentacle v20.2.0 与 csi.readAffinity 组合有损坏风险，因此不推荐。应升级到 v20.2.1+ 或 v20.2.2+（以当前升级文档段落为准）。
Rook 升级时，Toolbox 镜像需要手动更新吗？
是的，Toolbox 不受 Operator 自动改镜像，必须手工把 rook-ceph-tools 调到与集群一致的 Ceph 镜像，否则排障命令可能表现怪异。
