2. K8s API 版本演进机制：API组、版本化、废弃策略及生命周期
Kubernetes API 是集群的“控制面语言”，所有资源（包括 Deployment）的创建、更新、查询都通过 API 完成。理解 API 的版本演进机制，是掌握 Deployment 配置在集群升级前后兼容性适配的基础。Kubernetes 通过 API 组（API Group）、版本化（Versioning） 和 废弃策略（Deprecation Policy） 三个核心设计，实现了 API 的平滑演进。
2.1 API 组：资源分类与隔离
Kubernetes 将 API 划分为多个逻辑组，每个组包含一组相关的资源。API 组解决了早期单一路径（/api/v1）下资源膨胀、命名冲突的问题。
- 核心组（Core Group）：路径为
/api/v1，包含 Pod、Service、Node、Namespace 等最基础的资源。 - 命名组（Named Group）：路径为
/apis/<group-name>/<version>，例如apps/v1、batch/v1、networking.k8s.io/v1。Deployment 属于apps组。
apps/v1 中稳定下来。早期版本（如 extensions/v1beta1、apps/v1beta1、apps/v1beta2）中的 Deployment 已被废弃。集群升级时，必须确保 Deployment 的 apiVersion 字段指向 apps/v1。
2.2 版本化：Alpha → Beta → GA（Stable）
每个 API 组内的资源会经历三个成熟度阶段。每个阶段对应不同的稳定性、功能完整性和默认启用状态。
| 阶段 | 命名约定 | 默认启用 | 功能完整性 | 向后兼容性 | 生产推荐 |
|---|---|---|---|---|---|
| Alpha | v1alpha1, v1alpha2 |
否（需 Feature Gate） | 不完整，可能有大变更 | 不保证 | 不推荐 |
| Beta | v1beta1, v1beta2 |
是 | 基本完整，经过测试 | 通常兼容，但可能弃用 | 谨慎使用 |
| GA / Stable | v1 |
是 | 完整且稳定 | 长期保证 | 强烈推荐 |
apiVersion。如果使用了 extensions/v1beta1 或 apps/v1beta1 等已废弃版本，升级后 API Server 将拒绝这些资源，导致 Pod 无法正常调度。
2.3 废弃策略与生命周期
Kubernetes 官方定义了清晰的 API 废弃策略，确保用户有足够时间迁移。核心规则如下：
- GA 版本：标记为废弃后，至少保留 12 个月或 3 个次要版本（取较长者）。
- Beta 版本：标记为废弃后，至少保留 9 个月或 3 个次要版本（取较长者）。
- Alpha 版本：可在任何版本中移除，不提供兼容性保证。
以下表格展示了 Deployment 相关 API 版本的演进与废弃时间线：
| API 版本 | 引入版本 | 废弃版本 | 移除版本 | 状态 |
|---|---|---|---|---|
extensions/v1beta1 |
1.2 | 1.9 | 1.16 | 已移除 |
apps/v1beta1 |
1.8 | 1.9 | 1.16 | 已移除 |
apps/v1beta2 |
1.8 | 1.9 | 1.16 | 已移除 |
apps/v1 |
1.9 | — | — | 当前稳定版 |
kubectl convert 或 kubectl apply --dry-run=server 验证所有 Deployment 的 API 版本兼容性。推荐将所有 Deployment 的 apiVersion 统一为 apps/v1。
2.4 API 版本演进流程示意图
下图展示了 API 版本从 Alpha 到 GA 的演进路径，以及废弃后的移除时间线：
2.5 废弃 API 的检测与迁移
在集群升级前，SRE 必须主动检测并迁移已废弃的 API 版本。以下是推荐的检测步骤：
- 使用
kubectl convert命令：将旧版本资源转换为目标版本。 - 使用
kubectl apply --dry-run=server：在服务端验证资源是否被当前 API Server 接受。 - 审计集群中的资源：通过
kubectl get --raw或第三方工具（如pluto）扫描所有资源。
extensions/v1beta1 迁移到 apps/v1。
# 查看当前 Deployment 的 apiVersion
kubectl get deployment my-deploy -o jsonpath='{.apiVersion}'
# 使用 kubectl convert 转换
kubectl convert -f old-deploy.yaml --output-version apps/v1 > new-deploy.yaml
# 应用新版本
kubectl apply -f new-deploy.yaml2.6 版本兼容性矩阵
以下表格总结了不同 Kubernetes 版本中 Deployment 可用的 API 版本，帮助你在升级前快速判断兼容性：
| K8s 版本 | 可用 Deployment API 版本 | 推荐版本 |
|---|---|---|
| 1.8 及更早 | extensions/v1beta1, apps/v1beta1, apps/v1beta2 |
apps/v1beta2 |
| 1.9 – 1.15 | extensions/v1beta1, apps/v1beta1, apps/v1beta2, apps/v1 |
apps/v1 |
| 1.16 及以上 | apps/v1（其他版本已移除） |
apps/v1 |
extensions/v1beta1、apps/v1beta1 和 apps/v1beta2 中的 Deployment 已被完全移除。如果集群版本 ≥ 1.16，必须使用 apps/v1。
2.7 内部存储版本与外部版本
Kubernetes API Server 内部使用一个“存储版本”（Storage Version）来持久化资源。外部版本（External Version）用于客户端与 API Server 的交互。API Server 负责在外部版本和内部版本之间进行转换。
- 存储版本：通常是 GA 版本（如
apps/v1），所有数据以该版本写入 etcd。 - 外部版本：客户端可以请求任何支持的版本，API Server 自动转换。
这种设计允许客户端使用旧版本 API 读取资源，即使 etcd 中存储的是新版本格式。但前提是旧版本 API 尚未被移除。
apps/v1beta2 变为 apps/v1），API Server 会自动转换 etcd 中的数据。但客户端必须使用新的外部版本，否则会收到 404 错误。
2.8 总结：API 版本演进对 Deployment 配置的影响
API 版本演进机制直接决定了 Deployment 配置在集群升级前后的兼容性。核心要点如下：
- 始终使用
apps/v1：这是 Deployment 的 GA 版本，长期稳定且兼容。 - 升级前审计：检查所有 Deployment 的
apiVersion，确保没有使用已废弃版本。 - 利用转换工具：使用
kubectl convert或kubectl apply --dry-run=server验证兼容性。 - 关注废弃时间线：每个版本都有明确的废弃和移除时间，提前规划迁移窗口。