Kubernetes 弃用策略

本文档详细介绍了系统各个方面的弃用策略。

Kubernetes 是一个拥有众多组件和贡献者的庞大系统。与任何此类软件一样，其功能集会随着时间的推移而自然演变，有时可能需要移除某个功能。这可能包括 API、标志，甚至整个功能。为了避免破坏现有用户，Kubernetes 对计划移除的系统方面遵循弃用策略。

弃用 API 的部分

由于 Kubernetes 是一个 API 驱动的系统，因此 API 随着时间的推移而演变，以反映对问题空间的不断理解。Kubernetes API 实际上是一组 API，称为“API 组”，每个 API 组都独立版本化。 API 版本 分为 3 个主要轨道，每个轨道都有不同的弃用策略

Kubernetes 的给定版本可以支持任意数量的 API 组和每个 API 组的任意数量的版本。

以下规则管理 API 元素的弃用。这包括

• REST 资源（又称 API 对象）
• REST 资源的字段
• REST 资源上的注释，包括“beta”注释，但不包括“alpha”注释。
• 枚举或常量值
• 组件配置结构

这些规则在正式版本之间执行，而不是在对 master 或发布分支的任意提交之间执行。

规则 #1：API 元素只能通过增加 API 组的版本来移除。

一旦某个 API 元素在特定版本的 API 组中添加，就无法从该版本中移除，也无法对其行为进行重大更改，无论轨道如何。

规则 #2：API 对象必须能够在给定版本之间的 API 版本之间进行往返，而不会丢失信息，除了在某些版本中不存在的整个 REST 资源。

例如，可以将对象写入 v1，然后将其读回为 v2 并转换为 v1，结果 v1 资源将与原始资源相同。v2 中的表示可能与 v1 不同，但系统知道如何在两个方向上进行转换。此外，在 v2 中添加的任何新字段都必须能够往返于 v1，这意味着 v1 可能必须添加一个等效字段或将其表示为注释。

规则 #3：给定轨道中的 API 版本不得以更不稳定的 API 版本为代价而被弃用。

• GA API 版本可以替换 beta 和 alpha API 版本。
• Beta API 版本可以替换更早的 beta 和 alpha API 版本，但不得替换 GA API 版本。
• Alpha API 版本可以替换更早的 alpha API 版本，但不得替换 GA 或 beta API 版本。

规则 #4a：API 寿命由 API 稳定性级别决定

• GA API 版本可能被标记为已弃用，但在 Kubernetes 的主要版本中不得被移除
• Beta API 版本在引入后不超过 9 个月或 3 个次要版本（以较长者为准）被弃用，并且在弃用后不超过 9 个月或 3 个次要版本（以较长者为准）不再提供服务
• Alpha API 版本可以在任何版本中被移除，而无需事先弃用通知

这确保 beta API 支持涵盖 最大支持版本偏差 2 个版本，并且 API 不会停留在不稳定的 beta 版本上，积累将在 beta API 支持结束时被中断的生产使用。

规则 #4b：给定组的“首选”API 版本和“存储版本”不得在发布支持新版本和先前版本的版本之前推进

用户必须能够升级到 Kubernetes 的新版本，然后回滚到以前版本，而无需将任何内容转换为新 API 版本或出现故障（除非他们明确使用了仅在较新版本中可用的功能）。这在对象的存储表示中尤为明显。

所有这些都最好通过示例来说明。想象一个 Kubernetes 版本 X，它引入了新的 API 组。大约每 4 个月（每年 3 次）发布一个新的 Kubernetes 版本。下表描述了后续一系列版本中支持哪些 API 版本。

REST 资源（又称 API 对象）

考虑一个名为 Widget 的假想 REST 资源，它在上述时间表中 API v1 中存在，并且需要被弃用。我们与版本 X+1 同步记录并 宣布 弃用。Widget 资源仍然存在于 API 版本 v1（已弃用）中，但不存在于 v2alpha1 中。Widget 资源在直至版本 X+8（含）的版本中继续存在并正常工作。只有在版本 X+9 中，当 API v1 已经过时时，Widget 资源才会停止存在，并且行为会被移除。

从 Kubernetes v1.19 开始，向已弃用的 REST API 端点发出 API 请求

1. 在 API 响应中返回一个Warning 标头（如 RFC7234，第 5.5 节 中所定义）。

2. 向 审核事件 添加一个"k8s.io/deprecated":"true" 注释，该事件记录了该请求。

