1. CRD 版本迁移概述
1.1 什么是 CRD 版本迁移
CRD（Custom Resource Definition）版本迁移是指：当自定义资源（CR）的 API 版本发生变化时，Kubernetes 集群中已存储的旧版本资源对象被自动或手动转换为新版本格式的过程。Kubernetes 允许一个 CRD 同时注册多个版本（如 v1alpha1、v1beta1、v1），并通过 storage version 和 served version 机制控制读写行为。
核心概念速览：
- Storage Version — 持久化到 etcd 的版本，集群中只能有一个。
- Served Version — API Server 对外暴露的版本，可以有多个。
- Conversion — 不同版本之间的资源数据转换逻辑。
1.2 为什么需要版本迁移
CRD 版本迁移是 Operator 生命周期管理中的关键环节，主要驱动因素包括：
| 驱动因素 | 说明 | 典型场景 |
|---|---|---|
| API 演进 | 资源字段新增、废弃或重命名，需要平滑过渡 | v1alpha1 → v1beta1 → v1 |
| 兼容性保障 | 旧版客户端仍可读写，新版 Operator 使用新格式 | 多版本 Operator 共存 |
| 存储优化 | 统一 etcd 中资源存储格式，减少转换开销 | 废弃 v1alpha1 存储版本 |
| 安全合规 | 移除敏感字段或调整校验规则 | 字段加密、准入控制升级 |
| 生态集成 | 适配 Kubernetes 新版本 API 规范 | CRD v1 取代 v1beta1 |
最佳实践： 建议在 CRD 设计初期就规划好版本策略，避免后期大规模迁移。每个版本至少保留一个 minor 版本的兼容期。
1.3 版本迁移的核心挑战
CRD 版本迁移并非简单的字段映射，它涉及数据一致性、Operator 行为兼容、集群稳定性等多个维度。以下是实践中最常见的挑战：
- 数据完整性风险 — 转换过程中字段丢失、默认值缺失或类型不匹配，导致资源不可用。
- 双向转换一致性 — 从 v1 转 v2 再转回 v1 必须无损，否则引发数据漂移。
- 存储版本切换时机 — 切换 storage version 后，旧版本资源无法直接写入，需提前完成全量迁移。
- Operator 多版本共存 — 不同版本的 Operator 可能同时运行，需确保读写版本兼容。
- 转换 Webhook 可靠性 — 自定义转换 Webhook 的可用性直接影响 API 请求成功率。
- 大规模集群性能 — 全量迁移时，大量资源转换可能压垮 API Server 或 etcd。
⚠️ 常见误区： 很多团队只关注字段映射，忽略了 存储版本切换 和 Operator 多版本兼容 这两个隐性挑战。存储版本切换一旦执行，旧版本资源将无法直接通过 API 写入，必须确保所有客户端都已升级。
1.4 版本迁移的典型工作流
一个完整的 CRD 版本迁移通常包含以下步骤：
- 评估现状 — 梳理当前 CRD 版本、存储版本、资源数量、客户端依赖。
- 定义新版本 — 在 CRD 中注册新版本，配置 served 和 storage 标记。
- 实现转换逻辑 — 编写 Conversion Webhook 或使用内置转换策略。
- 测试验证 — 在测试集群中验证双向转换、数据完整性、Operator 行为。
- 灰度切换 — 逐步切换客户端到新版本，监控错误率。
- 全量迁移 — 执行存储版本切换，确保所有资源写入新版本。
- 清理旧版本 — 确认无依赖后，从 CRD 中移除旧 served 版本。
关键指标：
- 迁移成功率 ≥ 99.9%
- 转换延迟 ≤ 50ms（P99）
- 数据零丢失
- Operator 无重启或 CrashLoopBackOff