1. API 版本演进概述

Kubernetes API 是控制平面的核心通信契约，所有资源操作（创建、查询、更新、删除）均通过 API Server 完成。API 版本化设计直接决定了集群的可升级性、资源兼容性以及生态工具的适配成本。本节从设计哲学、版本生命周期、废弃策略与迁移路径三个维度展开，帮助学员建立对 API 版本演进的系统性认知。

1.1 API 版本化设计哲学

Kubernetes 的 API 版本化遵循以下核心原则：

• 向前兼容：同一资源在 stable 版本内，字段语义和默认行为不产生破坏性变更；新增字段必须使用 optional 或通过 feature gate 控制。
• 版本独立：每个 API 版本（如 v1、v1beta1）在 API Server 内部以独立的 codec 和 storage 版本存在，互不干扰。
• 存储版本唯一：etcd 中只存储一个 internal 版本（通常为 stable 版本），其他版本通过转换 Webhook 或内部转换器实现读写转换。
• 渐进式废弃：废弃一个 API 版本至少跨越 3 个 minor 版本，给予用户充足的迁移窗口。

1.2 alpha / beta / stable 版本生命周期

每个 API 版本在进入稳定版之前，会依次经过 alpha 和 beta 阶段。下表总结了各阶段的核心特征：

一个典型资源从 alpha 到 stable 的演进路径通常需要 2~4 个 minor 版本：

1. Alpha 引入：在某个 minor 版本中首次以 v1alpha1 出现，默认关闭，需显式开启 feature gate。
2. Beta 晋升：经过至少 1 个 minor 版本的 alpha 验证后，晋升为 v1beta1，默认启用。
3. Stable 毕业：beta 阶段至少持续 2 个 minor 版本，确认无重大缺陷后晋升为 v1。
4. 旧版本废弃：stable 版本发布后，旧 beta 版本进入废弃周期（通常标记为 deprecated），并在后续 3 个 minor 版本内移除。

1.3 版本废弃策略与迁移路径

Kubernetes 社区制定了严格的 API 版本废弃策略，确保集群管理员和生态工具开发者有足够的时间适配新版本。废弃策略的核心规则如下：

• 废弃公告：当某个 API 版本被标记为 deprecated 时，API Server 会在响应中返回 Warning 头部，提示客户端升级。
• 最少保留周期：从废弃到移除，至少跨越 3 个 minor 版本（例如 1.25 废弃 → 1.28 移除）。
• 存储版本优先：废弃的 beta 版本不再作为存储版本，所有数据自动转换为 stable 版本存储。
• 转换 Webhook 支持：对于自定义资源（CRD），如果存在多个版本，必须配置 Conversion Webhook 或内部转换策略，确保旧版本读写正确。

迁移路径通常遵循以下步骤：

1. 审计当前版本：使用 kubectl api-resources --api-group=<group> 列出集群中所有资源及其可用版本。
2. 识别废弃版本：检查 kubectl get --raw /openapi/v2 或 kubectl get --raw /version 中的废弃标记。
3. 更新 YAML 清单：将 apiVersion 字段从废弃版本（如 apps/v1beta1）升级到当前 stable 版本（如 apps/v1）。
4. 验证转换：使用 kubectl convert 命令或 kubectl apply --server-side 测试新版本清单的兼容性。
5. 更新 CI/CD 与工具：确保 Helm chart、Kustomize overlay、Operator 等工具中的 API 版本引用同步更新。

1.4 版本废弃时间线参考

下表列出了 Kubernetes 近几个版本中重要的 API 废弃事件，帮助学员建立时间线感知：