3. 在kube-apiserver 进程中将apiserver_requested_deprecated_apis 测量指标设置为1。该指标具有group、version、resource、subresource 等标签，可以与apiserver_request_total 指标相结合，以及一个removed_release 标签，表示将在哪个 Kubernetes 版本中移除该 API。以下 Prometheus 查询返回有关对已弃用 API 的请求的信息，这些 API 将在 v1.22 中被移除

   apiserver_requested_deprecated_apis{removed_release="1.22"} * on(group,version,resource,subresource) group_right() apiserver_request_total
   

REST 资源的字段

与整个 REST 资源一样，在 API v1 中存在的单个字段必须存在并正常工作，直到 API v1 被移除。与整个资源不同，v2 API 可以选择对该字段使用不同的表示形式，只要它可以进行往返即可。例如，一个名为“magnitude”的 v1 字段可能在 API v2 中被命名为“deprecatedMagnitude”。当 v1 最终被移除时，可以从 v2 中移除已弃用的字段。

枚举或常量值

与整个 REST 资源及其字段一样，在 API v1 中支持的常量值必须存在并正常工作，直到 API v1 被移除。

组件配置结构

组件配置的版本化和管理方式与 REST 资源类似。

未来工作

随着时间的推移，Kubernetes 将引入更细粒度的 API 版本，届时将根据需要调整这些规则。

弃用标志或 CLI

Kubernetes 系统由多个不同的程序协同工作组成。有时，Kubernetes 版本可能会移除这些程序中的标志或 CLI 命令（统称为“CLI 元素”。这些程序自然地分为两大类 - 面向用户和面向管理员的程序，它们在弃用策略方面略有不同。除非标志明确加名前缀或记录为“alpha”或“beta”，否则它被认为是 GA。

CLI 元素实际上是系统 API 的一部分，但由于它们不像 REST API 那样版本化，因此弃用规则如下

规则 #5a：面向用户的组件（例如 kubectl）的 CLI 元素在其宣布弃用后必须至少正常工作

• GA：12 个月或 2 个版本（以较长者为准）
• Beta：3 个月或 1 个版本（以较长者为准）
• Alpha：0 个版本

规则 #5b：面向管理员的组件（例如 kubelet）的 CLI 元素在其宣布弃用后必须至少正常工作

• GA：6 个月或 1 个版本（以较长者为准）
• Beta：3 个月或 1 个版本（以较长者为准）
• Alpha：0 个版本

规则 #5c：命令行界面 (CLI) 元素不得以更不稳定的 CLI 元素为代价而被弃用

类似于 API 的规则 #3，如果命令行界面中的某个元素被另一种实现替换，例如通过重命名现有元素，或通过切换到使用从文件而不是命令行参数中获取的配置，那么建议的替代方案必须具有相同或更高的稳定性级别。

规则 #6：弃用的 CLI 元素必须在使用时发出警告（可以选择禁用）。

弃用功能或行为

有时，Kubernetes 版本需要弃用系统中不受 API 或 CLI 控制的某些功能或行为。在这种情况下，弃用规则如下

规则 #7：弃用的行为在其宣布弃用后必须至少正常工作 1 年。

如果要使用需要工作才能采用更改的替代实现来替换功能或行为，则应尽力简化过渡。如果替代实现处于 Kubernetes 组织的控制之下，则适用以下规则

规则 #8：不得将功能或行为弃用，以支持稳定性较低的替代实现。

例如，不能将通用可用功能弃用，以支持 Beta 版本的替代方案。但是，Kubernetes 项目鼓励用户在替代实现达到相同的成熟度级别之前，就采用并过渡到替代实现。这对于探索功能的新用例或尽早获得有关替代方案的反馈特别重要。

替代实现有时可能是外部工具或产品，例如，功能可能会从 kubelet 移动到不受 Kubernetes 项目控制的容器运行时。在这种情况下，无法应用此规则，但必须努力确保存在一条过渡路径，不会影响组件的成熟度级别。以容器运行时为例，此努力可能涉及尝试确保流行的容器运行时具有能够提供相同稳定性级别同时实现替代行为的版本。

功能和行为的弃用规则并不意味着所有系统更改都受此策略管辖。这些规则仅适用于会影响在 Kubernetes 上运行的应用程序的正确性或影响 Kubernetes 集群管理的显着用户可见行为，并且这些行为将被完全删除。

