本文发表于一年多前。旧文章可能包含过时内容。请检查页面中的信息自发布以来是否已变得不正确。

Kubernetes 1.22 中的 API 和特性移除：你需要知道什么

作者：Krishna Kilari (Amazon Web Services), Tim Bannister (The Scale Factory) |

随着 Kubernetes API 的发展，API 会定期重组或升级。当 API 演进时，它们替换的旧 API 会被弃用，并最终被移除。请参阅Kubernetes API 移除以了解更多关于 Kubernetes 移除 API 的策略。

我们想确保您了解一些即将进行的移除。这些是您可以在当前支持的 Kubernetes 版本中使用的 Beta API，并且它们已经被弃用。所有这些移除的原因是它们已被更新的稳定（“GA”）API 取代。

Kubernetes 1.22（计划于 2021 年 8 月发布）将移除许多已弃用的 API。更新：Kubernetes 1.22：迈向新高峰包含 v1.22 发布的详细信息。

Kubernetes v1.22 的 API 移除

v1.22 版本将停止提供我们下面立即列出的 API 版本。这些都是 Beta API，之前已被弃用，取而代之的是更新、更稳定的 API 版本。

  • ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration API 的 Beta 版本（admissionregistration.k8s.io/v1beta1 API 版本）
  • Beta CustomResourceDefinition API（apiextensions.k8s.io/v1beta1）
  • Beta APIService API（apiregistration.k8s.io/v1beta1）
  • Beta TokenReview API（authentication.k8s.io/v1beta1）
  • SubjectAccessReview、LocalSubjectAccessReview、SelfSubjectAccessReview 的 Beta API 版本（来自 authorization.k8s.io/v1beta1 的 API 版本）
  • Beta CertificateSigningRequest API（certificates.k8s.io/v1beta1）
  • Beta Lease API（coordination.k8s.io/v1beta1）
  • 所有 Beta Ingress API（extensions/v1beta1 和 networking.k8s.io/v1beta1 API 版本）

Kubernetes 文档涵盖了这些v1.22 的 API 移除，并解释了每个 API 在 Beta 和稳定版本之间如何变化。

如何应对

我们将逐一介绍受这些移除影响的资源，并解释您需要采取的步骤。

Ingress
迁移到使用 networking.k8s.io/v1 Ingress API，该 API 自 v1.19 起可用。
相关的 API IngressClass 旨在补充 Ingress 概念，允许您在单个集群中配置多种 Ingress。如果您目前使用的是已弃用的 kubernetes.io/ingress.class 注解，请计划改用 .spec.ingressClassName 字段。
在运行 Kubernetes v1.19 或更高版本的任何集群上，您可以使用 v1 API 检索或更新现有 Ingress 对象，即使它们是使用旧版 API 创建的。

将 Ingress 转换为 v1 API 时，您应该审查该 Ingress 中的每条规则。旧版 Ingress 使用传统的 ImplementationSpecific 路径类型。 вместо ImplementationSpecific，请将路径匹配切换为 Prefix 或 Exact。切换到这些替代路径类型的好处之一是，它使在不同 Ingress 类之间迁移变得更容易。

ⓘ 除了升级您自己作为客户端对 Ingress API 的使用之外，还要确保您使用的每个 Ingress 控制器都与 v1 Ingress API 兼容。阅读Ingress 前提条件以获取有关 Ingress 和 Ingress 控制器的更多上下文。

ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration
迁移到使用 ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration 的 admissionregistration.k8s.io/v1 API 版本，该 API 自 v1.16 起可用。
您可以使用 v1 API 检索或更新现有对象，即使它们是使用旧版 API 创建的。
CustomResourceDefinition
迁移到使用 CustomResourceDefinition apiextensions.k8s.io/v1 API，该 API 自 v1.16 起可用。
您可以使用 v1 API 检索或更新现有对象，即使它们是使用旧版 API 创建的。如果您在集群中定义了任何自定义资源，则在升级后这些资源仍将可用。

