Kubernetes 1.22 已弃用的 API

Autopilot Standard

本页面介绍如何准备集群以升级到 GKE 1.22 版。您可以找到对 1.22 版中移除的已弃用 API 进行调用的 API 客户端，并更新这些客户端以使用正式版 API。如需了解详情，请参阅 Kubernetes 已弃用的 API 迁移指南。

1.22 中已移除的 API

Kubernetes 1.22 版中大多数已弃用的 API 都是以前的 Beta API，这些 API 已从 Beta 版 (v1beta1) 升级到正式版 (v1)。GA API 提供长期的兼容性保证，并且应该用于取代已弃用的 Beta API。

所有现有对象均可使用 GA API 进行交互。

网络钩子资源

从 1.22 版开始，我们不再提供 MutatingWebhookConfiguration 和 ValidatingWebhookConfiguration 的 Beta API 版本。

迁移清单和 API 客户端以使用 admissionregistration.k8s.io/v1 API 版本。

请参阅下表，了解 GA API 版本中的重大更改：

字段	更改
`webhooks[*].failurePolicy`	默认值已从 `Ignore` 更改为 `Fail`。
`webhooks[*].matchPolicy`	默认值已从 `Exact` 更改为 `Equivalent`。
`webhooks[*].timeoutSeconds`	默认值已从 `30s` 更改为 `10s`。
`webhooks[*].sideEffects`	默认值已移除，且该字段现在是必填字段。仅允许使用 `None` 和 `NoneOnDryRun`。
`webhooks[*].admissionReviewVersions`	默认值已移除，并且该字段现在是必填字段（`AdmissionReview` 的受支持版本是 `v1` 和 `v1beta1`）。
`webhooks[*].name`	在通过 `admissionregistration.k8s.io/v1` 创建的对象列表中，此名称必须是唯一的。

CustomResourceDefinition

从 1.22 版开始，我们不再提供 CustomResourceDefinition 的 Beta API 版本。

迁移清单和 API 客户端以使用 apiextensions.k8s.io/v1 API 版本。

请参阅下表，了解 GA API 版本中的重大更改：

字段	更改
`spec.scope`	不再默认为 `Namespaced`。必须明确指定该值。
`spec.version`	已移除。请改用 `spec.versions`。
`spec.validation`	已移除。请改用 `spec.versions[*].schema`。
`spec.subresources`	已移除。请改用 `spec.versions[*].subresources`。
`spec.additionalPrinterColumns`	已移除。请改用 `spec.versions[*].additionalPrinterColumns`。
`spec.conversion.webhookClientConfig`	已移至 `spec.conversion.webhook.clientConfig`
`spec.conversion.conversionReviewVersions`	已移至 `spec.conversion.webhook.conversionReviewVersions`
`spec.versions[*].schema.openAPIV3Schema`	现在在创建 v1 `CustomResourceDefinition` 对象时是必需的，并且必须是结构架构。
`spec.preserveUnknownFields`	创建 v1 `CustomResourceDefinition` 对象时，不允许使用值 `true`。必须在架构定义中将该值指定为 `x-kubernetes-preserve-unknown-fields: true`。
`additionalPrinterColumns`	在 `additionalPrinterColumns` 项中，`JSONPath` 字段已重命名为 `jsonPath`。

APIService

从 1.22 版开始，我们不再提供 APIService 的 Beta API 版本。迁移清单和 API 客户端以使用 apiregistration.k8s.io/v1 API 版本。

TokenReview

从 1.22 版开始，我们不再提供 TokenReview 的 Beta API 版本。迁移清单和 API 客户端以使用 authentication.k8s.io/v1 API 版本。

SubjectAccessReview 资源

自 1.22 版起，我们不再提供 LocalSubjectAccessReview、SelfSubjectAccessReview 和 SubjectAccessReview 的 Beta API 版本。

迁移清单和 API 客户端以使用 authorization.k8s.io/v1 API 版本。
请参阅下表，了解 GA API 版本中的重大更改：

字段更改

spec.group 已重命名为 spec.groups。

字段	更改
`spec.group`	已重命名为 `spec.groups`。

CertificateSigningRequest

从 1.22 版开始，我们不再提供 CertificateSigningRequest 的 Beta API 版本。

