1. 课程导论：为什么API版本会废弃？K8s版本升级的挑战与风险概述

1.1 API版本废弃的根源：Kubernetes的演进哲学

Kubernetes 是一个以 API 为中心 的容器编排平台。集群中所有的资源操作——Pod、Service、Deployment、Ingress 等——本质上都是对 API 对象的读写。为了在快速迭代的同时保持向后兼容，K8s 社区设计了严格的 API 版本化策略。

API 版本废弃（Deprecation）并非偶然，而是 K8s 演进过程中的必然产物。其核心原因包括：

• 功能迭代与重构：旧 API 字段设计不合理、语义模糊或存在安全隐患，需要引入新版本替代。
• 资源模型统一：例如从 extensions/v1beta1 迁移到 networking.k8s.io/v1，将分散的资源定义收敛到专用 API 组。
• GA（General Availability）稳定化：Beta 阶段的 API 经过生产验证后，会以 GA 版本发布，并逐步淘汰旧版本。
• 社区治理规则：K8s 官方规定，Beta API 在 3 个版本或 9 个月后必须废弃；Alpha API 可能随时移除。

1.2 API 版本生命周期模型

K8s 将 API 版本分为三个阶段，每个阶段对应不同的稳定性和废弃策略：

当集群从低版本升级到高版本时，如果旧版本中使用了已废弃的 API，升级后这些资源将无法被 API Server 识别，导致 资源丢失、控制器失效、甚至集群不可用。

1.3 K8s 版本升级的核心挑战

K8s 版本升级并非简单的“替换二进制文件”。它涉及控制平面、节点、客户端工具、第三方控制器和自定义资源的全面协同。以下是升级过程中最常见的挑战：

1. API 版本不兼容：旧资源使用 extensions/v1beta1，新集群只支持 networking.k8s.io/v1，导致资源无法读取。
2. Feature Gate 变更：某些 Beta 功能在升级后默认启用或禁用，影响 Pod 安全策略、动态卷供应等行为。
3. kubectl 客户端版本滞后：旧版 kubectl 无法识别新版 API，导致 kubectl apply 失败。
4. 第三方控制器兼容性：Ingress Controller、Service Mesh、监控组件等可能未适配新版 API。
5. 自定义资源（CRD）版本冲突：CRD 的存储版本与 serving 版本不一致，导致数据读写异常。
6. etcd 数据格式变化：跨大版本升级时，etcd 中的数据可能需要迁移或重新编码。

1.4 升级风险全景图

为了直观展示升级过程中可能遇到的风险层级，下图梳理了从底层基础设施到上层应用的完整风险链路：

从图中可以看出，风险是 自下而上传递 的：底层基础设施的不兼容会直接导致控制平面异常，进而影响节点和上层应用。而 API 版本废弃 是控制平面层最突出的风险点，也是本课程要重点解决的问题。

1.5 本课程能为你解决什么？

本课程将围绕“API 版本废弃与迁移”这一核心主题，提供一套完整的、可落地的升级方法论：

• 诊断工具链：如何使用 kubectl convert、kube-no-trouble、popeye 等工具扫描集群中的废弃 API。
• 迁移策略：针对 Deployment、Ingress、PodSecurityPolicy 等高频资源的版本迁移步骤。
• 自动化方案：通过 CI/CD 流水线在升级前自动检测并转换 YAML 清单。
• 回滚与容灾：升级失败后的快速回退方案和数据恢复技巧。
• 生产案例：从 1.20 到 1.26 的真实升级踩坑记录与复盘。