弃用 API 迁移指南

随着 Kubernetes API 的发展，API 会定期重新组织或升级。当 API 发展时，旧的 API 会被弃用，并最终被移除。此页面包含您在从弃用的 API 版本迁移到更新、更稳定的 API 版本时需要了解的信息。

按版本移除的 API

v1.32

v1.32 版本将停止提供以下弃用的 API 版本的服务

流量控制资源

flowcontrol.apiserver.k8s.io/v1beta3 版本的 FlowSchema 和 PriorityLevelConfiguration 将不再在 v1.32 中提供服务。

  • 迁移清单和 API 客户端以使用 flowcontrol.apiserver.k8s.io/v1 API 版本，该版本自 v1.29 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • flowcontrol.apiserver.k8s.io/v1 中的显著变化
    • PriorityLevelConfiguration spec.limited.nominalConcurrencyShares 字段仅在未指定时默认值为 30，显式值为 0 不会更改为 30。

v1.29

v1.29 版本停止提供以下弃用的 API 版本的服务

流量控制资源

flowcontrol.apiserver.k8s.io/v1beta2 版本的 FlowSchema 和 PriorityLevelConfiguration 自 v1.29 起不再提供服务。

  • 迁移清单和 API 客户端以使用 flowcontrol.apiserver.k8s.io/v1 API 版本（自 v1.29 起可用）或 flowcontrol.apiserver.k8s.io/v1beta3 API 版本（自 v1.26 起可用）。
  • 所有现有的持久化对象都可以通过新 API 访问
  • flowcontrol.apiserver.k8s.io/v1 中的显著变化
    • PriorityLevelConfiguration spec.limited.assuredConcurrencyShares 字段已重命名为 spec.limited.nominalConcurrencyShares，并且仅在未指定时默认值为 30，显式值为 0 不会更改为 30。
  • flowcontrol.apiserver.k8s.io/v1beta3 中的显著变化
    • PriorityLevelConfiguration spec.limited.assuredConcurrencyShares 字段已重命名为 spec.limited.nominalConcurrencyShares

v1.27

v1.27 版本停止提供以下弃用的 API 版本的服务

CSIStorageCapacity

storage.k8s.io/v1beta1 版本的 CSIStorageCapacity 自 v1.27 起不再提供服务。

  • 迁移清单和 API 客户端以使用 storage.k8s.io/v1 API 版本，该版本自 v1.24 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 无显著变化

v1.26

v1.26 版本停止提供以下弃用的 API 版本的服务

流量控制资源

flowcontrol.apiserver.k8s.io/v1beta1 版本的 FlowSchema 和 PriorityLevelConfiguration 自 v1.26 起不再提供服务。

  • 迁移清单和 API 客户端以使用 flowcontrol.apiserver.k8s.io/v1beta2 API 版本。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 无显著变化

HorizontalPodAutoscaler

autoscaling/v2beta2 版本的 HorizontalPodAutoscaler 自 v1.26 起不再提供服务。

  • 迁移清单和 API 客户端以使用 autoscaling/v2 API 版本，该版本自 v1.23 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 显著变化

v1.25

v1.25 版本停止提供以下弃用的 API 版本的服务

CronJob

batch/v1beta1 版本的 CronJob 自 v1.25 起不再提供服务。

  • 迁移清单和 API 客户端以使用 batch/v1 API 版本，该版本自 v1.21 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 无显著变化

EndpointSlice

discovery.k8s.io/v1beta1 版本的 EndpointSlice 自 v1.25 起不再提供服务。

  • 迁移清单和 API 客户端以使用 discovery.k8s.io/v1 API 版本，该版本自 v1.21 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • discovery.k8s.io/v1 中的显著变化
    • 使用每个 Endpoint 的 nodeName 字段，而不是弃用的 topology["kubernetes.io/hostname"] 字段
    • 使用每个 Endpoint 的 zone 字段，而不是弃用的 topology["topology.kubernetes.io/zone"] 字段
    • topology 已替换为 deprecatedTopology 字段，该字段在 v1 中不可写

Event