迁移清单和 API 客户端以使用 certificates.k8s.io/v1 API 版本。

请参阅下表，了解 GA API 版本中的重大更改：

字段	更改
`spec.signerName`	对于请求证书的 API 客户端，此字段为必填字段（请参阅已知的 Kubernetes 签名者），并且不允许通过 `certificates.k8s.io/v1` API 创建对 `kubernetes.io/legacy-unknown` 的请求。
`spec.usages`	对于请求证书的 API 客户端，此字段为必填字段。此字段不能包含重复值，并且只能包含已知的用量。
`status.conditions`	对于批准或签署证书的 API 客户端，此字段不能包含重复类型。
`status.conditions[*].status`	对于批准或签署证书的 API 客户端，此字段现在是必填字段。
`status.certificate`	对于批准或签署证书的 API 客户端，此字段必须采用 PEM 编码，并且仅包含 `CERTIFICATE` 块。

Lease

从 1.22 版开始，我们不再提供 Lease 的 Beta API 版本。迁移清单和 API 客户端以使用 coordination.k8s.io/v1 API 版本。

Ingress（在版本 1.21 或更早版本上创建的集群在版本 1.23 之前可用）

如果运行版本 1.22 或更高版本的 GKE 集群是在版本 1.22 或更高版本上创建的，则 Ingress 的 Beta API 版本（extensions/v1beta1 和 networking.k8s.io/v1beta1）不再为这些集群提供服务。

但是，对于在 GKE 1.21 或更早版本上创建并通过补丁程序版本 1.22.7-gke.300 或更高版本升级到版本 1.22 的集群，在集群升级到版本 1.23 之前，您仍然可以使用 Beta API 版本。这是旧版集群的一次性例外，让您可以使用从版本 1.22 中开源 Kubernetes 中移除的这些 API 版本，从而有更多时间迁移集群。

任何运行 GKE 版本 1.23 及更高版本的集群将不再提供已弃用的 Ingress Beta 版 API。使用这些 API 版本的清单将无法再应用。在升级到版本 1.23 前后，以前持久保留的对象仍然有效，并且可以使用新的 API 版本进行查看和更新。

迁移清单和 API 客户端以使用 networking.k8s.io/v1 API 版本。

请参阅下表，了解 GA API 版本中的重大更改：

字段	更改
`spec.backend`	已重命名为 `spec.defaultBackend`。
后端 `serviceName`	已重命名为 `service.name`。
`servicePort`	数字后端 `servicePort` 字段已重命名为 `service.port.number`。字符串后端 `servicePort` 字段已重命名为 `service.port.name`。
`pathType`	现在对于每个指定的路径都是必需的。值可以是：`Prefix`、`Exact` 或 `ImplementationSpecific`。如要匹配未定义的 `v1beta1` 行为，请使用 `ImplementationSpecific`。

以下清单描述了 v1 和 v1beta1 中的同一 Ingress：

v1beta1 清单

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: example
spec:
  backend:
    serviceName: default-backend
    servicePort: 80
  rules:
  - http:
      paths:
      - path: /testpath
        backend:
          serviceName: test
          servicePort: 80

v1 清单

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example
spec:
  defaultBackend:
    service:
      name: default-backend
      port:
        number: 80
  rules:
  - http:
      paths:
      - path: /testpath
        pathType: ImplementationSpecific
        backend:
          service:
            name: test
            port:
              number: 80

您可以对启用了 Google Cloud Observability 的集群使用以下查询，以识别访问 Ingress v1beta1 API 的客户端：

resource.type="k8s_cluster"
resource.labels.cluster_name="$CLUSTER_NAME"
protoPayload.authenticationInfo.principalEmail:("system:serviceaccount" OR "@")
protoPayload.request.apiVersion=("extensions/v1beta1" OR "networking.k8s.io/v1beta1")
protoPayload.request.kind="Ingress"
NOT ("kube-system")

IngressClass

从 1.22 版开始，我们不再提供 IngressClass 的 Beta API 版本。迁移清单和 API 客户端以使用 networking.k8s.io/v1 API 版本。

RBAC 资源

