2. Kubernetes 版本演进与 API 生命周期
在制定集群升级治理模板时，理解 Kubernetes 的版本号规则与 API 生命周期是进行 API 废弃检查的前提。Kubernetes 遵循语义化版本（SemVer）规范，同时通过严格的 API 阶段（alpha → beta → stable）来管理资源的废弃与移除，确保集群在升级过程中不因 API 变更而中断业务。
2.1 Kubernetes 版本号规则
Kubernetes 版本号采用 v<major>.<minor>.<patch> 格式，每个字段的含义如下：
| 字段 | 含义 | 示例 | 升级影响 |
|---|---|---|---|
| Major | 主版本号，表示不兼容的 API 变更 | v1 → v2 | 通常需要大规模迁移，K8s 社区极少使用 |
| Minor | 次版本号，表示功能新增或废弃 | v1.24 → v1.25 | 包含 API 废弃与移除，需检查清单 |
| Patch | 补丁版本号，仅包含安全修复与 Bug 修复 | v1.25.3 → v1.25.4 | 无 API 变更，可安全升级 |
运维要点： 在升级治理模板中，
minor 版本升级是 API 废弃检查的核心关注点。每次 minor 版本升级前，必须运行 kubectl convert 或 kube-no-trouble 等工具扫描集群中已废弃的 API 资源。
2.2 API 版本阶段与废弃策略
Kubernetes API 资源从引入到最终移除，会经历三个明确的阶段：v1alpha1 → v1beta1 → v1。每个阶段都有不同的稳定性承诺和废弃时间线。
核心原则： 只有进入
v1（GA）阶段的 API 才提供长期向后兼容性。alpha 和 beta 阶段的 API 可能在任意版本中被废弃或移除，且不保证迁移路径。
2.2.1 各阶段特征对比
| 阶段 | 版本标识 | 默认启用 | 废弃后保留版本数 | 移除策略 |
|---|---|---|---|---|
| Alpha | v1alpha1, v1alpha2 … | 否（需 Feature Gate） | 无保证 | 可在下一 minor 版本直接移除 |
| Beta | v1beta1, v1beta2 … | 是 | 至少保留 3 个 minor 版本 | 废弃后 3 个 minor 版本内移除 |
| Stable (GA) | v1 | 是 | 长期保留 | 仅在新 major 版本中移除 |
2.2.2 废弃与移除时间线示例
以 networkpolicies 资源为例，展示从 beta 到 GA 再到废弃的完整生命周期：
- v1.7：引入
networking.k8s.io/v1beta1（Beta） - v1.12：
networking.k8s.io/v1进入 GA，v1beta1标记为废弃 - v1.15：
v1beta1被移除，仅保留v1
常见陷阱： 许多团队在升级时只关注当前使用的 API 版本，忽略了
CustomResourceDefinition (CRD) 和 Aggregated API 的版本变更。CRD 的 v1beta1 已在 v1.22 中被移除，如果集群中仍有使用 v1beta1 的 CRD，升级将直接失败。
2.3 API 废弃检查流程
在升级治理模板中，API 废弃检查应作为节点排空前的强制前置步骤。以下是标准检查流程：
- 扫描集群资源：使用
kubectl get --all-namespaces -o json | jq '.items[] | .apiVersion' | sort -u列出所有使用的 API 版本。 - 比对废弃清单：对照目标版本的
deprecated.yaml或社区维护的kube-apidiff工具，标记已废弃的 API。 - 迁移资源：使用
kubectl convert -f <file> --output-version <new-version>将资源清单转换为新版本。 - 验证兼容性：在测试集群中应用转换后的资源，确认无错误。
- 更新模板制品库：将制品库中的 Helm Chart、Kustomize 模板、Operator 配置更新为新的 API 版本。
2.4 API 生命周期与版本演进关系图
下图展示了 Kubernetes 版本演进过程中，API 从引入到移除的完整生命周期，以及各阶段对应的升级风险等级：
2.5 版本升级与 API 废弃对照表
以下表格列出了近几个主要 Kubernetes 版本中关键的 API 废弃与移除事件，供升级治理模板参考：
| K8s 版本 | 废弃的 API 版本 | 移除的 API 版本 | 影响资源 | 迁移目标版本 |
|---|---|---|---|---|
| v1.22 | — | apiextensions.k8s.io/v1beta1rbac.authorization.k8s.io/v1beta1 |
CRD, Role, ClusterRole | v1 |
| v1.25 | policy/v1beta1 (PodDisruptionBudget) |
policy/v1beta1 (PodSecurityPolicy) |
PDB, PSP | policy/v1 |
| v1.26 | flowcontrol.apiserver.k8s.io/v1beta1 |
— | FlowSchema, PriorityLevelConfiguration | v1beta2 → v1 |
| v1.27 | storage.k8s.io/v1beta1 (CSIDriver, CSINode) |
— | CSI 相关资源 | v1 |
| v1.28 | node.k8s.io/v1beta1 (RuntimeClass) |
— | RuntimeClass | v1 |
制品库治理建议： 在模板制品库中为每个 Helm Chart 或 Kustomize 项目维护一个
api-versions.yaml 文件，记录当前使用的所有 API 版本及其状态（active / deprecated / removed）。每次升级前，运行自动化脚本对比目标版本与当前版本，生成废弃 API 清单。
2.6 节点排空前的 API 检查清单
在节点排空计划中，API 废弃检查应作为前置条件之一。以下是标准检查清单：
- ☐ 扫描集群：使用
kubectl get --raw /openapi/v2获取集群支持的 API 版本列表。 - ☐ 比对目标版本：下载目标版本的
openapi.json，使用kubectl-diff或kube-apidiff找出已废弃的 API。 - ☐ 检查 CRD：列出所有 CRD 及其使用的 API 版本，确保没有引用
v1beta1的 CRD。 - ☐ 检查 Webhook：确认
MutatingWebhookConfiguration和ValidatingWebhookConfiguration使用的 API 版本未被废弃。 - ☐ 检查 Operator：确保 Operator 管理的资源版本与目标集群兼容。
- ☐ 更新制品库：将模板制品库中的所有 YAML 文件更新为新的 API 版本。
- ☐ 测试验证：在测试集群中执行
kubectl apply --dry-run=server -f <manifest>验证兼容性。
完成上述检查后，方可进入节点排空阶段。API 废弃检查是升级治理模板中不可跳过的安全门禁，直接决定了升级的成功率与业务连续性。