你正在查看的文档所针对的是 Kubernetes 版本: v1.27
Kubernetes v1.27 版本的文档已不再维护。你现在看到的版本来自于一份静态的快照。如需查阅最新文档,请点击 最新版本。
已弃用 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/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 参考文档。