弃用 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。
- PriorityLevelConfiguration 的
v1.29
v1.29 版本停止提供以下废弃的 API 版本
流控制资源
FlowSchema 和 PriorityLevelConfiguration 的 flowcontrol.apiserver.k8s.io/v1beta2 API 版本自 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。
- PriorityLevelConfiguration 的
- flowcontrol.apiserver.k8s.io/v1beta3 中的显著变化
- PriorityLevelConfiguration 的
spec.limited.assuredConcurrencyShares
字段已重命名为spec.limited.nominalConcurrencyShares
- PriorityLevelConfiguration 的
v1.27
v1.27 版本停止提供以下废弃的 API 版本
CSIStorageCapacity
CSIStorageCapacity 的 storage.k8s.io/v1beta1 API 版本自 v1.27 起不再提供。
- 将清单和 API 客户端迁移到使用 storage.k8s.io/v1 API 版本,该版本自 v1.24 起可用。
- 所有现有持久化对象都可以通过新的 API 访问
- 无显著变化
v1.26
v1.26 版本停止提供以下废弃的 API 版本
流控制资源
FlowSchema 和 PriorityLevelConfiguration 的 flowcontrol.apiserver.k8s.io/v1beta1 API 版本自 v1.26 起不再提供。
- 将清单和 API 客户端迁移到使用 flowcontrol.apiserver.k8s.io/v1beta2 API 版本。
- 所有现有持久化对象都可以通过新的 API 访问
- 无显著变化
HorizontalPodAutoscaler
HorizontalPodAutoscaler 的 autoscaling/v2beta2 API 版本自 v1.26 起不再提供。
- 将清单和 API 客户端迁移到使用 autoscaling/v2 API 版本,该版本自 v1.23 起可用。
- 所有现有持久化对象都可以通过新的 API 访问
- 显著变化
targetAverageUtilization
被替换为target.averageUtilization
和target.type: Utilization
。请参阅基于多个指标和自定义指标进行自动扩缩。
v1.25
v1.25 版本停止提供以下废弃的 API 版本
定时作业
CronJob 的 batch/v1beta1 API 版本自 v1.25 起不再提供。
- 将清单和 API 客户端迁移到使用 batch/v1 API 版本,该版本自 v1.21 起可用。
- 所有现有持久化对象都可以通过新的 API 访问
- 无显著变化
EndpointSlice
EndpointSlice 的 discovery.k8s.io/v1beta1 API 版本自 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 中不可写入
- 使用每个 Endpoint 的
Event
Event 的 events.k8s.io/v1beta1 API 版本自 v1.25 起不再提供。
- 将清单和 API 客户端迁移到使用 events.k8s.io/v1 API 版本,该版本自 v1.19 起可用。
- 所有现有持久化对象都可以通过新的 API 访问
- events.k8s.io/v1 中的显著变化
type
仅限于Normal
和Warning
involvedObject
重命名为regarding
- 创建新的 events.k8s.io/v1 Event 时,
action
、reason
、reportingController
和reportingInstance
是必需的 - 使用
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
HorizontalPodAutoscaler 的 autoscaling/v2beta1 API 版本自 v1.25 起不再提供。
- 将清单和 API 客户端迁移到使用 autoscaling/v2 API 版本,该版本自 v1.23 起可用。
- 所有现有持久化对象都可以通过新的 API 访问
- 显著变化
targetAverageUtilization
被替换为target.averageUtilization
和target.type: Utilization
。请参阅基于多个指标和自定义指标进行自动扩缩。
PodDisruptionBudget
PodDisruptionBudget 的 policy/v1beta1 API 版本自 v1.25 起不再提供。
- 将清单和 API 客户端迁移到使用 policy/v1 API 版本,该版本自 v1.21 起可用。
- 所有现有持久化对象都可以通过新的 API 访问
- policy/v1 中的显著变化
- 写入到
policy/v1
PodDisruptionBudget 的空spec.selector
({}
) 将选择命名空间中的所有 Pod(在policy/v1beta1
中,空的spec.selector
不选择任何 Pod)。未设置的spec.selector
在两个 API 版本中均不选择任何 Pod。
- 写入到
PodSecurityPolicy
policy/v1beta1 API 版本的 PodSecurityPolicy 自 v1.25 起不再提供,并且 PodSecurityPolicy 准入控制器将被移除。
迁移到 Pod 安全性准入或第三方准入 webhook。有关迁移指南,请参阅从 PodSecurityPolicy 迁移到内置 PodSecurity 准入控制器。有关废弃的更多信息,请参阅PodSecurityPolicy 废弃:过去、现在和未来。
RuntimeClass
RuntimeClass 的 node.k8s.io/v1beta1 API 版本自 v1.25 起不再提供。
- 将清单和 API 客户端迁移到使用 node.k8s.io/v1 API 版本,该版本自 v1.20 起可用。
- 所有现有持久化对象都可以通过新的 API 访问
- 无显著变化
v1.22
v1.22 版本停止提供以下废弃的 API 版本
Webhook 资源
MutatingWebhookConfiguration 和 ValidatingWebhookConfiguration 的 admissionregistration.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。
- 将清单和 API 客户端迁移到使用 admissionregistration.k8s.io/v1 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
)- 通过
admissionregistration.k8s.io/v1
创建的对象,webhooks[*].name
在列表中必须是唯一的
CustomResourceDefinition
CustomResourceDefinition 的 apiextensions.k8s.io/v1beta1 API 版本自 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
APIService 的 apiregistration.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。
- 将清单和 API 客户端迁移到使用 apiregistration.k8s.io/v1 API 版本,该版本自 v1.10 起可用。
- 所有现有持久化对象都可以通过新的 API 访问
- 无显著变化
TokenReview
TokenReview 的 authentication.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。
- 将清单和 API 客户端迁移到使用 authentication.k8s.io/v1 API 版本,该版本自 v1.6 起可用。
- 无显著变化
SubjectAccessReview 资源
LocalSubjectAccessReview、SelfSubjectAccessReview、SubjectAccessReview 和 SelfSubjectRulesReview 的 authorization.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。
- 将清单和 API 客户端迁移到使用 authorization.k8s.io/v1 API 版本,该版本自 v1.6 起可用。
- 显著变化
spec.group
在 v1 中已重命名为spec.groups
(修复了 #32709)
CertificateSigningRequest
CertificateSigningRequest 的 certificates.k8s.io/v1beta1 API 版本自 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
块
- 对于请求证书的 API 客户端
Lease
Lease 的 coordination.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。
- 将清单和 API 客户端迁移到使用 coordination.k8s.io/v1 API 版本,该版本自 v1.14 起可用。
- 所有现有持久化对象都可以通过新的 API 访问
- 无显著变化
Ingress
Ingress 的 extensions/v1beta1 和 networking.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。
- 将清单和 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
IngressClass 的 networking.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。
- 将清单和 API 客户端迁移到使用 networking.k8s.io/v1 API 版本,该版本自 v1.19 起可用。
- 所有现有持久化对象都可以通过新的 API 访问
- 无显著变化
RBAC 资源
ClusterRole、ClusterRoleBinding、Role 和 RoleBinding 的 rbac.authorization.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。
- 将清单和 API 客户端迁移到使用 rbac.authorization.k8s.io/v1 API 版本,该版本自 v1.8 起可用。
- 所有现有持久化对象都可以通过新的 API 访问
- 无显著变化
PriorityClass
PriorityClass 的 scheduling.k8s.io/v1beta1 API 版本自 v1.22 起不再提供。
- 将清单和 API 客户端迁移到使用 scheduling.k8s.io/v1 API 版本,该版本自 v1.14 起可用。
- 所有现有持久化对象都可以通过新的 API 访问
- 无显著变化
存储资源
CSIDriver、CSINode、StorageClass 和 VolumeAttachment 的 storage.k8s.io/v1beta1 API 版本自 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 在 storage.k8s.io/v1 v1.13 中可用
- 所有现有持久化对象都可以通过新的 API 访问
- 无显著变化
v1.16
v1.16 版本停止提供以下废弃的 API 版本
NetworkPolicy
NetworkPolicy 的 extensions/v1beta1 API 版本自 v1.16 起不再提供。
- 将清单和 API 客户端迁移到使用 networking.k8s.io/v1 API 版本,该版本自 v1.8 起可用。
- 所有现有持久化对象都可以通过新的 API 访问
DaemonSet
DaemonSet 的 extensions/v1beta1 和 apps/v1beta2 API 版本自 v1.16 起不再提供。
- 将清单和 API 客户端迁移到使用 apps/v1 API 版本,该版本自 v1.9 起可用。
- 所有现有持久化对象都可以通过新的 API 访问
- 显著变化
spec.templateGeneration
已移除spec.selector
现在是必需的,并且创建后不可变;使用现有模板标签作为选择器以实现无缝升级spec.updateStrategy.type
现在默认为RollingUpdate
(extensions/v1beta1
中的默认值为OnDelete
)
部署
Deployment 的 extensions/v1beta1、apps/v1beta1 和 apps/v1beta2 API 版本自 v1.16 起不再提供。
- 将清单和 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
StatefulSet 的 apps/v1beta1 和 apps/v1beta2 API 版本自 v1.16 起不再提供。
- 将清单和 API 客户端迁移到使用 apps/v1 API 版本,该版本自 v1.9 起可用。
- 所有现有持久化对象都可以通过新的 API 访问
- 显著变化
spec.selector
现在是必需的,并且创建后不可变;使用现有模板标签作为选择器以实现无缝升级spec.updateStrategy.type
现在默认为RollingUpdate
(apps/v1beta1
中的默认值为OnDelete
)
副本集
ReplicaSet 的 extensions/v1beta1、apps/v1beta1 和 apps/v1beta2 API 版本自 v1.16 起不再提供。
- 将清单和 API 客户端迁移到使用 apps/v1 API 版本,该版本自 v1.9 起可用。
- 所有现有持久化对象都可以通过新的 API 访问
- 显著变化
spec.selector
现在是必需的,并且创建后不可变;使用现有模板标签作为选择器以实现无缝升级
PodSecurityPolicy
PodSecurityPolicy 的 extensions/v1beta1 API 版本自 v1.16 起不再提供。
- 将清单和 API 客户端迁移到使用 policy/v1beta1 API 版本,该版本自 v1.10 起可用。
- 请注意,PodSecurityPolicy 的 policy/v1beta1 API 版本将在 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 参考。