📚 课程目录第3章 API弃用废弃的定义与区别

3. API 弃用废弃的定义与区别：Deprecated vs Removed vs Disabled

在 Kubernetes 集群升级与 API 生命周期治理中，准确区分 Deprecated（弃用）、Removed（移除） 和 Disabled（禁用） 三个概念，是进行依赖分析和节点池巡检的前提。三者虽然都表示 API 不可用或即将不可用，但在时间窗口、影响范围、治理策略上存在本质差异。

核心认知： Deprecated 是“警告信号”，Removed 是“最终结局”，Disabled 是“管理动作”。混淆三者会导致巡检误判或升级失败。

3.1 概念定义与生命周期位置

术语	定义	生命周期阶段	典型触发条件
Deprecated	API 版本被标记为废弃，仍可正常使用，但会在未来版本中移除。	废弃期（通常持续 3~6 个次要版本）	Kubernetes 版本升级后，旧 API 版本被标记为 deprecated
Removed	API 版本已从 Kubernetes 代码库中彻底删除，无法再使用。	移除期（升级后立即生效）	集群升级到移除该 API 的版本
Disabled	API 版本在集群中被人为关闭（通过 feature gate 或 admission webhook），但代码仍存在。	管理期（可随时启用/关闭）	集群管理员主动禁用某 API 版本

3.2 核心区别对比矩阵

对比维度	Deprecated	Removed	Disabled
可用性	完全可用	不可用	不可用
代码存在性	代码保留	代码删除	代码保留
触发方式	版本升级自动标记	版本升级自动移除	管理员手动配置
恢复可能性	不可恢复（版本已标记）	不可恢复（代码已删除）	可恢复（重新启用）
巡检关注点	识别依赖，规划迁移	确认无残留依赖	确认禁用范围正确
升级影响	产生警告日志	直接导致请求失败	取决于禁用策略

3.3 在节点池巡检中的实际表现

在集群升级治理的节点池巡检场景中，三种状态会以不同形式暴露在审计日志、API 请求和节点状态中：

Deprecated 表现： kube-apiserver 日志中出现 WARNING: the v1beta1 API version is deprecated；kubectl 请求返回 Warning 头；Prometheus 指标 apiserver_request_deprecated 递增。
Removed 表现： 请求返回 HTTP 404 或 410（Gone）；kube-controller-manager 报错 unknown API version；节点上运行的旧版 workload 无法创建/更新。
Disabled 表现： 请求被 admission webhook 拒绝，返回 Forbidden；feature gate 状态显示 Disabled=true；节点池中部分节点因 webhook 配置差异出现行为不一致。

  巡检避坑提示： 不要将 Disabled 等同于 Removed。Disabled 的 API 版本在代码中仍然存在，如果后续重新启用，依赖该 API 的 workload 可以立即恢复。而 Removed 的 API 版本即使重新编译也无法恢复，必须迁移到新版本。

3.4 治理优先级与决策树

在节点池巡检中，针对三种状态应采取不同的治理动作：

Deprecated 依赖： 高优先级治理。必须在 Removed 之前完成迁移，否则升级后直接中断。
Removed 依赖： 紧急阻断治理。集群升级前必须确保零残留，否则升级失败。
Disabled 依赖： 按需治理。确认禁用策略是否符合安全基线，避免误禁导致业务中断。

3.5 常见误解与澄清

误解	澄清
Deprecated 的 API 可以一直使用	错误。Deprecated 有明确的生命周期终点，必须在 Removed 前完成迁移。
Disabled 就是 Removed	错误。Disabled 是管理动作，代码仍在；Removed 是代码删除，不可逆。
Deprecated 不影响集群稳定性	部分正确。短期内不影响，但长期不迁移会导致升级阻塞。
节点池巡检只需关注 Removed	错误。Deprecated 依赖是巡检的核心输入，提前发现才能避免升级中断。

实战警告： 在集群升级前，务必使用 kubectl convert 或 kube-no-trouble 等工具扫描所有节点池中的 Deprecated API 依赖。不要等到升级后才发现 Removed 导致的 404 错误，届时回滚成本极高。