events.k8s.io/v1beta1 版本的 Event 自 v1.25 起不再提供服务。

  • 迁移清单和 API 客户端以使用 events.k8s.io/v1 API 版本，该版本自 v1.19 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • events.k8s.io/v1 中的显著变化
    • type 限制为 Normal 和 Warning
    • involvedObject 已重命名为 regarding
    • 在创建新的 events.k8s.io/v1 事件时，action、reason、reportingController 和 reportingInstance 是必需的
    • 使用 eventTime，而不是弃用的 firstTimestamp 字段（已重命名为 deprecatedFirstTimestamp，并且不允许在新的 events.k8s.io/v1 事件中使用）
    • 使用 series.lastObservedTime，而不是弃用的 lastTimestamp 字段（已重命名为 deprecatedLastTimestamp，并且不允许在新的 events.k8s.io/v1 事件中使用）
    • 使用 series.count，而不是弃用的 count 字段（已重命名为 deprecatedCount，并且不允许在新的 events.k8s.io/v1 事件中使用）
    • 使用 reportingController，而不是弃用的 source.component 字段（已重命名为 deprecatedSource.component，并且不允许在新的 events.k8s.io/v1 事件中使用）
    • 使用 reportingInstance，而不是弃用的 source.host 字段（已重命名为 deprecatedSource.host，并且不允许在新的 events.k8s.io/v1 事件中使用）

HorizontalPodAutoscaler

autoscaling/v2beta1 版本的 HorizontalPodAutoscaler 自 v1.25 起不再提供服务。

  • 迁移清单和 API 客户端以使用 autoscaling/v2 API 版本，该版本自 v1.23 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 显著变化

PodDisruptionBudget

policy/v1beta1 版本的 PodDisruptionBudget 自 v1.25 起不再提供服务。

  • 迁移清单和 API 客户端以使用 policy/v1 API 版本，该版本自 v1.21 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • policy/v1 中的显著变化
    • 在 policy/v1 PodDisruptionBudget 中写入的空 spec.selector（{}）会选择命名空间中的所有 Pod（在 policy/v1beta1 中，空 spec.selector 不会选择任何 Pod）。在任一 API 版本中，未设置的 spec.selector 不会选择任何 Pod。

PodSecurityPolicy

policy/v1beta1 API 版本中的 PodSecurityPolicy 自 v1.25 起不再提供服务，并且 PodSecurityPolicy 准入控制器将被移除。

迁移到 Pod 安全准入 或 第三方准入 Webhook。有关迁移指南，请参阅 从 PodSecurityPolicy 迁移到内置 Pod 安全准入控制器。有关弃用更多信息，请参阅 PodSecurityPolicy 弃用：过去、现在和未来。

RuntimeClass

node.k8s.io/v1beta1 API 版本中的 RuntimeClass 自 v1.25 起不再提供服务。

  • 迁移清单和 API 客户端以使用 node.k8s.io/v1 API 版本，该版本自 v1.20 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 无显著变化

v1.22

v1.22 版本停止提供以下弃用的 API 版本的服务

Webhook 资源

admissionregistration.k8s.io/v1beta1 版本的 MutatingWebhookConfiguration 和 ValidatingWebhookConfiguration 自 v1.22 起不再提供服务。

  • 迁移清单和 API 客户端以使用 admissionregistration.k8s.io/v1 API 版本，该版本自 v1.16 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 显著变化
    • webhooks[*].failurePolicy 默认值已从 Ignore 更改为 Fail（适用于 v1）
    • webhooks[*].matchPolicy 默认值已从 Exact 更改为 Equivalent（适用于 v1）
    • webhooks[*].timeoutSeconds 默认值已从 30s 更改为 10s（适用于 v1）
    • webhooks[*].sideEffects 默认值已移除，该字段已变为必需，并且仅允许 None 和 NoneOnDryRun（适用于 v1）
    • webhooks[*].admissionReviewVersions 默认值已移除，该字段已变为必需（适用于 v1）（AdmissionReview 支持的版本为 v1 和 v1beta1）
    • 通过 admissionregistration.k8s.io/v1 创建的对象，webhooks[*].name 在列表中必须是唯一的

CustomResourceDefinition

apiextensions.k8s.io/v1beta1 版本的 CustomResourceDefinition 自 v1.22 起不再提供服务。

  • 迁移清单和 API 客户端以使用 apiextensions.k8s.io/v1 API 版本，该版本自 v1.16 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 显著变化
    • spec.scope 不再默认设置为 Namespaced，必须显式指定
    • spec.version 在 v1 中已移除；请使用 spec.versions 代替。
    • spec.validation 在 v1 中已移除；请使用 spec.versions[*].schema 代替。
    • spec.subresources 在 v1 中已移除；请使用 spec.versions[*].subresources 代替。
    • spec.additionalPrinterColumns 在 v1 中已移除；请使用 spec.versions[*].additionalPrinterColumns 代替。
    • spec.conversion.webhookClientConfig 在 v1 中已移至 spec.conversion.webhook.clientConfig。
    • spec.conversion.conversionReviewVersions 在 v1 中已移至 spec.conversion.webhook.conversionReviewVersions。
    • 在创建 v1 CustomResourceDefinition 对象时，spec.versions[*].schema.openAPIV3Schema 现在是必需的，并且必须是 结构化模式。
    • 在创建 v1 CustomResourceDefinition 对象时，spec.preserveUnknownFields: true 不允许；它必须在模式定义中指定为 x-kubernetes-preserve-unknown-fields: true。
    • 在 additionalPrinterColumns 项目中，JSONPath 字段在 v1 中已重命名为 jsonPath（修复了 #66531）。

