API 版本的生命周期
每个 API 组都按 alpha、beta、稳定版本的节奏演进：被标记弃用的版本会先在 apiserver 给出警告，随后在某个次版本中被彻底移除。移除之后，继续提交旧 apiVersion 的清单会被直接拒绝，而且字段结构变化不能只改一行——例如 Ingress 从 extensions/v1beta1 迁到 networking.k8s.io/v1 时新增了必填的 pathType、backend 结构也变了。因此清单审计与集群内既有对象的核对，是升级前必做的动作。
基本信息
| 适用对象 | 清单里的 apiVersion，以及集群内既有对象的存储版本 |
|---|---|
| 常见迁移路径 | apps/v1beta1 与 v1beta2 到 apps/v1；extensions/v1beta1 Ingress 到 networking.k8s.io/v1；policy/v1beta1 PDB 到 policy/v1 |
| 发现手段 | kubectl apply 的弃用警告、apiserver 弃用指标、清单静态扫描 |
| 关键指标 | apiserver_requested_deprecated_apis |
| 后果 | 升级后旧版本清单无法提交，既有对象可能无法更新 |
典型使用场景
- 集群升级前：对全部清单与 Helm chart 做一次 API 版本审计
- CI 门禁：把弃用告警纳入流水线，阻止新提交引入旧版本
- 接管存量集群：核对运行中的对象是否仍使用已移除的组版本
- 多集群同版本化：借迁移把各集群清单统一到同一 API 版本
- 第三方组件评估：确认 Operator 与 CRD 是否已适配目标集群版本
发现与核对
发现与核对
kubectl apply --dry-run=server -f deploy.yaml # 输出里含 deprecated 警告
kubectl api-resources | grep -i -E 'extensions|beta' # 看集群还提供哪些版本
kubectl get --raw /metrics | grep apiserver_requested_deprecated_apis | head -5
kubectl get ingress -A -o jsonpath='{range .items[*]}{.apiVersion}{"\n"}{end}' | sort -u常见迁移对照
| 旧版本 | 新版本 | 迁移注意 |
|---|---|---|
| apps/v1beta1、v1beta2 | apps/v1 | 选择器字段结构与默认值行为有差异 |
| extensions/v1beta1 Ingress | networking.k8s.io/v1 | pathType 必填、backend 结构改变 |
| policy/v1beta1 PDB | policy/v1 | 结构基本一致，主要是组版本变更 |
| batch/v1beta1 CronJob | batch/v1 | 组版本升级，字段差异小 |
| autoscaling/v2beta2 | autoscaling/v2 | 指标字段基本一致，建议顺手对齐 |
只看清单容易漏：集群里由 Operator 或控制器动态创建的对象同样会使用旧版本，审计时要结合 apiserver 指标与运行对象一起看。
被移除的 API 在升级后无法回退到旧版本：升级窗口前完成审计与清单替换，比升级后再救火从容得多。
迁移要连存储版本一起看：即使清单已改成新版本，集群里早先写入的对象仍可能以旧版本存储，升级后对这些对象做更新同样会触发校验，建议在升级前对存量对象做一次整体重写。