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.32 release stopped serving the following deprecated API versions:
The flowcontrol.apiserver.k8s.io/v1beta3 API version of FlowSchema and PriorityLevelConfiguration is no longer served as of v1.32.
spec.limited.nominalConcurrencyShares field only defaults to 30 when unspecified, and an explicit value of 0 is not changed to 30.The v1.29 release stopped serving the following deprecated API versions:
The flowcontrol.apiserver.k8s.io/v1beta2 API version of FlowSchema and PriorityLevelConfiguration is no longer served as of v1.29.
spec.limited.assuredConcurrencyShares field is renamed to spec.limited.nominalConcurrencyShares and only defaults to 30 when unspecified, and an explicit value of 0 is not changed to 30.spec.limited.assuredConcurrencyShares field is renamed to spec.limited.nominalConcurrencySharesThe v1.27 release stopped serving the following deprecated API versions:
The storage.k8s.io/v1beta1 API version of CSIStorageCapacity is no longer served as of v1.27.
The v1.26 release stopped serving the following deprecated API versions:
The flowcontrol.apiserver.k8s.io/v1beta1 API version of FlowSchema and PriorityLevelConfiguration is no longer served as of v1.26.
The autoscaling/v2beta2 API version of HorizontalPodAutoscaler is no longer served as of v1.26.
targetAverageUtilization is replaced with target.averageUtilization and target.type: Utilization. See Autoscaling on multiple metrics and custom metrics.The v1.25 release stopped serving the following deprecated API versions:
The batch/v1beta1 API version of CronJob is no longer served as of v1.25.
The discovery.k8s.io/v1beta1 API version of EndpointSlice is no longer served as of 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 is no longer served as of v1.25.
type is limited to Normal and WarninginvolvedObject is renamed to regardingaction, 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 is no longer served as of v1.25.
targetAverageUtilization is replaced with target.averageUtilization and target.type: Utilization. See Autoscaling on multiple metrics and custom metrics.The policy/v1beta1 API version of PodDisruptionBudget is no longer served as of 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 is no longer served as of v1.25, and the PodSecurityPolicy admission controller will be removed.
Migrate to Pod Security Admission or a 3rd party admission webhook. For a migration guide, see Migrate from PodSecurityPolicy to the Built-In PodSecurity Admission Controller. For more information on the deprecation, see PodSecurityPolicy Deprecation: Past, Present, and Future.
RuntimeClass in the node.k8s.io/v1beta1 API version is no longer served as of 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/v1The 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 schemaspec.preserveUnknownFields: true is disallowed when creating v1 CustomResourceDefinition objects;
it must be specified within schema definitions as x-kubernetes-preserve-unknown-fields: trueadditionalPrinterColumns 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, SubjectAccessReview, and SelfSubjectRulesReview 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.defaultBackendserviceName field is renamed to service.nameservicePort fields are renamed to service.port.numberservicePort fields are renamed to service.port.namepathType 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 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
This conversion may use non-ideal default values. To learn more about a specific resource, check the Kubernetes API reference.
The kubectl convert tool is not installed by default, although
in fact it once was part of kubectl itself. For more details, you can read the
deprecation and removal issue
for the built-in subcommand.
To learn how to set up kubectl convert on your computer, visit the page that is right for your
operating system:
Linux,
macOS, or
Windows.