上述规则的例外情况是 *功能门*。功能门是键值对，允许用户启用/禁用实验性功能。

功能门旨在涵盖功能的开发生命周期 - 它们并非旨在作为长期 API。因此，它们预计将在功能变为 GA 或被丢弃后被弃用并删除。

随着功能在各个阶段的移动，相关的功能门也会随之演变。与相应功能门匹配的功能生命周期是

• Alpha：功能门默认情况下处于禁用状态，用户可以启用它。
• Beta：功能门默认情况下处于启用状态，用户可以禁用它。
• GA：功能门已弃用（参见 "弃用"），并且不再起作用。
• GA，弃用窗口已完成：功能门已删除，不再接受对它的调用。

弃用

功能可以在生命周期的任何阶段（在 GA 之前）被删除。当功能在 GA 之前被删除时，它们的关联功能门也会被弃用。

当调用尝试禁用不起作用的功能门时，调用将失败，以避免可能在静默运行的情况下出现的不受支持的情况。

在某些情况下，删除 GA 之前的功能需要相当长的时间。功能门可以保持起作用，直到其关联的功能被完全删除，此时功能门本身可以被弃用。

当删除 GA 功能的功能门也需要相当长的时间时，如果功能门对功能没有影响，并且功能门不会导致错误，则对功能门的调用可能会保持起作用。

旨在由用户禁用的功能应包含一种在关联的功能门中禁用该功能的机制。

功能门的版本控制与之前讨论的组件不同，因此弃用规则如下

规则 #9：当它们控制的相应功能过渡到生命周期阶段时，必须弃用功能门。功能门必须至少起作用

• Beta 功能到 GA：6 个月或 2 个版本（以较长者为准）
• Beta 功能到 EOL：3 个月或 1 个版本（以较长者为准）
• Alpha 功能到 EOL：0 个版本

规则 #10：弃用的功能门在使用时必须响应警告。当功能门被弃用时，它必须在发行说明和相应的 CLI 帮助中进行记录。警告和文档都必须指示功能门是否不起作用。

弃用指标

Kubernetes 控制平面的每个组件都公开指标（通常是 /metrics 端点），这些指标通常由集群管理员摄取。并非所有指标都相同：一些指标通常用作 SLI 或用于确定 SLO，这些指标往往具有更大的重要性。其他指标在本质上更具实验性，或者主要用于 Kubernetes 开发过程。

因此，指标分为三个稳定性类别（ALPHA、BETA STABLE）；这会影响在 Kubernetes 版本期间删除指标。这些类别由指标的感知重要性决定。弃用和删除指标的规则如下

规则 #11a：对于相应稳定性类别，指标必须至少起作用

• STABLE：4 个版本或 12 个月（以较长者为准）
• BETA：2 个版本或 8 个月（以较长者为准）
• ALPHA：0 个版本

规则 #11b：指标在 *宣布弃用* 后，必须至少起作用

• STABLE：3 个版本或 9 个月（以较长者为准）
• BETA：1 个版本或 4 个月（以较长者为准）
• ALPHA：0 个版本

弃用的指标的描述文本将以弃用通知字符串 '(Deprecated from x.y)' 为前缀，并且在指标注册期间将发出警告日志。与它们稳定的未弃用对应项一样，弃用的指标将自动注册到指标端点，因此可见。

在后续版本中（当指标的 deprecatedVersion 等于 *current_kubernetes_version - 3* 时），弃用的指标将成为 *隐藏* 指标。**与** 它们的弃用对应项 **不同**，隐藏指标 *不再* 自动注册到指标端点（因此隐藏）。但是，可以通过二进制文件上的命令行标志（--show-hidden-metrics-for-version=）显式启用它们。这为集群管理员提供了一个紧急出口，以便在他们无法对早期的弃用警告做出反应的情况下，正确迁移出弃用的指标。隐藏指标应该在发布一个版本后被删除。

例外

没有一项策略可以涵盖所有可能的情况。此策略是一份动态文件，并将随着时间的推移而不断发展。实际上，会有一些情况不适合此策略，或者此策略会成为一个严重的障碍。对于此类情况，应与 SIG 和项目负责人讨论，以找到针对这些特定情况的最佳解决方案，始终牢记 Kubernetes 致力于成为一个稳定的系统，尽可能避免对用户造成影响。所有相关的发行说明中都会宣布例外情况。