2. Kubernetes API 版本机制：API 组、版本（v1alpha1/v1beta1/v1）、版本优先级与存储版本概念

Kubernetes API 的版本机制是集群资源校准与版本管理的核心基础。理解 API 组、版本演进路径、版本优先级以及存储版本的概念，是进行 API 弃用检测和升级规划的前提。本节将系统梳理这些关键概念及其相互关系。

2.1 API 组（API Group）

API 组是 Kubernetes 中资源类型的逻辑分类。每个资源（如 Deployment、Pod、Service）都属于一个特定的 API 组。API 组的设计使得不同功能领域的资源可以独立演进，互不干扰。

API 组在 RESTful API 路径中体现为 /apis/<group>/<version>/<resource>。例如，/apis/apps/v1/deployments 表示 apps 组 v1 版本的 Deployment 资源。

2.2 版本演进路径：v1alpha1 → v1beta1 → v1

Kubernetes 为每个 API 组定义了三个主要的版本阶段，反映了资源的成熟度和稳定性。版本演进遵循严格的准入标准。

• v1alpha1（Alpha 版本）：实验性功能，默认关闭；可能包含重大缺陷；不保证后续版本兼容性；可能在任意版本中被移除。
• v1beta1（Beta 版本）：功能基本稳定，默认开启；经过充分测试；承诺在后续版本中保持向后兼容（通常至少 3 个版本）；弃用前会提前通知。
• v1（GA/稳定版本）：生产就绪；长期支持；保证向后兼容；弃用周期通常为 12 个月或更长。

2.3 版本优先级（Version Priority）

当同一个 API 组中存在多个版本时（例如 apps/v1 和 apps/v1beta2），Kubernetes 通过版本优先级机制确定哪个版本是“首选版本”（Preferred Version）。首选版本是 API 服务器在未指定版本时默认返回的版本，也是 kubectl 等客户端默认使用的版本。

版本优先级规则如下：

1. 稳定性优先：v1 > v1beta1 > v1alpha1
2. 数字版本号优先：v2 > v1（同稳定性级别时）
3. 字母顺序：v1beta2 > v1beta1（同级别时）

2.4 存储版本（Storage Version）

存储版本是 Kubernetes 在 etcd 中实际持久化存储资源对象时使用的版本。每个 API 组中的每个资源只能有一个存储版本。存储版本的选择由 API 服务器的启动参数 --storage-versions 或代码中的默认配置决定。

存储版本与首选版本的关系：

• 可以不同：例如，首选版本是 apps/v1，但存储版本可能是 apps/v1beta2（在迁移过程中）。
• 读写转换：当客户端使用非存储版本读写资源时，API 服务器会自动进行版本转换（Convert）。
• 迁移影响：当存储版本被弃用时，etcd 中所有该版本的资源必须迁移到新的存储版本，否则数据将不可访问。

2.5 版本机制关系图

下图展示了 API 组、版本演进、版本优先级与存储版本之间的整体关系：

2.6 版本转换与数据迁移

当存储版本发生变化时（例如从 v1beta1 升级到 v1），etcd 中已存储的旧版本资源需要被转换并重新写入。Kubernetes 提供了两种转换机制：

• 内部转换（Internal Conversion）：API 服务器在读取/写入时自动完成版本转换，无需用户干预。这是默认行为。
• 显式迁移（Explicit Migration）：通过 kubectl convert 命令或 API 调用手动触发资源迁移。适用于大规模集群或需要精确控制迁移时机的场景。

2.7 版本弃用检测的关键指标

在集群升级资源校准方案中，需要重点监控以下版本相关指标：