You are viewing documentation for Kubernetes version: v1.28
Kubernetes v1.28 documentation is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date information, see the latest version.
Deprecated API Migration Guide
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.
Removed APIs by release
v1.29
The v1.29 release will stop serving the following deprecated API versions:
Flow control resources
The flowcontrol.apiserver.k8s.io/v1beta2 API version of FlowSchema and PriorityLevelConfiguration will no longer be served in v1.29.
- Migrate manifests and API clients to use the flowcontrol.apiserver.k8s.io/v1beta3 API version, available since v1.26.
- All existing persisted objects are accessible via the new API
- Notable changes in flowcontrol.apiserver.k8s.io/v1beta3:
- The PriorityLevelConfiguration
spec.limited.assuredConcurrencyShares
field is renamed tospec.limited.nominalConcurrencyShares
- The PriorityLevelConfiguration
v1.27
The v1.27 release stopped serving the following deprecated API versions:
CSIStorageCapacity
The storage.k8s.io/v1beta1 API version of CSIStorageCapacity will no longer be served in v1.27.
- Migrate manifests and API clients to use the storage.k8s.io/v1 API version, available since v1.24.
- All existing persisted objects are accessible via the new API
- No notable changes
v1.26
The v1.26 release stopped serving the following deprecated API versions:
Flow control resources
The flowcontrol.apiserver.k8s.io/v1beta1 API version of FlowSchema and PriorityLevelConfiguration is no longer served as of v1.26.
- Migrate manifests and API clients to use the flowcontrol.apiserver.k8s.io/v1beta3 API version, available since v1.26.
- All existing persisted objects are accessible via the new API
- No notable changes
HorizontalPodAutoscaler
The autoscaling/v2beta2 API version of HorizontalPodAutoscaler is no longer served as of v1.26.
- Migrate manifests and API clients to use the autoscaling/v2 API version, available since v1.23.
- All existing persisted objects are accessible via the new API
v1.25
The v1.25 release stopped serving the following deprecated API versions:
CronJob
The batch/v1beta1 API version of CronJob is no longer served as of v1.25.
- Migrate manifests and API clients to use the batch/v1 API version, available since v1.21.
- All existing persisted objects are accessible via the new API
- No notable changes
EndpointSlice
The discovery.k8s.io/v1beta1 API version of EndpointSlice is no longer served as of v1.25.
- Migrate manifests and API clients to use the discovery.k8s.io/v1 API version, available since v1.21.
- All existing persisted objects are accessible via the new API
- Notable changes in discovery.k8s.io/v1:
- use per Endpoint
nodeName
field instead of deprecatedtopology["kubernetes.io/hostname"]
field - use per Endpoint
zone
field instead of deprecatedtopology["topology.kubernetes.io/zone"]
field topology
is replaced with thedeprecatedTopology
field which is not writable in v1
- use per Endpoint
Event
The events.k8s.io/v1beta1 API version of Event is no longer served as of v1.25.
- Migrate manifests and API clients to use the events.k8s.io/v1 API version, available since v1.19.
- All existing persisted objects are accessible via the new API
- Notable changes in events.k8s.io/v1:
type
is limited toNormal
andWarning
involvedObject
is renamed toregarding
action
,reason
,reportingController
, andreportingInstance
are required when creating new events.k8s.io/v1 Events- use
eventTime
instead of the deprecatedfirstTimestamp
field (which is renamed todeprecatedFirstTimestamp
and not permitted in new events.k8s.io/v1 Events) - use
series.lastObservedTime
instead of the deprecatedlastTimestamp
field (which is renamed todeprecatedLastTimestamp
and not permitted in new events.k8s.io/v1 Events) - use
series.count
instead of the deprecatedcount
field (which is renamed todeprecatedCount
and not permitted in new events.k8s.io/v1 Events) - use
reportingController
instead of the deprecatedsource.component
field (which is renamed todeprecatedSource.component
and not permitted in new events.k8s.io/v1 Events) - use
reportingInstance
instead of the deprecatedsource.host
field (which is renamed todeprecatedSource.host
and not permitted in new events.k8s.io/v1 Events)
HorizontalPodAutoscaler
The autoscaling/v2beta1 API version of HorizontalPodAutoscaler is no longer served as of v1.25.
- Migrate manifests and API clients to use the autoscaling/v2 API version, available since v1.23.
- All existing persisted objects are accessible via the new API
PodDisruptionBudget
The policy/v1beta1 API version of PodDisruptionBudget is no longer served as of v1.25.
- Migrate manifests and API clients to use the policy/v1 API version, available since v1.21.
- All existing persisted objects are accessible via the new API
- Notable changes in policy/v1:
- an empty
spec.selector
({}
) written to apolicy/v1
PodDisruptionBudget selects all pods in the namespace (inpolicy/v1beta1
an emptyspec.selector
selected no pods). An unsetspec.selector
selects no pods in either API version.
- an empty
PodSecurityPolicy
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
RuntimeClass in the node.k8s.io/v1beta1 API version is no longer served as of v1.25.
- Migrate manifests and API clients to use the node.k8s.io/v1 API version, available since v1.20.
- All existing persisted objects are accessible via the new API
- No notable changes
v1.22
The v1.22 release stopped serving the following deprecated API versions:
Webhook resources
The admissionregistration.k8s.io/v1beta1 API version of MutatingWebhookConfiguration and ValidatingWebhookConfiguration is no longer served as of v1.22.
- Migrate manifests and API clients to use the admissionregistration.k8s.io/v1 API version, available since v1.16.
- All existing persisted objects are accessible via the new APIs
- Notable changes:
webhooks[*].failurePolicy
default changed fromIgnore
toFail
for v1webhooks[*].matchPolicy
default changed fromExact
toEquivalent
for v1webhooks[*].timeoutSeconds
default changed from30s
to10s
for v1webhooks[*].sideEffects
default value is removed, and the field made required, and onlyNone
andNoneOnDryRun
are permitted for v1webhooks[*].admissionReviewVersions
default value is removed and the field made required for v1 (supported versions for AdmissionReview arev1
andv1beta1
)webhooks[*].name
must be unique in the list for objects created viaadmissionregistration.k8s.io/v1
CustomResourceDefinition
The apiextensions.k8s.io/v1beta1 API version of CustomResourceDefinition is no longer served as of v1.22.
- Migrate manifests and API clients to use the apiextensions.k8s.io/v1 API version, available since v1.16.
- All existing persisted objects are accessible via the new API
- Notable changes:
spec.scope
is no longer defaulted toNamespaced
and must be explicitly specifiedspec.version
is removed in v1; usespec.versions
insteadspec.validation
is removed in v1; usespec.versions[*].schema
insteadspec.subresources
is removed in v1; usespec.versions[*].subresources
insteadspec.additionalPrinterColumns
is removed in v1; usespec.versions[*].additionalPrinterColumns
insteadspec.conversion.webhookClientConfig
is moved tospec.conversion.webhook.clientConfig
in v1spec.conversion.conversionReviewVersions
is moved tospec.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 asx-kubernetes-preserve-unknown-fields: true
- In
additionalPrinterColumns
items, theJSONPath
field was renamed tojsonPath
in v1 (fixes #66531)
APIService
The apiregistration.k8s.io/v1beta1 API version of APIService is no longer served as of v1.22.
- Migrate manifests and API clients to use the apiregistration.k8s.io/v1 API version, available since v1.10.
- All existing persisted objects are accessible via the new API
- No notable changes
TokenReview
The authentication.k8s.io/v1beta1 API version of TokenReview is no longer served as of v1.22.
- Migrate manifests and API clients to use the authentication.k8s.io/v1 API version, available since v1.6.
- No notable changes
SubjectAccessReview resources
The authorization.k8s.io/v1beta1 API version of LocalSubjectAccessReview, SelfSubjectAccessReview, SubjectAccessReview, and SelfSubjectRulesReview is no longer served as of v1.22.
- Migrate manifests and API clients to use the authorization.k8s.io/v1 API version, available since v1.6.
- Notable changes:
spec.group
was renamed tospec.groups
in v1 (fixes #32709)
CertificateSigningRequest
The certificates.k8s.io/v1beta1 API version of CertificateSigningRequest is no longer served as of v1.22.
- Migrate manifests and API clients to use the certificates.k8s.io/v1 API version, available since v1.19.
- All existing persisted objects are accessible via the new API
- Notable changes in
certificates.k8s.io/v1
:- For API clients requesting certificates:
spec.signerName
is now required (see known Kubernetes signers), and requests forkubernetes.io/legacy-unknown
are not allowed to be created via thecertificates.k8s.io/v1
APIspec.usages
is now required, may not contain duplicate values, and must only contain known usages
- For API clients approving or signing certificates:
status.conditions
may not contain duplicate typesstatus.conditions[*].status
is now requiredstatus.certificate
must be PEM-encoded, and contain onlyCERTIFICATE
blocks
- For API clients requesting certificates:
Lease
The coordination.k8s.io/v1beta1 API version of Lease is no longer served as of v1.22.
- Migrate manifests and API clients to use the coordination.k8s.io/v1 API version, available since v1.14.
- All existing persisted objects are accessible via the new API
- No notable changes
Ingress
The extensions/v1beta1 and networking.k8s.io/v1beta1 API versions of Ingress is no longer served as of v1.22.
- Migrate manifests and API clients to use the networking.k8s.io/v1 API version, available since v1.19.
- All existing persisted objects are accessible via the new API
- Notable changes:
spec.backend
is renamed tospec.defaultBackend
- The backend
serviceName
field is renamed toservice.name
- Numeric backend
servicePort
fields are renamed toservice.port.number
- String backend
servicePort
fields are renamed toservice.port.name
pathType
is now required for each specified path. Options arePrefix
,Exact
, andImplementationSpecific
. To match the undefinedv1beta1
behavior, useImplementationSpecific
.
IngressClass
The networking.k8s.io/v1beta1 API version of IngressClass is no longer served as of v1.22.
- Migrate manifests and API clients to use the networking.k8s.io/v1 API version, available since v1.19.
- All existing persisted objects are accessible via the new API
- No notable changes
RBAC resources
The rbac.authorization.k8s.io/v1beta1 API version of ClusterRole, ClusterRoleBinding, Role, and RoleBinding is no longer served as of v1.22.
- Migrate manifests and API clients to use the rbac.authorization.k8s.io/v1 API version, available since v1.8.
- All existing persisted objects are accessible via the new APIs
- No notable changes
PriorityClass
The scheduling.k8s.io/v1beta1 API version of PriorityClass is no longer served as of v1.22.
- Migrate manifests and API clients to use the scheduling.k8s.io/v1 API version, available since v1.14.
- All existing persisted objects are accessible via the new API
- No notable changes
Storage resources
The storage.k8s.io/v1beta1 API version of CSIDriver, CSINode, StorageClass, and VolumeAttachment is no longer served as of v1.22.
- Migrate manifests and API clients to use the storage.k8s.io/v1 API version
- CSIDriver is available in storage.k8s.io/v1 since v1.19.
- CSINode is available in storage.k8s.io/v1 since v1.17
- StorageClass is available in storage.k8s.io/v1 since v1.6
- VolumeAttachment is available in storage.k8s.io/v1 v1.13
- All existing persisted objects are accessible via the new APIs
- No notable changes
v1.16
The v1.16 release stopped serving the following deprecated API versions:
NetworkPolicy
The extensions/v1beta1 API version of NetworkPolicy is no longer served as of v1.16.
- Migrate manifests and API clients to use the networking.k8s.io/v1 API version, available since v1.8.
- All existing persisted objects are accessible via the new API
DaemonSet
The extensions/v1beta1 and apps/v1beta2 API versions of DaemonSet are no longer served as of v1.16.
- Migrate manifests and API clients to use the apps/v1 API version, available since v1.9.
- All existing persisted objects are accessible via the new API
- Notable changes:
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 toRollingUpdate
(the default inextensions/v1beta1
wasOnDelete
)
Deployment
The extensions/v1beta1, apps/v1beta1, and apps/v1beta2 API versions of Deployment are no longer served as of v1.16.
- Migrate manifests and API clients to use the apps/v1 API version, available since v1.9.
- All existing persisted objects are accessible via the new API
- Notable changes:
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 to600
seconds (the default inextensions/v1beta1
was no deadline)spec.revisionHistoryLimit
now defaults to10
(the default inapps/v1beta1
was2
, the default inextensions/v1beta1
was to retain all)maxSurge
andmaxUnavailable
now default to25%
(the default inextensions/v1beta1
was1
)
StatefulSet
The apps/v1beta1 and apps/v1beta2 API versions of StatefulSet are no longer served as of v1.16.
- Migrate manifests and API clients to use the apps/v1 API version, available since v1.9.
- All existing persisted objects are accessible via the new API
- Notable changes:
spec.selector
is now required and immutable after creation; use the existing template labels as the selector for seamless upgradesspec.updateStrategy.type
now defaults toRollingUpdate
(the default inapps/v1beta1
wasOnDelete
)
ReplicaSet
The extensions/v1beta1, apps/v1beta1, and apps/v1beta2 API versions of ReplicaSet are no longer served as of v1.16.
- Migrate manifests and API clients to use the apps/v1 API version, available since v1.9.
- All existing persisted objects are accessible via the new API
- Notable changes:
spec.selector
is now required and immutable after creation; use the existing template labels as the selector for seamless upgrades
PodSecurityPolicy
The extensions/v1beta1 API version of PodSecurityPolicy is no longer served as of v1.16.
- Migrate manifests and API client to use the policy/v1beta1 API version, available since v1.10.
- Note that the policy/v1beta1 API version of PodSecurityPolicy will be removed in v1.25.
What to do
Test with deprecated APIs disabled
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,...
Locate use of deprecated APIs
Use client warnings, metrics, and audit information available in 1.19+ to locate use of deprecated APIs.
Migrate to non-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.
Note:The
kubectl convert
tool is not installed by default, although in fact it once was part ofkubectl
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.