弃用 API 迁移指南

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

按版本移除的 API

v1.32

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

流量控制资源

**flowcontrol.apiserver.k8s.io/v1beta3** API 版本的 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** API 版本的 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** API 版本的 CSIStorageCapacity 从 v1.27 开始不再提供。

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

v1.26

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

流量控制资源

**flowcontrol.apiserver.k8s.io/v1beta1** API 版本的 FlowSchema 和 PriorityLevelConfiguration 从 v1.26 开始不再提供。

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

HorizontalPodAutoscaler

**autoscaling/v2beta2** API 版本的 HorizontalPodAutoscaler 从 v1.26 开始不再提供。

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

v1.25

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

CronJob

**batch/v1beta1** API 版本的 CronJob 从 v1.25 开始不再提供。

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

EndpointSlice

**discovery.k8s.io/v1beta1** API 版本的 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 中不可写

事件

**events.k8s.io/v1beta1** API 版本的 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** API 版本的 HorizontalPodAutoscaler 从 v1.25 开始不再提供。

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

PodDisruptionBudget

**policy/v1beta1** API 版本的 PodDisruptionBudget 从 v1.25 开始不再提供。

  • 迁移清单和 API 客户端以使用**policy/v1** API 版本，该版本从 v1.21 开始可用。
  • 所有现有的持久化对象都可以通过新的 API 访问
  • **policy/v1** 中的显著变化
    • 空spec.selector（{}）写入policy/v1 PodDisruptionBudget 将选择命名空间中的所有 Pod（在policy/v1beta1 中，空spec.selector 选择了没有 Pod）。未设置的spec.selector 在两个 API 版本中都选择没有 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** API 版本的 MutatingWebhookConfiguration 和 ValidatingWebhookConfiguration 从 v1.22 开始不再提供。

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

CustomResourceDefinition

**apiextensions.k8s.io/v1beta1** API 版本的 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

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

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

TokenReview

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

  • 迁移清单和 API 客户端以使用**authentication.k8s.io/v1** API 版本，该版本从 v1.6 开始可用。
  • 没有显著变化

SubjectAccessReview 资源

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

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

CertificateSigningRequest

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

  • 将清单和 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 块

租约

自 v1.22 起，不再提供**coordination.k8s.io/v1beta1** API 版本的 Lease。

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

Ingress

自 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** v1.13 中可用
  • 所有现有的持久化对象都可以通过新的 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）

部署

自 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 起可用。
  • 请注意，v1.25 中将删除**policy/v1beta1** API 版本的 PodSecurityPolicy。

操作方法

测试禁用弃用 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

    此转换可能使用非理想的默认值。要详细了解特定资源，请查看 KubernetesAPI 参考。

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