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.25

The v1.25 release will stop serving the following deprecated API versions:

Event

The events.k8s.io/v1beta1 API version of Event will no longer be served in 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 to Normal and Warning
  • involvedObject is renamed to regarding
  • action, reason, reportingComponent, and reportingInstance are required when creating new events.k8s.io/v1 Events
  • use eventTime instead of the deprecated firstTimestamp field (which is renamed to deprecatedFirstTimestamp and not permitted in new events.k8s.io/v1 Events)
  • use series.lastObservedTime instead of the deprecated lastTimestamp field (which is renamed to deprecatedLastTimestamp and not permitted in new events.k8s.io/v1 Events)
  • use series.count instead of the deprecated count field (which is renamed to deprecatedCount and not permitted in new events.k8s.io/v1 Events)
  • use reportingComponent instead of the deprecated source.component field (which is renamed to deprecatedSource.component and not permitted in new events.k8s.io/v1 Events)
  • use reportingInstance instead of the deprecated source.host field (which is renamed to deprecatedSource.host and not permitted in new events.k8s.io/v1 Events)

RuntimeClass

RuntimeClass in the node.k8s.io/v1beta1 API version will no longer be served in 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 will stop serving the following deprecated API versions:

Webhook resources

The admissionregistration.k8s.io/v1beta1 API version of MutatingWebhookConfiguration and ValidatingWebhookConfiguration will no longer be served in 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 from Ignore to Fail for v1
  • webhooks[*].matchPolicy default changed from Exact to Equivalent for v1
  • webhooks[*].timeoutSeconds default changed from 30s to 10s for v1
  • webhooks[*].sideEffects default value is removed, and the field made required, and only None and NoneOnDryRun are permitted for v1
  • webhooks[*].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

CustomResourceDefinition

The apiextensions.k8s.io/v1beta1 API version of CustomResourceDefinition will no longer be served in 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 to Namespaced and must be explicitly specified
  • spec.version is removed in v1; use spec.versions instead
  • spec.validation is removed in v1; use spec.versions[*].schema instead
  • spec.subresources is removed in v1; use spec.versions[*].subresources instead
  • spec.additionalPrinterColumns is removed in v1; use spec.versions[*].additionalPrinterColumns instead
  • spec.conversion.webhookClientConfig is moved to spec.conversion.webhook.clientConfig in v1
  • spec.conversion.conversionReviewVersions is moved to spec.conversion.webhook.conversionReviewVersions in v1
  • spec.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
  • In additionalPrinterColumns items, the JSONPath field was renamed to jsonPath in v1 (fixes #66531)

APIService

The apiregistration.k8s.io/v1beta1 API version of APIService will no longer be served in 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 will no longer be served in 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, and SubjectAccessReview will no longer be served in 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 to spec.groups in v1 (fixes #32709)

CertificateSigningRequest

The certificates.k8s.io/v1beta1 API version of CertificateSigningRequest will no longer be served in 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 for kubernetes.io/legacy-unknown are not allowed to be created via the certificates.k8s.io/v1 API
    • spec.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 types
    • status.conditions[*].status is now required
    • status.certificate must be PEM-encoded, and contain only CERTIFICATE blocks

Lease

The coordination.k8s.io/v1beta1 API version of Lease will no longer be served in 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 will no longer be served in 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 to spec.defaultBackend
  • The backend serviceName field is renamed to service.name
  • Numeric backend servicePort fields are renamed to service.port.number
  • String backend 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.

IngressClass

The networking.k8s.io/v1beta1 API version of IngressClass will no longer be served in 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 will no longer be served in 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 will no longer be served in 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 will no longer be served in 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 removed
  • spec.selector is now required and immutable after creation; use the existing template labels as the selector for seamless upgrades
  • spec.updateStrategy.type now defaults to RollingUpdate (the default in extensions/v1beta1 was OnDelete)

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 removed
  • spec.selector is now required and immutable after creation; use the existing template labels as the selector for seamless upgrades
  • spec.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)

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 upgrades
  • spec.updateStrategy.type now defaults to RollingUpdate (the default in apps/v1beta1 was OnDelete)

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

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 (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.