如果您正在使用外部 CustomResourceDefinitions，可以使用kubectl convert将现有清单转换为使用更新的 API。由于 Beta 和稳定版 CustomResourceDefinitions 之间存在一些功能差异，我们建议您在升级后测试每个自定义资源，以确保它按预期工作。

APIService
迁移到使用 apiregistration.k8s.io/v1 APIService API，该 API 自 v1.10 起可用。
您可以使用 v1 API 检索或更新现有对象，即使它们是使用旧版 API 创建的。如果您已经使用 APIService 对象进行了 API 聚合，则在升级后此聚合将继续工作。
TokenReview
迁移到使用 authentication.k8s.io/v1 TokenReview API，该 API 自 v1.10 起可用。

除了通过 HTTP 提供此 API 之外，Kubernetes API 服务器还使用相同的格式将 TokenReviews 发送到 webhook。v1.22 版本默认继续使用 v1beta1 API 将 TokenReviews 发送到 webhook。请参阅展望未来，了解一些关于切换到稳定 API 的具体提示。

SubjectAccessReview、SelfSubjectAccessReview 和 LocalSubjectAccessReview
迁移到使用这些授权 API 的 authorization.k8s.io/v1 版本，该 API 自 v1.6 起可用。
CertificateSigningRequest
迁移到使用 certificates.k8s.io/v1 CertificateSigningRequest API，该 API 自 v1.19 起可用。
您可以使用 v1 API 检索或更新现有对象，即使它们是使用旧版 API 创建的。升级后，现有已颁发证书的有效期将保持不变。
Lease
迁移到使用 coordination.k8s.io/v1 Lease API，该 API 自 v1.14 起可用。
您可以使用 v1 API 检索或更新现有对象，即使它们是使用旧版 API 创建的。

kubectl convert

有一个 kubectl 插件提供 kubectl convert 子命令。它是一个官方插件，您可以作为 Kubernetes 的一部分下载。有关详细信息，请参阅下载 Kubernetes。

您可以使用 kubectl convert 更新清单文件以使用不同的 API 版本。例如，如果您在源代码控制中有一个使用 Beta Ingress API 的清单，您可以检出该定义，并运行 kubectl convert -f <manifest> --output-version <group>/<version>。您可以使用 kubectl convert 命令自动转换现有清单。

例如，要将旧的 Ingress 定义转换为 networking.k8s.io/v1，您可以运行

kubectl convert -f ./legacy-ingress.yaml --output-version networking.k8s.io/v1

自动转换使用与 Kubernetes 控制平面更新最初使用旧 API 版本创建的对象类似的技术。由于它是机械转换，您可能需要手动更改清单以调整默认值等。

为升级进行演练

如果您管理集群的 API 服务器组件，您可以在升级到 Kubernetes v1.22 之前尝试这些 API 移除。

为此，请将以下内容添加到 kube-apiserver 命令行参数中

--runtime-config=admissionregistration.k8s.io/v1beta1=false,apiextensions.k8s.io/v1beta1=false,apiregistration.k8s.io/v1beta1=false,authentication.k8s.io/v1beta1=false,authorization.k8s.io/v1beta1=false,certificates.k8s.io/v1beta1=false,coordination.k8s.io/v1beta1=false,extensions/v1beta1/ingresses=false,networking.k8s.io/v1beta1=false

（作为副作用，这也会关闭 EndpointSlice 的 v1beta1 - 在测试时请注意这一点）。

一旦您将集群中所有 kube-apiserver 切换为使用该设置，这些 Beta API 将被移除。您可以测试 API 客户端（kubectl、部署工具、自定义控制器等）是否仍按预期工作，并且如果需要，您可以恢复而无需计划更具破坏性的降级。

对软件开发者的建议

也许您正在阅读本文，因为您是与 Kubernetes 集成的插件或其他组件的开发人员？

如果您开发 Ingress 控制器、Webhook 身份验证器、API 聚合或任何依赖这些已弃用 API 的其他工具，您应该已经开始切换您的软件。

