已弃用 API 的迁移指南

随着 Kubernetes API 的演化,API 会周期性地被重组或升级。 当 API 演化时,老的 API 会被弃用并被最终删除。 本页面包含你在将已弃用 API 版本迁移到新的更稳定的 API 版本时需要了解的知识。

各发行版本中移除的 API

v1.32

v1.32 发行版本将停止提供以下已弃用的 API 版本:

流控制资源

FlowSchema 和 PriorityLevelConfiguration 的 flowcontrol.apiserver.k8s.io/v1beta3 API 版本将不再在 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 提供。

  • 自 v1.24 版本起,迁移清单和 API 客户端使用 storage.k8s.io/v1 API 版本
  • 所有现有的持久化对象都可以通过新的 API 访问
  • 没有需要额外注意的变更

v1.26

v1.26 发行版本中将去除以下已弃用的 API 版本:

流控制资源

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

  • 迁移清单和 API 客户端使用 flowcontrol.apiserver.k8s.io/v1beta3 API 版本, 此 API 从 v1.26 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;
  • 没有需要额外注意的变更。

HorizontalPodAutoscaler

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

  • 迁移清单和 API 客户端使用 autoscaling/v2 API 版本, 此 API 从 v1.23 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问。

v1.25

v1.25 发行版本将停止提供以下已废弃 API 版本:

CronJob

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

  • 迁移清单和 API 客户端使用 batch/v1 API 版本,此 API 从 v1.21 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;
  • 没有需要额外注意的变更。

EndpointSlice

从 v1.25 版本开始不再提供 discovery.k8s.io/v1beta1 API 版本的 EndpointSlice。

  • 迁移清单和 API 客户端使用 discovery.k8s.io/v1 API 版本,此 API 从 v1.21 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;
  • discovery.k8s.io/v1 中值得注意的变更有:
    • 使用每个 Endpoint 的 nodeName 字段而不是已被弃用的 topology["kubernetes.io/hostname"] 字段;
    • 使用每个 Endpoint 的 zone 字段而不是已被弃用的 topology["kubernetes.io/zone"] 字段;
    • topology 字段被替换为 deprecatedTopology,并且在 v1 版本中不可写入。

Event

从 v1.25 版本开始不再提供 events.k8s.io/v1beta1 API 版本的 Event。

  • 迁移清单和 API 客户端使用 events.k8s.io/v1 API 版本,此 API 从 v1.19 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;

  • events.k8s.io/v1 中值得注意的变更有:

    • type 字段只能设置为 NormalWarning 之一;
    • involvedObject 字段被更名为 regarding
    • actionreasonreportingControllerreportingInstance 字段 在创建新的 events.k8s.io/v1 版本 Event 时都是必需的字段;
    • 使用 eventTime 而不是已被弃用的 firstTimestamp 字段 (该字段已被更名为 deprecatedFirstTimestamp,且不允许出现在新的 events.k8s.io/v1 Event 对象中);
    • 使用 series.lastObservedTime 而不是已被弃用的 lastTimestamp 字段 (该字段已被更名为 deprecatedLastTimestamp,且不允许出现在新的 events.k8s.io/v1 Event 对象中);
    • 使用 series.count 而不是已被弃用的 count 字段 (该字段已被更名为 deprecatedCount,且不允许出现在新的 events.k8s.io/v1 Event 对象中);
    • 使用 reportingController 而不是已被弃用的 source.component 字段 (该字段已被更名为 deprecatedSource.component,且不允许出现在新的 events.k8s.io/v1 Event 对象中);
    • 使用 reportingInstance 而不是已被弃用的 source.host 字段 (该字段已被更名为 deprecatedSource.host,且不允许出现在新的 events.k8s.io/v1 Event 对象中)。

HorizontalPodAutoscaler

从 v1.25 版本开始不再提供 autoscaling/v2beta1 API 版本的 HorizontalPodAutoscaler。

  • 迁移清单和 API 客户端使用 autoscaling/v2 API 版本,此 API 从 v1.23 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问。

PodDisruptionBudget

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

  • 迁移清单和 API 客户端使用 policy/v1 API 版本,此 API 从 v1.21 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;
  • policy/v1 中需要额外注意的变更有:
    • policy/v1 版本的 PodDisruptionBudget 中将 spec.selector 设置为空({})时会选择名字空间中的所有 Pod(在 policy/v1beta1 版本中,空的 spec.selector 不会选择任何 Pod)。如果 spec.selector 未设置,则在两个 API 版本下都不会选择任何 Pod。

PodSecurityPolicy

从 v1.25 版本开始不再提供 policy/v1beta1 API 版本中的 PodSecurityPolicy, 并且 PodSecurityPolicy 准入控制器也会被删除。

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

RuntimeClass