APIService

从 v1.22 开始，不再提供 apiregistration.k8s.io/v1beta1 API 版本的 APIService。

  • 迁移清单和 API 客户端以使用 apiregistration.k8s.io/v1 API 版本，该版本自 v1.10 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 无显著变化

TokenReview

从 v1.22 开始，不再提供 authentication.k8s.io/v1beta1 API 版本的 TokenReview。

  • 迁移清单和 API 客户端以使用 authentication.k8s.io/v1 API 版本，该版本自 v1.6 起可用。
  • 无显著变化

SubjectAccessReview 资源

从 v1.22 开始，不再提供 authorization.k8s.io/v1beta1 API 版本的 LocalSubjectAccessReview、SelfSubjectAccessReview、SubjectAccessReview 和 SelfSubjectRulesReview。

  • 迁移清单和 API 客户端以使用 authorization.k8s.io/v1 API 版本，该版本自 v1.6 起可用。
  • 显著变化
    • spec.group 在 v1 中已重命名为 spec.groups（修复了 #32709）。

CertificateSigningRequest

从 v1.22 开始，不再提供 certificates.k8s.io/v1beta1 API 版本的 CertificateSigningRequest。

  • 迁移清单和 API 客户端以使用 certificates.k8s.io/v1 API 版本，该版本自 v1.19 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • certificates.k8s.io/v1 中的显著变化
    • 对于请求证书的 API 客户端
      • spec.signerName 现在是必需的（参见 已知的 Kubernetes 签名者），并且不允许通过 certificates.k8s.io/v1 API 创建对 kubernetes.io/legacy-unknown 的请求。
      • spec.usages 现在是必需的，不能包含重复的值，并且必须只包含已知的用途。
    • 对于批准或签署证书的 API 客户端
      • status.conditions 不能包含重复的类型。
      • status.conditions[*].status 现在是必需的。
      • status.certificate 必须是 PEM 编码的，并且只包含 CERTIFICATE 块。

Lease

从 v1.22 开始，不再提供 coordination.k8s.io/v1beta1 API 版本的 Lease。

  • 迁移清单和 API 客户端以使用 coordination.k8s.io/v1 API 版本，该版本自 v1.14 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 无显著变化

入口

从 v1.22 开始，不再提供 extensions/v1beta1 和 networking.k8s.io/v1beta1 API 版本的 Ingress。

  • 迁移清单和 API 客户端以使用 networking.k8s.io/v1 API 版本，该版本自 v1.19 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 显著变化
    • spec.backend 已重命名为 spec.defaultBackend。
    • 后端 serviceName 字段已重命名为 service.name。
    • 数字后端 servicePort 字段已重命名为 service.port.number。
    • 字符串后端 servicePort 字段已重命名为 service.port.name。
    • 每个指定的路径现在都需要 pathType。选项包括 Prefix、Exact 和 ImplementationSpecific。要匹配未定义的 v1beta1 行为，请使用 ImplementationSpecific。

IngressClass

从 v1.22 开始，不再提供 networking.k8s.io/v1beta1 API 版本的 IngressClass。

  • 迁移清单和 API 客户端以使用 networking.k8s.io/v1 API 版本，该版本自 v1.19 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 无显著变化

RBAC 资源

从 v1.22 开始，不再提供 rbac.authorization.k8s.io/v1beta1 API 版本的 ClusterRole、ClusterRoleBinding、Role 和 RoleBinding。

  • 迁移清单和 API 客户端以使用 rbac.authorization.k8s.io/v1 API 版本，该版本自 v1.8 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 无显著变化

PriorityClass

从 v1.22 开始，不再提供 scheduling.k8s.io/v1beta1 API 版本的 PriorityClass。

  • 迁移清单和 API 客户端以使用 scheduling.k8s.io/v1 API 版本，该版本自 v1.14 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 无显著变化

存储资源

从 v1.22 开始，不再提供 storage.k8s.io/v1beta1 API 版本的 CSIDriver、CSINode、StorageClass 和 VolumeAttachment。

  • 迁移清单和 API 客户端以使用 storage.k8s.io/v1 API 版本。
    • CSIDriver 自 v1.19 起在 storage.k8s.io/v1 中可用。
    • CSINode 自 v1.17 起在 storage.k8s.io/v1 中可用。
    • StorageClass 自 v1.6 起在 storage.k8s.io/v1 中可用。
    • VolumeAttachment 自 v1.13 起在 storage.k8s.io/v1 中可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 无显著变化