您可以使用为升级进行演练中的提示来运行您自己的只使用新 API 的 Kubernetes 集群，并确保您的代码正常工作。对于您的文档，请确保读者了解他们在 Kubernetes v1.22 升级时应采取的任何步骤。

在可能的情况下，帮助您的用户尽早采用新的 API——也许在测试环境中——这样他们就可以向您提供有关任何问题的反馈。

Kubernetes v1.25 中还有一些更多的弃用，所以请计划好也要涵盖这些。

Kubernetes API 移除

以下是关于 Kubernetes 为什么要移除某些 API 的一些背景信息，以及关于 Kubernetes 中稳定API 的承诺。

Kubernetes 遵循其功能的弃用策略，包括 Kubernetes API。该策略允许替换 Kubernetes 中的稳定 (“GA”) API。重要的是，此策略意味着只有当同一 API 的较新稳定版本可用时，稳定 API 才会被弃用。

这种稳定性保证很重要：如果您正在使用稳定的 Kubernetes API，则永远不会发布强制您切换到 Alpha 或 Beta 功能的新版本。

早期阶段则不同。Alpha 功能正在测试中，可能不完整。几乎总是，Alpha 功能默认是禁用的。Kubernetes 版本可以并且确实会移除未成功的 Alpha 功能。

在 Alpha 之后是 Beta。这些功能通常默认启用；如果测试成功，该功能可以升级到稳定版。如果失败，可能需要重新设计。

去年，Kubernetes 正式采纳了针对已达到 Beta 阶段的 API 的策略

对于 Kubernetes REST API，当新功能的 API 达到 Beta 阶段时，就会开始倒计时。这个 Beta 质量的 API 现在有三个版本……要不

  • 达到 GA，并弃用 Beta 版，或者
  • 推出新的 Beta 版（并弃用之前的 Beta 版）。

在那篇文章发布时，三个 Kubernetes 版本大约相当于九个日历月。同月晚些时候，Kubernetes 采用了每年发布三个版本的新发布节奏，因此倒计时周期现在大约是十二个日历月。

无论 API 移除是因为 Beta 功能升级到稳定版，还是因为该 API 未能成功，Kubernetes 都将继续遵循其弃用策略移除 API，并确保迁移选项已记录在案。

展望未来

如果您使用 webhook 身份验证检查，则有一个相关的设置。未来的 Kubernetes 版本将默认切换为使用 authentication.k8s.io/v1 API 将 TokenReview 对象发送到 webhook。目前，默认是将 authentication.k8s.io/v1beta1 TokenReviews 发送到 webhook，并且这仍然是 Kubernetes v1.22 的默认设置。但是，如果您愿意，现在就可以切换到稳定 API：将 --authentication-token-webhook-version=v1 添加到 kube-apiserver 的命令行选项中，并检查用于身份验证的 webhook 是否仍按预期工作。

一旦您满意它正常工作，您就可以在您的控制平面中保留 --authentication-token-webhook-version=v1 选项。

计划于明年发布的 v1.25 版本将停止提供几个目前已经稳定一段时间的 Kubernetes API 的 Beta 版本。相同的 v1.25 版本将移除 PodSecurityPolicy，该策略已被弃用，并且不会升级到稳定版。有关更多信息，请参阅PodSecurityPolicy 弃用：过去、现在和未来。

Kubernetes 1.25 计划的官方API 移除列表是

  • Beta CronJob API（batch/v1beta1）
  • Beta EndpointSlice API（networking.k8s.io/v1beta1）
  • Beta PodDisruptionBudget API（policy/v1beta1）
  • Beta PodSecurityPolicy API（policy/v1beta1）

想了解更多吗？

弃用会在 Kubernetes 发布说明中宣布。您可以在 1.19、1.20 和 1.21 的发布说明中查看待弃用功能的公告。

有关弃用和移除过程的信息，请查看官方的 Kubernetes 弃用策略文档。