从 v1.25 版本开始不再提供 node.k8s.io/v1beta1 API 版本中的 RuntimeClass。

  • 迁移清单和 API 客户端使用 node.k8s.io/v1 API 版本,此 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 版本, 此 API 从 v1.16 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;

  • 值得注意的变更:

    • webhooks[*].failurePolicy 在 v1 版本中默认值从 Ignore 改为 Fail
    • webhooks[*].matchPolicy 在 v1 版本中默认值从 Exact 改为 Equivalent
    • webhooks[*].timeoutSeconds 在 v1 版本中默认值从 30s 改为 10s
    • webhooks[*].sideEffects 的默认值被删除,并且该字段变为必须指定; 在 v1 版本中可选的值只能是 NoneNoneOnDryRun 之一
    • webhooks[*].admissionReviewVersions 的默认值被删除,在 v1 版本中此字段变为必须指定(AdmissionReview 的被支持版本包括 v1v1beta1
    • webhooks[*].name 必须在通过 admissionregistration.k8s.io/v1 创建的对象列表中唯一

CustomResourceDefinition

apiextensions.k8s.io/v1beta1 API 版本的 CustomResourceDefinition 不在 v1.22 版本中继续提供。

  • 迁移清单和 API 客户端使用 apiextensions.k8s.io/v1 API 版本,此 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

    • spec.versions[*].schema.openAPIV3Schema 在创建 v1 版本的 CustomResourceDefinition 对象时变成必需字段,并且其取值必须是一个 结构化的 Schema
    • spec.preserveUnknownFields: true 在创建 v1 版本的 CustomResourceDefinition 对象时不允许指定;该配置必须在 Schema 定义中使用 x-kubernetes-preserve-unknown-fields: true 来设置
    • 在 v1 版本中,additionalPrinterColumns 的条目中的 JSONPath 字段被更名为 jsonPath(补丁 #66531

APIService

apiregistration/v1beta1 API 版本的 APIService 不在 v1.22 版本中继续提供。

  • 迁移清单和 API 客户端使用 apiregistration.k8s.io/v1 API 版本,此 API 从 v1.10 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;
  • 没有需要额外注意的变更。

TokenReview

authentication.k8s.io/v1beta1 API 版本的 TokenReview 不在 v1.22 版本中继续提供。

  • 迁移清单和 API 客户端使用 authentication.k8s.io/v1 API 版本,此 API 从 v1.6 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;
  • 没有需要额外注意的变更。

SubjectAccessReview resources

authorization.k8s.io/v1beta1 API 版本的 LocalSubjectAccessReview、 SelfSubjectAccessReview、SubjectAccessReview、SelfSubjectRulesReview 不在 v1.22 版本中继续提供。

  • 迁移清单和 API 客户端使用 authorization.k8s.io/v1 API 版本,此 API 从 v1.6 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;
  • 需要额外注意的变更:
    • spec.group 在 v1 版本中被更名为 spec.groups (补丁 #32709

CertificateSigningRequest

certificates.k8s.io/v1beta1 API 版本的 CertificateSigningRequest 不在 v1.22 版本中继续提供。

  • 迁移清单和 API 客户端使用 certificates.k8s.io/v1 API 版本,此 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

coordination.k8s.io/v1beta1 API 版本的 Lease 不在 v1.22 版本中继续提供。

  • 迁移清单和 API 客户端使用 coordination.k8s.io/v1 API 版本,此 API 从 v1.14 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;
  • 没有需要额外注意的变更。

Ingress

extensions/v1beta1networking.k8s.io/v1beta1 API 版本的 Ingress 不在 v1.22 版本中继续提供。

  • 迁移清单和 API 客户端使用 networking.k8s.io/v1 API 版本,此 API 从 v1.19 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;

  • 值得注意的变更:

    • spec.backend 字段被更名为 spec.defaultBackend
    • 后端的 serviceName 字段被更名为 service.name
    • 数值表示的后端 servicePort 字段被更名为 service.port.number
    • 字符串表示的后端 servicePort 字段被更名为 service.port.name
    • 对所有要指定的路径,pathType 都成为必需字段。 可选项为 PrefixExactImplementationSpecific。 要匹配 v1beta1 版本中未定义路径类型时的行为,可使用 ImplementationSpecific

IngressClass

networking.k8s.io/v1beta1 API 版本的 IngressClass 不在 v1.22 版本中继续提供。

  • 迁移清单和 API 客户端使用 networking.k8s.io/v1 API 版本,此 API 从 v1.19 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;
  • 没有需要额外注意的变更。

RBAC 资源

rbac.authorization.k8s.io/v1beta1 API 版本的 ClusterRole、ClusterRoleBinding、 Role 和 RoleBinding 不在 v1.22 版本中继续提供。

  • 迁移清单和 API 客户端使用 rbac.authorization.k8s.io/v1 API 版本,此 API 从 v1.8 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;
  • 没有需要额外注意的变更。

PriorityClass

scheduling.k8s.io/v1beta1 API 版本的 PriorityClass 不在 v1.22 版本中继续提供。

  • 迁移清单和 API 客户端使用 scheduling.k8s.io/v1 API 版本,此 API 从 v1.14 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;
  • 没有需要额外注意的变更。

存储资源

storage.k8s.io/v1beta1 API 版本的 CSIDriver、CSINode、StorageClass 和 VolumeAttachment 不在 v1.22 版本中继续提供。

  • 迁移清单和 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

extensions/v1beta1 API 版本的 NetworkPolicy 不在 v1.16 版本中继续提供。

  • 迁移清单和 API 客户端使用 networking.k8s.io/v1 API 版本,此 API 从 v1.8 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问。

DaemonSet

extensions/v1beta1apps/v1beta2 API 版本的 DaemonSet 在 v1.16 版本中不再继续提供。

  • 迁移清单和 API 客户端使用 apps/v1 API 版本,此 API 从 v1.9 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;

  • 值得注意的变更:

    • spec.templateGeneration 字段被删除
    • spec.selector 现在变成必需字段,并且在对象创建之后不可变更; 可以将现有模板的标签作为选择算符以实现无缝迁移。
    • spec.updateStrategy.type 的默认值变为 RollingUpdateextensions/v1beta1 API 版本中的默认值是 OnDelete)。

Deployment

extensions/v1beta1apps/v1beta1apps/v1beta2 API 版本的 Deployment 在 v1.16 版本中不再继续提供。

  • 迁移清单和 API 客户端使用 apps/v1 API 版本,此 API 从 v1.9 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;

  • 值得注意的变更:

    • spec.rollbackTo 字段被删除
    • spec.selector 字段现在变为必需字段,并且在 Deployment 创建之后不可变更; 可以使用现有的模板的标签作为选择算符以实现无缝迁移。
    • spec.progressDeadlineSeconds 的默认值变为 600 秒 (extensions/v1beta1 中的默认值是没有期限)
    • spec.revisionHistoryLimit 的默认值变为 10apps/v1beta1 API 版本中此字段默认值为 2,在extensions/v1beta1 API 版本中的默认行为是保留所有历史记录)。
    • maxSurgemaxUnavailable 的默认值变为 25% (在 extensions/v1beta1 API 版本中,这些字段的默认值是 1)。

StatefulSet

apps/v1beta1apps/v1beta2 API 版本的 StatefulSet 在 v1.16 版本中不再继续提供。

  • 迁移清单和 API 客户端使用 apps/v1 API 版本,此 API 从 v1.9 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;

  • 值得注意的变更:

    • spec.selector 字段现在变为必需字段,并且在 StatefulSet 创建之后不可变更; 可以使用现有的模板的标签作为选择算符以实现无缝迁移。
    • spec.updateStrategy.type 的默认值变为 RollingUpdateapps/v1beta1 API 版本中的默认值是 OnDelete)。