v1.16

v1.16 版本停止提供以下已弃用的 API 版本。

NetworkPolicy

从 v1.16 开始，不再提供 extensions/v1beta1 API 版本的 NetworkPolicy。

  • 迁移清单和 API 客户端以使用 networking.k8s.io/v1 API 版本，该版本自 v1.8 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问

守护进程集

从 v1.16 开始，不再提供 extensions/v1beta1 和 apps/v1beta2 API 版本的 DaemonSet。

  • 迁移清单和 API 客户端以使用 apps/v1 API 版本，该版本自 v1.9 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 显著变化
    • spec.templateGeneration 已移除。
    • spec.selector 现在是必需的，并且在创建后不可变；使用现有的模板标签作为选择器以实现无缝升级。
    • spec.updateStrategy.type 现在默认为 RollingUpdate（extensions/v1beta1 中的默认值为 OnDelete）。

Deployment

从 v1.16 开始，不再提供 extensions/v1beta1、apps/v1beta1 和 apps/v1beta2 API 版本的 Deployment。

  • 迁移清单和 API 客户端以使用 apps/v1 API 版本，该版本自 v1.9 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 显著变化
    • spec.rollbackTo 已移除。
    • spec.selector 现在是必需的，并且在创建后不可变；使用现有的模板标签作为选择器以实现无缝升级。
    • spec.progressDeadlineSeconds 现在默认为 600 秒（extensions/v1beta1 中的默认值为无截止日期）。
    • spec.revisionHistoryLimit 现在默认为 10（apps/v1beta1 中的默认值为 2，extensions/v1beta1 中的默认值为保留所有）。
    • maxSurge 和 maxUnavailable 现在默认为 25%（extensions/v1beta1 中的默认值为 1）。

StatefulSet

从 v1.16 开始，不再提供 apps/v1beta1 和 apps/v1beta2 API 版本的 StatefulSet。

  • 迁移清单和 API 客户端以使用 apps/v1 API 版本，该版本自 v1.9 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 显著变化
    • spec.selector 现在是必需的，并且在创建后不可变；使用现有的模板标签作为选择器以实现无缝升级。
    • spec.updateStrategy.type 现在默认为 RollingUpdate（apps/v1beta1 中的默认值为 OnDelete）。

副本集

从 v1.16 开始，不再提供 extensions/v1beta1、apps/v1beta1 和 apps/v1beta2 API 版本的 ReplicaSet。

  • 迁移清单和 API 客户端以使用 apps/v1 API 版本，该版本自 v1.9 起可用。
  • 所有现有的持久化对象都可以通过新 API 访问
  • 显著变化
    • spec.selector 现在是必需的，并且在创建后不可变；使用现有的模板标签作为选择器以实现无缝升级。

PodSecurityPolicy

从 v1.16 开始，不再提供 extensions/v1beta1 API 版本的 PodSecurityPolicy。

  • 迁移清单和 API 客户端以使用 policy/v1beta1 API 版本，该版本自 v1.10 起可用。
  • 请注意，policy/v1beta1 API 版本的 PodSecurityPolicy 将在 v1.25 中移除。

操作步骤

测试禁用已弃用的 API

您可以通过启动禁用特定 API 版本的 API 服务器来测试您的集群，以模拟即将到来的移除。将以下标志添加到 API 服务器启动参数中

--runtime-config=<group>/<version>=false

例如

--runtime-config=admissionregistration.k8s.io/v1beta1=false,apiextensions.k8s.io/v1beta1,...

定位已弃用 API 的使用情况

使用 1.19+ 中提供的客户端警告、指标和审计信息 来定位已弃用 API 的使用情况。

迁移到非已弃用的 API

  • 更新自定义集成和控制器以调用非已弃用的 API。

  • 更改 YAML 文件以引用非已弃用的 API。

    您可以使用 kubectl convert 命令自动转换现有对象。

    kubectl convert -f <file> --output-version <group>/<version>.

    例如，要将旧的 Deployment 转换为 apps/v1，您可以运行以下命令

    kubectl convert -f ./my-deployment.yaml --output-version apps/v1

    此转换可能会使用非理想的默认值。要了解有关特定资源的更多信息，请查看 Kubernetes API 参考。

上次修改时间：2024 年 3 月 17 日凌晨 12:37 PST：更新 v1.25 和 v1.26 的 HorizontalPodAutoscaler 已弃用 API 迁移指南 (#45390) (f424d45142)