Kubernetes API 版本机制：API 组、版本（alpha/beta/stable）、版本优先级与转换

在 Kubernetes 多租户集群的升级工程中，API 版本是决定资源兼容性与迁移路径的核心要素。Kubernetes 通过 API 组（API Group）、版本阶段（alpha/beta/stable）、版本优先级 以及 版本转换（Convert） 四层机制，构建了一套可演进、可废弃的 API 生命周期体系。理解这套机制，是制定多租户集群升级策略的前提。

2.1 API 组：资源分类与命名空间隔离

Kubernetes API 使用 API 组 对资源进行逻辑分组。每个资源属于一个或多个 API 组，组名通常采用 DNS 格式（如 apps、batch、networking.k8s.io）。核心组（core group）没有组名，直接通过 /api/v1 访问。

2.2 版本阶段：alpha、beta、stable

每个 API 组内的资源可以同时存在多个版本，每个版本带有明确的成熟度标识：alpha、beta、stable。这三个阶段决定了功能的可用性、默认启用状态以及废弃策略。

2.3 版本优先级与存储版本

Kubernetes 允许一个资源在多个 API 版本间共存，但 存储版本（storage version） 是唯一持久化到 etcd 的版本。API Server 通过 版本优先级（version priority） 决定哪个版本作为存储版本：优先级最高的 stable 版本被选为存储版本。

版本优先级规则如下：

1. stable 版本 优先级高于 beta 版本，beta 版本高于 alpha 版本。
2. 同阶段内，版本号数值大 的优先级高（如 v2 > v1）。
3. 如果多个版本优先级相同，按 字母序 决定。

以下 SVG 展示了 API 版本优先级与存储版本的选择流程：

2.4 版本转换：内部转换与外部转换

Kubernetes API Server 内置了 版本转换（Version Conversion） 机制，确保客户端可以使用任意支持的版本读写资源，而底层存储始终使用存储版本。转换分为两类：

• 内部转换（Internal Conversion）：API Server 自动完成，无需用户干预。当客户端提交 apps/v1beta1 的 Deployment 时，API Server 将其转换为 apps/v1 格式存储；读取时再反向转换。
• 外部转换（External Conversion）：通过 Conversion Webhook 实现，适用于自定义资源（CRD）或需要复杂转换逻辑的场景。多租户集群中，平台管理员可以为租户 CRD 注册统一的转换 Webhook。

以下 SVG 展示了 API 版本转换的完整流程：

2.5 多租户场景下的版本管理策略

在多租户集群中，API 版本管理需要额外关注以下要点：

• 版本准入控制：通过 Admission Webhook 禁止租户创建使用已废弃或 alpha 版本的资源。
• 存储版本统一：确保所有租户的资源使用相同的存储版本，避免 etcd 中存储格式混乱。
• 版本迁移窗口：在集群升级前，提前通知租户迁移到目标版本，并提供兼容性测试环境。
• 废弃版本监控：使用 kubectl convert 或 API 审计日志，识别仍在使用废弃版本的租户资源。