As the Kubernetes API evolves, APIs are periodically reorganized or upgraded. When APIs evolve, the old API is deprecated and eventually removed. This page contains information you need to know when migrating from deprecated API versions to newer and more stable API versions.
The v1.26 release will stop serving the following deprecated API versions:
The flowcontrol.apiserver.k8s.io/v1beta1 API version of FlowSchema and PriorityLevelConfiguration will no longer be served in v1.26.
The autoscaling/v2beta2 API version of HorizontalPodAutoscaler will no longer be served in v1.26.
The v1.25 release will stop serving the following deprecated API versions:
The batch/v1beta1 API version of CronJob will no longer be served in v1.25.
The discovery.k8s.io/v1beta1 API version of EndpointSlice will no longer be served in v1.25.
nodeName
field instead of deprecated topology["kubernetes.io/hostname"]
fieldzone
field instead of deprecated topology["topology.kubernetes.io/zone"]
fieldtopology
is replaced with the deprecatedTopology
field which is not writable in v1The events.k8s.io/v1beta1 API version of Event will no longer be served in v1.25.
type
is limited to Normal
and Warning
involvedObject
is renamed to regarding
action
, reason
, reportingController
, and reportingInstance
are required when creating new events.k8s.io/v1 EventseventTime
instead of the deprecated firstTimestamp
field (which is renamed to deprecatedFirstTimestamp
and not permitted in new events.k8s.io/v1 Events)series.lastObservedTime
instead of the deprecated lastTimestamp
field (which is renamed to deprecatedLastTimestamp
and not permitted in new events.k8s.io/v1 Events)series.count
instead of the deprecated count
field (which is renamed to deprecatedCount
and not permitted in new events.k8s.io/v1 Events)reportingController
instead of the deprecated source.component
field (which is renamed to deprecatedSource.component
and not permitted in new events.k8s.io/v1 Events)reportingInstance
instead of the deprecated source.host
field (which is renamed to deprecatedSource.host
and not permitted in new events.k8s.io/v1 Events)The autoscaling/v2beta1 API version of HorizontalPodAutoscaler will no longer be served in v1.25.
The policy/v1beta1 API version of PodDisruptionBudget will no longer be served in v1.25.
spec.selector
({}
) written to a policy/v1
PodDisruptionBudget selects all pods in the namespace (in policy/v1beta1
an empty spec.selector
selected no pods). An unset spec.selector
selects no pods in either API version.PodSecurityPolicy in the policy/v1beta1 API version will no longer be served in v1.25, and the PodSecurityPolicy admission controller will be removed.
PodSecurityPolicy replacements are still under discussion, but current use can be migrated to 3rd-party admission webhooks now.
RuntimeClass in the node.k8s.io/v1beta1 API version will no longer be served in v1.25.
The v1.22 release stopped serving the following deprecated API versions:
The admissionregistration.k8s.io/v1beta1 API version of MutatingWebhookConfiguration and ValidatingWebhookConfiguration is no longer served as of v1.22.
webhooks[*].failurePolicy
default changed from Ignore
to Fail
for v1webhooks[*].matchPolicy
default changed from Exact
to Equivalent
for v1webhooks[*].timeoutSeconds
default changed from 30s
to 10s
for v1webhooks[*].sideEffects
default value is removed, and the field made required, and only None
and NoneOnDryRun
are permitted for v1webhooks[*].admissionReviewVersions
default value is removed and the field made required for v1 (supported versions for AdmissionReview are v1
and v1beta1
)webhooks[*].name
must be unique in the list for objects created via admissionregistration.k8s.io/v1
The apiextensions.k8s.io/v1beta1 API version of CustomResourceDefinition is no longer served as of v1.22.
spec.scope
is no longer defaulted to Namespaced
and must be explicitly specifiedspec.version
is removed in v1; use spec.versions
insteadspec.validation
is removed in v1; use spec.versions[*].schema
insteadspec.subresources
is removed in v1; use spec.versions[*].subresources
insteadspec.additionalPrinterColumns
is removed in v1; use spec.versions[*].additionalPrinterColumns
insteadspec.conversion.webhookClientConfig
is moved to spec.conversion.webhook.clientConfig
in v1spec.conversion.conversionReviewVersions
is moved to spec.conversion.webhook.conversionReviewVersions
in v1spec.versions[*].schema.openAPIV3Schema
is now required when creating v1 CustomResourceDefinition objects, and must be a structural schema
spec.preserveUnknownFields: true
is disallowed when creating v1 CustomResourceDefinition objects; it must be specified within schema definitions as x-kubernetes-preserve-unknown-fields: true
additionalPrinterColumns
items, the JSONPath
field was renamed to jsonPath
in v1 (fixes #66531)The apiregistration.k8s.io/v1beta1 API version of APIService is no longer served as of v1.22.
The authentication.k8s.io/v1beta1 API version of TokenReview is no longer served as of v1.22.
The authorization.k8s.io/v1beta1 API version of LocalSubjectAccessReview, SelfSubjectAccessReview, and SubjectAccessReview is no longer served as of v1.22.
spec.group
was renamed to spec.groups
in v1 (fixes #32709)The certificates.k8s.io/v1beta1 API version of CertificateSigningRequest is no longer served as of v1.22.
certificates.k8s.io/v1
: spec.signerName
is now required (see known Kubernetes signers), and requests for kubernetes.io/legacy-unknown
are not allowed to be created via the certificates.k8s.io/v1
APIspec.usages
is now required, may not contain duplicate values, and must only contain known usagesstatus.conditions
may not contain duplicate typesstatus.conditions[*].status
is now requiredstatus.certificate
must be PEM-encoded, and contain only CERTIFICATE
blocksThe coordination.k8s.io/v1beta1 API version of Lease is no longer served as of v1.22.
The extensions/v1beta1 and networking.k8s.io/v1beta1 API versions of Ingress is no longer served as of v1.22.
spec.backend
is renamed to spec.defaultBackend
serviceName
field is renamed to service.name
servicePort
fields are renamed to service.port.number
servicePort
fields are renamed to service.port.name
pathType
is now required for each specified path. Options are Prefix
, Exact
, and ImplementationSpecific
. To match the undefined v1beta1
behavior, use ImplementationSpecific
.The networking.k8s.io/v1beta1 API version of IngressClass is no longer served as of v1.22.
The rbac.authorization.k8s.io/v1beta1 API version of ClusterRole, ClusterRoleBinding, Role, and RoleBinding is no longer served as of v1.22.
The scheduling.k8s.io/v1beta1 API version of PriorityClass is no longer served as of v1.22.
The storage.k8s.io/v1beta1 API version of CSIDriver, CSINode, StorageClass, and VolumeAttachment is no longer served as of v1.22.
The v1.16 release stopped serving the following deprecated API versions:
The extensions/v1beta1 API version of NetworkPolicy is no longer served as of v1.16.
The extensions/v1beta1 and apps/v1beta2 API versions of DaemonSet are no longer served as of v1.16.
spec.templateGeneration
is removedspec.selector
is now required and immutable after creation; use the existing template labels as the selector for seamless upgradesspec.updateStrategy.type
now defaults to RollingUpdate
(the default in extensions/v1beta1
was OnDelete
)The extensions/v1beta1, apps/v1beta1, and apps/v1beta2 API versions of Deployment are no longer served as of v1.16.
spec.rollbackTo
is removedspec.selector
is now required and immutable after creation; use the existing template labels as the selector for seamless upgradesspec.progressDeadlineSeconds
now defaults to 600
seconds (the default in extensions/v1beta1
was no deadline)spec.revisionHistoryLimit
now defaults to 10
(the default in apps/v1beta1
was 2
, the default in extensions/v1beta1
was to retain all)maxSurge
and maxUnavailable
now default to 25%
(the default in extensions/v1beta1
was 1
)The apps/v1beta1 and apps/v1beta2 API versions of StatefulSet are no longer served as of v1.16.
spec.selector
is now required and immutable after creation; use the existing template labels as the selector for seamless upgradesspec.updateStrategy.type
now defaults to RollingUpdate
(the default in apps/v1beta1
was OnDelete
)The extensions/v1beta1, apps/v1beta1, and apps/v1beta2 API versions of ReplicaSet are no longer served as of v1.16.
spec.selector
is now required and immutable after creation; use the existing template labels as the selector for seamless upgradesThe extensions/v1beta1 API version of PodSecurityPolicy is no longer served as of v1.16.
You can test your clusters by starting an API server with specific API versions disabled to simulate upcoming removals. Add the following flag to the API server startup arguments:
--runtime-config=<group>/<version>=false
For example:
--runtime-config=admissionregistration.k8s.io/v1beta1=false,apiextensions.k8s.io/v1beta1,...
Use client warnings, metrics, and audit information available in 1.19+ to locate use of deprecated APIs.
Update custom integrations and controllers to call the non-deprecated APIs
Change YAML files to reference the non-deprecated APIs
You can use the kubectl-convert
command (kubectl convert
prior to v1.20) to automatically convert an existing object:
kubectl-convert -f <file> --output-version <group>/<version>
.
For example, to convert an older Deployment to apps/v1
, you can run:
kubectl-convert -f ./my-deployment.yaml --output-version apps/v1
Note that this may use non-ideal default values. To learn more about a specific resource, check the Kubernetes API reference.
© 2022 The Kubernetes Authors
Documentation Distributed under CC BY 4.0.
https://kubernetes.io/docs/reference/using-api/deprecation-guide/