Information in this document may be out of date
This document has an older update date than the original, so the information it contains may be out of date. If you're able to read English, see the English version for the most up-to-date information: Deprecated API Migration Guide
已弃用 API 的迁移指南
随着 Kubernetes API 的演化,API 会周期性地被重组或升级。 当 API 演化时,老的 API 会被弃用并被最终删除。 本页面包含你在将已弃用 API 版本迁移到新的更稳定的 API 版本时需要了解的知识。
各发行版本中移除的 API
v1.29
v1.29 发行版本将停止提供以下已弃用的 API 版本:
流控制资源
flowcontrol.apiserver.k8s.io/v1beta2 API 版本的 FlowSchema 和 PriorityLevelConfiguration 将不会在 v1.29 中提供。
- 迁移清单和 API 客户端使用 flowcontrol.apiserver.k8s.io/v1beta3 API 版本, 此 API 从 v1.26 版本开始可用;
- 所有的已保存的对象都可以通过新的 API 来访问;
- flowcontrol.apiserver.k8s.io/v1beta3 中需要额外注意的变更:
- PriorityLevelConfiguration 的
spec.limited.assuredConcurrencyShares
字段已被更名为spec.limited.nominalConcurrencyShares
- PriorityLevelConfiguration 的
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 版本中不可写入。
- 使用每个 Endpoint 的
Event
从 v1.25 版本开始不再提供 events.k8s.io/v1beta1 API 版本的 Event。
- 迁移清单和 API 客户端使用 events.k8s.io/v1 API 版本,此 API 从 v1.19 版本开始可用;
- 所有的已保存的对象都可以通过新的 API 来访问;
- events.k8s.io/v1 中值得注意的变更有:
type
字段只能设置为Normal
和Warning
之一;involvedObject
字段被更名为regarding
;action
、reason
、reportingController
和reportingInstance
字段 在创建新的 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 版本中可选的值只能是None
和NoneOnDryRun
之一webhooks[*].admissionReviewVersions
的默认值被删除,在 v1 版本中此字段变为必须指定(AdmissionReview 的被支持版本包括v1
和v1beta1
)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 对象时变成必需字段,并且其取值必须是一个 结构化的 Schemaspec.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
数据块
- 对于请求证书的 API 客户端而言:
Lease
coordination.k8s.io/v1beta1 API 版本的 Lease 不在 v1.22 版本中继续提供。
- 迁移清单和 API 客户端使用 coordination.k8s.io/v1 API 版本,此 API 从 v1.14 版本开始可用;
- 所有的已保存的对象都可以通过新的 API 来访问;
- 没有需要额外注意的变更。
Ingress
extensions/v1beta1 和 networking.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
都成为必需字段。 可选项为Prefix
、Exact
和ImplementationSpecific
。 要匹配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/v1beta1 和 apps/v1beta2 API 版本的 DaemonSet 在 v1.16 版本中不再继续提供。
- 迁移清单和 API 客户端使用 apps/v1 API 版本,此 API 从 v1.9 版本开始可用;
- 所有的已保存的对象都可以通过新的 API 来访问;
- 值得注意的变更:
spec.templateGeneration
字段被删除spec.selector
现在变成必需字段,并且在对象创建之后不可变更; 可以将现有模板的标签作为选择算符以实现无缝迁移。spec.updateStrategy.type
的默认值变为RollingUpdate
(extensions/v1beta1
API 版本中的默认值是OnDelete
)。
Deployment
extensions/v1beta1、apps/v1beta1 和 apps/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
的默认值变为10
(apps/v1beta1
API 版本中此字段默认值为2
,在extensions/v1beta1
API 版本中的默认行为是保留所有历史记录)。maxSurge
和maxUnavailable
的默认值变为25%
(在extensions/v1beta1
API 版本中,这些字段的默认值是1
)。
StatefulSet
apps/v1beta1 和 apps/v1beta2 API 版本的 StatefulSet 在 v1.16 版本中不再继续提供。
- 迁移清单和 API 客户端使用 apps/v1 API 版本,此 API 从 v1.9 版本开始可用;
- 所有的已保存的对象都可以通过新的 API 来访问;
- 值得注意的变更:
spec.selector
字段现在变为必需字段,并且在 StatefulSet 创建之后不可变更; 可以使用现有的模板的标签作为选择算符以实现无缝迁移。spec.updateStrategy.type
的默认值变为RollingUpdate
(apps/v1beta1
API 版本中的默认值是OnDelete
)。
ReplicaSet
extensions/v1beta1、apps/v1beta1 和 apps/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
命令自动转换现有对象:kubectl convert -f <file> --output-version <group>/<version>
例如,要将较老的 Deployment 版本转换为
apps/v1
版本,你可以运行:kubectl convert -f ./my-deployment.yaml --output-version apps/v1
这个转换可能使用了非理想的默认值。要了解更多关于特定资源的信息, 请查阅 Kubernetes API 参考文档。