Kubernetes 弃用策略

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

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

弃用 API 的部分

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

Kubernetes 的给定版本可以支持任意数量的 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 查询返回有关对将在 v1.22 中删除的已弃用 API 的请求的信息

   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 可以选择使用不同的表示形式来表示该字段，只要它可以往返即可。例如，在 API v1 中被弃用的名为“magnitude”的字段可能在 API v2 中被命名为“deprecatedMagnitude”。当 v1 最终被删除时，可以从 v2 中删除已弃用的字段。

枚举或常量值

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

组件配置结构

组件配置的版本控制和管理方式类似于 REST 资源。

未来工作

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

弃用标志或 CLI

Kubernetes 系统由多个不同的程序协同工作组成。有时，Kubernetes 版本可能会删除这些程序中的标志或 CLI 命令（统称为“CLI 元素”）。各个程序自然地分为两大类 - 面向用户的程序和面向管理员的程序，它们在弃用策略方面略有不同。除非一个标志明确地以“alpha”或“beta”为前缀或在文档中被标记为“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 致力于成为一个稳定的系统，该系统尽可能地不会破坏用户。例外情况将在所有相关的发布说明中宣布。