4. 版本差异校验概念
在 Operator 的持续迭代中，CRD（Custom Resource Definition）版本管理是保证集群稳定性的核心挑战。版本差异校验正是为了应对这一挑战而引入的机制——它确保新旧版本之间的数据结构、语义和行为变更不会导致已有资源损坏或控制器异常。
4.1 为什么需要版本差异校验
Operator 一旦部署到生产环境，其管理的 CR 实例可能已经成千上万。如果不对版本变更进行校验，以下问题将频繁发生：
- 数据丢失：新版本删除了旧版本中的某个字段，导致已有 CR 实例在转换时被静默丢弃数据。
- 控制器崩溃：Reconcile 逻辑期望的字段结构在新版本中不存在，引发空指针或类型断言失败。
- 转换失败：自定义转换函数（Hub-and-Spoke）存在逻辑缺陷，导致 CR 在存储版本与请求版本之间转换时出错。
- API 兼容性断裂：客户端（如 CI/CD 工具、其他 Operator）使用旧版 API 写入数据，被新版 API 拒绝或错误处理。
核心原则：版本差异校验不是可选项，而是 Operator 生产化部署的强制性质量门禁。缺少校验的版本升级等同于在运行中的集群里“盲改数据库 schema”。
4.2 版本兼容性类型
理解兼容性类型是设计校验策略的前提。下表总结了三种核心兼容性类型及其在 Operator 场景下的具体表现：
| 兼容性类型 | 定义 | Operator 场景示例 | 校验要求 |
|---|---|---|---|
| 向前兼容 (Forward Compatibility) |
新版本的 Operator 能够正确处理旧版本写入的 CR 数据。 | v2 版本的 Reconcile 逻辑读取 v1 版本创建的 CR，字段 myField 在 v1 中为 string，v2 中改为 object，但转换函数能正确映射。 | 必须提供存储版本到最新版本的转换函数；校验转换后的数据语义完整。 |
| 向后兼容 (Backward Compatibility) |
旧版本的 Operator 能够读取新版本写入的 CR 数据（通常通过存储版本不变实现）。 | 集群中存储版本始终为 v1，v2 新增字段通过 +kubebuilder:pruning:PreserveUnknownFields 保留，旧版本 Operator 忽略未知字段。 |
新版本不能删除或重命名存储版本中的已有字段；新增字段必须使用 optional 或 preserve-unknown-fields。 |
| 破坏性变更 (Breaking Change) |
版本升级后，已有 CR 实例无法被正确读取、转换或处理，导致数据损坏或控制器异常。 | v1 中字段 spec.replicas 为 int，v2 中改为 string；转换函数未实现，导致所有 v1 CR 在读取时 panic。 |
必须通过版本差异校验工具（如 oc verify-crd、kubebuilder validate）提前检测并拒绝此类变更。 |
实践建议：在 Operator 开发中，优先保证向前兼容——即新版本能处理旧数据。向后兼容通常由 Kubernetes API Server 的存储版本机制自动保障，但前提是你不破坏存储版本的 schema。
4.3 校验的粒度与范围
版本差异校验并非笼统的“检查一下”，而是需要从多个维度进行分层验证。下表列出了校验的粒度层级及其覆盖范围：
| 校验粒度 | 校验范围 | 典型检查项 | 工具/方法 |
|---|---|---|---|
| Schema 级 | CRD 的 OpenAPI v3 schema 定义 | 字段类型变更（string→int）、字段删除、required 标记新增、枚举值范围缩小 | kubectl diff、oc verify-crd、kubeconform |
| 转换函数级 | Hub-and-Spoke 转换逻辑 | 转换函数是否覆盖所有字段、是否存在 nil 引用、是否丢失 annotation/label | 单元测试 + envtest 集成测试 |
| 存储级 | etcd 中实际存储的 CR 实例 | 存储版本是否变更、存量 CR 能否被新版本正确反序列化 | 集群内灰度升级 + kubectl get crd -o yaml 检查 storage 标记 |
| 行为级 | Reconcile 逻辑对 CR 数据的处理 | 新版本 Reconcile 是否依赖旧版本不存在的字段、默认值逻辑是否一致 | 端到端测试 + 混沌工程（注入旧版本 CR） |
| 客户端级 | 外部客户端（CI/CD、其他 Operator） | 客户端使用的 API 版本是否被新 CRD 支持、响应结构是否变化 | API 版本声明检查 + 契约测试 |
校验范围则从单个 CRD 扩展到整个 Operator 管理的资源集合。例如，一个管理 Database 和 Backup 两种 CRD 的 Operator，在升级时不仅要校验每个 CRD 内部的版本差异，还要校验跨 CRD 的引用关系是否断裂（如 Database v2 删除了 status.backupRef 字段，而 Backup v2 仍依赖该字段）。
常见误区：很多团队只做 Schema 级校验，忽略了转换函数和行为级校验。结果 CRD 定义看起来没问题，但实际转换函数中忘记处理某个嵌套字段，导致生产数据丢失。版本差异校验必须是全链路的。
4.4 校验策略选择矩阵
根据 Operator 的成熟度和集群规模，可以选择不同的校验策略组合：
| Operator 阶段 | 推荐校验粒度 | 自动化程度 | 关键风险 |
|---|---|---|---|
| 开发期（< 10 个集群） | Schema 级 + 转换函数级 | 手动触发 | 字段类型误改、转换函数遗漏 |
| 预发布（10-100 集群） | Schema 级 + 转换函数级 + 存储级 | CI 流水线自动 | 存量 CR 转换失败、默认值不一致 |
| 生产期（> 100 集群） | 全粒度（含行为级 + 客户端级） | 全自动 + 灰度金丝雀 | 跨 CRD 引用断裂、客户端兼容性 |
入门建议：从 Schema 级校验开始，使用
kubebuilder 生成的 CRD 天然包含 OpenAPI 验证。在此基础上，为每个版本添加转换函数的单元测试，覆盖所有字段的映射逻辑。这是投入产出比最高的起点。