CRD 升级是什么
CRD（CustomResourceDefinition）是 Kubernetes 的集群级扩展资源：升级它不是替换一个文件，而是一次版本治理——多版本并存、切换存储版本、迁移存量对象，每步都有顺序要求。标准顺序：先提供新版本、迁移使用者、再切存储版本、最后移除旧版本。CRD 与控制器镜像要配套发布，字段级行为变化是最容易出问题的地方。
基本信息
| 多版本 | spec.versions 可同时提供多个 served 版本 |
|---|---|
| 存储版本 | storage: true 的版本只应有一个 |
| 升级顺序 | 加新版本 → 迁移使用者 → 切存储 → 移除旧版本 |
| 风险点 | 字段级行为变化（未识别字段处理、默认值、校验） |
| 配套 | CRD 与控制器镜像按版本搭配发布 |
| 常用工具 | kubectl get / explain / apply，schema 对比 |
升级前检查
升级前检查
kubectl get crd examples.example.com -o jsonpath='{.spec.versions[*].name}' # 列出已提供版本
kubectl get crd examples.example.com -o jsonpath='{.spec.versions[?(@.storage==true)].name}' # 当前存储版本
kubectl explain example.spec --recursive | head -50 # 对比新旧字段
kubectl get examples.example.com --all-namespaces | wc -l # 存量对象规模
kubectl get crd examples.example.com -o yaml > crd-backup.yaml # 升级前备份定义典型使用场景
- 新增 API 版本：为控制器新能力提供新的版本定义
- 存储版本切换：把存量对象迁移到新版本的存储格式
- 校验规则增强：收紧 schema 或增加字段校验
- 多集群巡检：确认各集群 CRD 版本与控制器版本匹配
- 故障排查：对象行为与文档不符时先核对 CRD 版本
- 大规模迁移：分批迁移并在每批后核对对象状态
阶段与检查点
| 阶段 | 动作 | 检查点 |
|---|---|---|
| 加新版本 | 旧版本继续 served | 新版本 schema 先跑通 |
| 迁移使用者 | 客户端与控制器切用新版本 | 旧版本访问量归零 |
| 切存储版本 | 把 storage: true 指到新版本 | 存量对象读写正常 |
| 移除旧版本 | 从 versions 中删除 | 确认无客户端仍在使用 |
| 控制器配套 | 控制器与 CRD 同批发布 | 版本匹配关系有记录 |
直接切存储版本：存量对象若无法转换会读取失败，先确认转换能力再切。
CRD 与控制器混在一次大发布：出问题时定位成本成倍上升，拆成两步走。
移除旧版本前先确认没有客户端和控制器还在调用它，残留调用会直接报错。