自 1.22 版起，我们不再提供 ClusterRole、ClusterRoleBinding、Role 和 RoleBinding 的 Beta API 版本。迁移清单和 API 客户端以使用 rbac.authorization.k8s.io/v1 API 版本。

PriorityClass

从 1.22 版开始，我们不再提供 PriorityClass 的 Beta API 版本。迁移清单和 API 客户端以使用 scheduling.k8s.io/v1 API 版本。

存储资源

自 1.22 版起，我们不再提供 CSIDriver、CSINode、StorageClass 和 VolumeAttachment 的 Beta API 版本。迁移清单和 API 客户端以使用 storage.k8s.io/v1 API 版本。

查找使用已弃用 API 的集群

您可以通过弃用数据分析查找哪些集群在使用已弃用的 API。弃用数据分析还提供哪些 API 客户端正在调用集群中的已弃用 API 等信息。

您还可以使用审核日志来查找哪些客户端在调用已弃用的 API。

找到对已弃用的 API 进行写入调用的 API 客户端

对于启用了 Google Cloud Observability 的集群，您可以使用以下管理员活动审核日志查询来显示非 Google 管理的用户代理使用已弃用 API 的情况：

resource.type="k8s_cluster"
labels."k8s.io/removed-release"="DEPRECATED_API_MINOR_VERSION"
protoPayload.authenticationInfo.principalEmail:("system:serviceaccount" OR "@")
protoPayload.authenticationInfo.principalEmail!~("system:serviceaccount:kube-system:")

将 DEPRECATED_API_MINOR_VERSION 替换为已移除弃用的 API 的次要版本，例如 1.22。

系统会自动为 GKE 集群启用管理员活动审核日志。运行此查询后，日志会显示对已弃用的 API 进行写入调用的用户代理。

找到对已弃用的 API 进行读取调用的 API 客户端

默认情况下，审核日志仅显示对已弃用 API 的写入调用。如需显示对已弃用 API 的读取调用，请配置数据访问审核日志。

按照说明使用 Google Cloud 控制台配置数据访问审核日志。在 Google Cloud 控制台中，选择 Kubernetes Engine API。在信息面板的“日志类型”标签页中，选择 Admin Read 和 Data Read。

启用这些日志后，您现在可以使用原始查询来查看已弃用 API 的读取调用和写入调用。

升级第三方组件

弃用数据洞见可能会显示调用集群中已弃用 API 的第三方代理的结果。

如需解决这些数据洞见问题，请尝试以下步骤：

请咨询您的第三方软件提供商以获取更新的版本。
将第三方软件升级到最新版本。如果您无法升级软件，则应测试将 GKE 升级到已移除的 API 的版本是否会破坏您的服务。

我们建议您在预演集群上执行此升级和 GKE 版本升级以监控中断情况，然后再升级生产集群。

准备升级到版本 1.22

您无需删除并重新创建任何 API 对象。所有现有的 API 对象都可以使用新的 API 版本进行读取和更新。不过，在升级到 Kubernetes 1.22 之前，我们建议您先迁移客户端和清单。如需了解详情，请参阅Kubernetes 已弃用的 API 迁移指南的“应对措施|”部分。

您可以查看弃用数据洞见和建议，以确定您的集群是否正在使用已弃用的 Kubernetes 功能或 API。弃用数据洞见基于用户代理对已弃用的 API 的 API 调用，而非 Kubernetes 对象的配置。

更新受弃用影响的集群

如需升级受弃用影响的集群，请执行以下步骤：

在弃用数据洞见或日志中检查哪些用户代理使用已弃用的 API。
更新使用已弃用的 API 的用户代理，以使用受支持的 API 版本。
将调用已弃用的 API 的所有第三方软件更新为最新版本。
升级测试集群并在升级生产集群之前在测试环境中测试应用，以降低弃用 API 不再可用时的中断风险。
更新所有用户代理后，GKE 会等待 30 天，以便不再观察到已弃用 API 的使用，然后取消屏蔽自动升级。自动升级根据发布时间表进行。
如果您无法更新受影响的用户代理，请升级单独的测试集群以检查升级是否会导致中断。如果升级不会导致中断，您可以手动升级集群。

资源

如需了解详情，请参阅 OSS Kubernetes 文档：