ReplicaSet

extensions/v1beta1apps/v1beta1apps/v1beta2 API 版本的 ReplicaSet 在 v1.16 版本中不再继续提供。

  • 迁移清单和 API 客户端使用 apps/v1 API 版本,此 API 从 v1.9 版本开始可用;
  • 所有的已保存的对象都可以通过新的 API 来访问;

  • 值得注意的变更:

    • spec.selector 现在变成必需字段,并且在对象创建之后不可变更; 可以将现有模板的标签作为选择算符以实现无缝迁移。

PodSecurityPolicy

extensions/v1beta1 API 版本的 PodSecurityPolicy 在 v1.16 版本中不再继续提供。

  • 迁移清单和 API 客户端使用 policy/v1beta1 API 版本,此 API 从 v1.10 版本开始可用;
  • 注意 policy/v1beta1 API 版本的 PodSecurityPolicy 会在 v1.25 版本中移除。

需要做什么

在禁用已启用 API 的情况下执行测试

你可以通过在启动 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 命令自动转换现有对象:

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

    例如,要将较老的 Deployment 版本转换为 apps/v1 版本,你可以运行:

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

    这个转换可能使用了非理想的默认值。要了解更多关于特定资源的信息, 请查阅 Kubernetes API 参考文档

    说明:

    尽管实际上 kubectl convert 工具曾经是 kubectl 自身的一部分,但此工具不是默认安装的。 如果想了解更多详情,可以阅读内置子命令的弃用和移除问题

    要了解如何在你的计算机上设置 kubectl convert,查阅适合你操作系统的页面: LinuxmacOSWindows