4. Cluster Upgrade 资源校准定义
在 Kubernetes 集群升级过程中，资源校准（Resource Alignment） 是指将集群中正在使用的 API 资源版本与目标 Kubernetes 版本所支持的 API 版本进行一致性匹配的过程。其核心目标是确保升级后所有工作负载、控制器和自动化工具能够继续正常工作，不会因为 API 版本的移除或变更而导致功能失效。
4.1 什么是资源校准
资源校准本质上是一个版本映射与迁移的过程。Kubernetes 每个版本都会对 API 资源进行生命周期管理，包括引入新版本、弃用旧版本以及最终移除已弃用的版本。资源校准就是要在升级前识别出那些在目标版本中不再可用的 API 版本，并将其迁移到受支持的版本上。
核心定义：资源校准 = 检测当前集群中使用的 API 版本 → 对比目标版本支持的 API 版本 → 迁移不兼容资源 → 验证校准结果。
| 校准维度 | 说明 | 示例 |
|---|---|---|
| API 版本映射 | 将资源从旧版本迁移到目标版本支持的版本 | extensions/v1beta1 → apps/v1 |
| 资源清单更新 | 修改 YAML 文件中的 apiVersion 字段 |
apiVersion: apps/v1 |
| 存储版本迁移 | 更新 etcd 中存储的资源版本 | kubectl convert 命令 |
| 控制器适配 | 确保 Operator 和控制器使用新 API | 更新 CRD 定义 |
4.2 为何升级前必须校准 API 资源
不进行资源校准直接升级集群，会导致以下严重后果：
- 资源不可用：目标版本已移除的 API 版本将无法被识别，相关资源会丢失或无法操作。
- 控制器崩溃：使用旧 API 的控制器在升级后会持续报错，导致 reconciliation 循环失败。
- 数据丢失风险：etcd 中存储的资源如果使用已移除的 API 版本，升级后可能无法读取。
- 回滚困难：一旦升级完成且发现 API 不兼容，回滚操作可能更加复杂且风险更高。
⚠️ 关键警告：Kubernetes v1.22 移除了大量
extensions/v1beta1 和 apps/v1beta1 资源。如果未提前校准，升级后所有 Ingress、DaemonSet、Deployment 等资源将无法正常工作，造成生产事故。
4.3 资源校准流程
下图展示了从检测到校准完成的完整流程：
4.4 校准的关键检查项
在升级前，必须对以下资源类型进行校准检查：
| 资源类型 | 常见弃用版本 | 目标版本 | 检查工具 |
|---|---|---|---|
| Ingress | extensions/v1beta1 |
networking.k8s.io/v1 |
kubectl convert |
| Deployment | apps/v1beta1, apps/v1beta2 |
apps/v1 |
kubectl convert |
| DaemonSet | extensions/v1beta1 |
apps/v1 |
kubectl convert |
| StatefulSet | apps/v1beta1, apps/v1beta2 |
apps/v1 |
kubectl convert |
| NetworkPolicy | extensions/v1beta1 |
networking.k8s.io/v1 |
kubectl convert |
| PodSecurityPolicy | policy/v1beta1 |
policy/v1（v1.25+ 移除） |
迁移到 Pod Security Admission |
4.5 校准的自动化策略
手动校准在大规模集群中效率低下且容易遗漏。推荐采用以下自动化策略：
- 使用
kubectl convert命令：批量转换 YAML 文件中的 API 版本。 - 集成
pluto工具：自动检测 Helm Chart 和 YAML 文件中的弃用 API。 - CI/CD 流水线检查：在代码提交阶段自动运行 API 版本检测。
- 集群内审计：使用
kubectl get --raw获取集群中实际使用的 API 版本。
💡 最佳实践：在升级前至少两个版本周期开始进行资源校准，逐步迁移，避免在升级窗口内一次性处理大量不兼容资源。
4.6 校准失败的典型场景
以下场景是资源校准中常见的失败原因：
- CRD 资源未校准：自定义资源定义（CRD）的 API 版本也需要同步更新。
- Helm Chart 版本锁定：Chart 中硬编码了弃用的 API 版本，需要更新 Chart 版本。
- Operator 未升级：Operator 本身使用的 API 版本可能已弃用，需要先升级 Operator。
- 存储版本残留：etcd 中存储的资源版本未更新，导致读取时版本不匹配。
通过系统化的资源校准，可以确保集群升级过程平稳、安全，避免因 API 版本不兼容导致的业务中断。下一阶段将深入讲解如何使用具体工具进行 API 弃用检测。