📚 课程目录第4章 API废弃生命周期

4. API 废弃生命周期：Kubernetes API 废弃策略、废弃阶段与版本演进

在多集群环境中，不同集群可能运行着多个 Kubernetes 版本。API 资源的版本演进（Alpha → Beta → GA → Deprecated → Removed）直接决定了工作负载的兼容性。理解 API 废弃生命周期，是进行版本漂移校准与交付前验收的核心前提。

Kubernetes 使用明确的版本标识符来管理 API 资源的稳定性与可用性。每个 API 版本都对应一个特定的生命周期阶段，决定了该资源在生产环境中的使用策略。

版本标识	生命周期阶段	默认启用	生产可用	废弃后行为
v1alpha1	Alpha	否（需 Feature Gate）	否	随时可能移除，不保证兼容
v1beta1	Beta	是	建议测试环境	标记 Deprecated 后通常保留 3 个版本
v1	GA / Stable	是	是	标记 Deprecated 后保留至少 12 个月或 3 个版本

验收要点： 在多集群交付验收中，必须确认所有引用的 API 资源均处于 GA（v1）阶段。任何仍在使用 Alpha 或已废弃 Beta 版本的资源，都应视为版本漂移风险项。

Kubernetes 的 API 废弃生命周期包含两个关键阶段：Deprecated（废弃） 和 Removed（移除）。理解这两个阶段的区别，是制定清单化验收策略的基础。

  关键指标： 从 Deprecated 到 Removed 的过渡期，GA 版本至少为 12 个月或 3 个次要版本；Beta 版本至少为 3 个次要版本。多集群验收时，应检查每个集群的 Kubernetes 版本，计算废弃 API 的剩余存活窗口。

Kubernetes 官方对 API 废弃制定了严格的策略，这些策略直接映射到多集群交付验收的检查项中。以下是核心策略及其验收映射关系：

Kubernetes 废弃策略	策略说明	多集群验收映射
最少保留周期	GA API 废弃后至少保留 12 个月或 3 个次要版本	检查目标集群版本是否在保留窗口内
Beta 加速废弃	Beta API 废弃后仅保留 3 个次要版本	Beta 资源需优先迁移，窗口更短
版本偏好	客户端应使用首选版本（Preferred Version）	验证 manifests 中是否使用了非首选版本
向后兼容	同一资源在不同版本间可互转	确认存储版本与 serving 版本的一致性

常见陷阱： 部分集群可能通过 Feature Gate 关闭了某些 Beta API，导致原本可用的资源突然不可用。多集群验收时，必须检查每个集群的 Feature Gate 配置，确保与 API 版本状态一致。

在 Kubernetes API 版本演进中，存在两个关键概念：存储版本（Storage Version） 和 Serving 版本（Serving Version）。理解它们的区别，对于多集群版本漂移校准至关重要。

存储版本：资源在 etcd 中持久化存储的 API 版本。通常为 GA 版本，由 kube-apiserver 的 --storage-versions 参数控制。
Serving 版本：kube-apiserver 对外提供读写服务的 API 版本。客户端可以通过不同版本读写同一资源，apiserver 负责在存储版本与 serving 版本之间进行转换。

  验收检查点： 当某个 API 版本被标记为 Deprecated 后，其 serving 版本仍然可用，但存储版本可能已经迁移到更新的 GA 版本。多集群验收时，应检查 etcd 中存储的资源版本，确保没有遗留的旧版本数据。

基于上述生命周期策略，以下是多集群交付前 API 废弃清单化验收的核心检查项：

版本映射检查：列出所有集群的 Kubernetes 版本，对照官方废弃表，标记每个集群中已废弃的 API 版本。
资源使用审计：使用 kubectl get --raw /openapi/v2 或 kubectl api-resources 检查集群中正在使用的 API 版本。
废弃警告扫描：检查 kube-apiserver 日志中是否包含 deprecated 或 removed 关键字。
迁移窗口计算：根据集群版本与废弃 API 的移除版本，计算剩余迁移时间窗口。
存储版本验证：检查 etcd 中存储的资源版本，确保没有使用已移除的存储版本。

最佳实践： 建议在每个集群中部署 kubectl-deprecations 插件或使用 pluto 工具，自动扫描并生成 API 废弃报告。在多集群交付验收中，将此报告作为清单化验收的附件。