kubernetes reference title Kubernetes Deprecation Policy bgrant0607 contenttype concept weight 40 reviewers thockin lavalamp

Answer:
---
reviewers:
- bgrant0607
- lavalamp
- thockin
title: Kubernetes Deprecation Policy
content_type: concept
weight: 40
---

This document details the deprecation policy for various facets of the system.

Kubernetes is a large system with many components and many contributors. As
with any such software, the feature set naturally evolves over time, and
sometimes a feature may need to be removed. This could include an API, a flag,
or even an entire feature. To avoid breaking existing users, Kubernetes follows
a deprecation policy for aspects of the system that are slated to be removed.

## Deprecating parts of the API

Since Kubernetes is an API-driven system, the API has evolved over time to
reflect the evolving understanding of the problem space. The Kubernetes API is
actually a set of APIs, called "API groups", and each API group is
independently versioned. [API versions](/docs/reference/using-api/#api-versioning) fall
into 3 main tracks, each of which has different policies for deprecation:

| Example  | Track                            |
|----------|----------------------------------|
| v1       | GA (generally available, stable) |
| v1beta1  | Beta (pre-release)               |
| v1alpha1 | Alpha (experimental)             |

A given release of Kubernetes can support any number of API groups and any
number of versions of each.

The following rules govern the deprecation of elements of the API. This
includes:

* REST resources (aka API objects)
* Fields of REST resources
* Annotations on REST resources, including "beta" annotations but not
  including "alpha" annotations.
* Enumerated or constant values
* Component config structures

These rules are enforced between official releases, not between
arbitrary commits to master or release branches.

**Rule #1: API elements may only be removed by incrementing the version of the
API group.**

Once an API element has been added to an API group at a particular version, it
can not be removed from that version or have its behavior significantly
changed, regardless of track.

For historical reasons, there are 2 "monolithic" API groups - "core" (no
group name) and "extensions". Resources will incrementally be moved from these
legacy API groups into more domain-specific API groups.

**Rule #2: API objects must be able to round-trip between API versions in a given
release without information loss, with the exception of whole REST resources
that do not exist in some versions.**

For example, an object can be written as v1 and then read back as v2 and
converted to v1, and the resulting v1 resource will be identical to the
original. The representation in v2 might be different from v1, but the system
knows how to convert between them in both directions. Additionally, any new
field added in v2 must be able to round-trip to v1 and back, which means v1
might have to add an equivalent field or represent it as an annotation.

**Rule #3: An API version in a given track may not be deprecated in favor of a less stable API version.**

* GA API versions can replace beta and alpha API versions.
* Beta API versions can replace earlier beta and alpha API versions, but *may not* replace GA API versions.
* Alpha API versions can replace earlier alpha API versions, but *may not* replace GA or beta API versions.

**Rule #4a: API lifetime is determined by the API stability level**

* GA API versions may be marked as deprecated, but must not be removed within a major version of Kubernetes
* Beta API versions are deprecated no more than 9 months or 3 minor releases after introduction (whichever is longer),
  and are no longer served 9 months or 3 minor releases after deprecation (whichever is longer)
* Alpha API versions may be removed in any release without prior deprecation notice

This ensures beta API support covers the [maximum supported version skew of 2 releases](/releases/version-skew-policy/),
and that APIs don't stagnate on unstable beta versions, accumulating production usage that will be
disrupted when support for the beta API ends.

There are no current plans for a major version revision of Kubernetes that removes GA APIs.

Until [#52185](https://github.com/kubernetes/kubernetes/issues/52185) is
resolved, no API versions that have been persisted to storage may be removed.
Serving REST endpoints for those versions may be disabled (subject to the
deprecation timelines in this document), but the API server must remain capable
of decoding/converting previously persisted data from storage.

**Rule #4b: The "preferred" API version and the "storage version" for a given
group may not advance until after a release has been made that supports both the
new version and the previous version**

Users must be able to upgrade to a new release of Kubernetes and then roll back
to a previous release, without converting anything to the new API version or
suffering breakages (unless they explicitly used features only available in the
newer version). This is particularly evident in the stored representation of
objects.

All of this is best illustrated by examples. Imagine a Kubernetes release,
version X, which introduces a new API group. A new Kubernetes release is made
every approximately 4 months (3 per year). The following table describes which
API versions are supported in a series of subsequent releases.

      Release
      API Versions
      Preferred/Storage Version
      Notes

      X
      v1alpha1
      v1alpha1

      X+1
      v1alpha2
      v1alpha2

v1alpha1 is removed. See release notes for required actions.

      X+2
      v1beta1
      v1beta1

v1alpha2 is removed. See release notes for required actions.

      X+3
      v1beta2, v1beta1 (deprecated)
      v1beta1

v1beta1 is deprecated. See release notes for required actions.

      X+4
      v1beta2, v1beta1 (deprecated)
      v1beta2

      X+5
      v1, v1beta1 (deprecated), v1beta2 (deprecated)
      v1beta2

v1beta2 is deprecated. See release notes for required actions.

      X+6
      v1, v1beta2 (deprecated)
      v1

v1beta1 is removed. See release notes for required actions.

      X+7
      v1, v1beta2 (deprecated)
      v1

      X+8
      v2alpha1, v1
      v1

v1beta2 is removed. See release notes for required actions.

      X+9
      v2alpha2, v1
      v1

v2alpha1 is removed. See release notes for required actions.

      X+10
      v2beta1, v1
      v1

v2alpha2 is removed. See release notes for required actions.

      X+11
      v2beta2, v2beta1 (deprecated), v1
      v1

v2beta1 is deprecated. See release notes for required actions.

      X+12
      v2, v2beta2 (deprecated), v2beta1 (deprecated), v1 (deprecated)
      v1

v2beta2 is deprecated. See release notes for required actions.

v1 is deprecated in favor of v2, but will not be removed

      X+13
      v2, v2beta1 (deprecated), v2beta2 (deprecated), v1 (deprecated)
      v2

      X+14
      v2, v2beta2 (deprecated), v1 (deprecated)
      v2

v2beta1 is removed. See release notes for required actions.

      X+15
      v2, v1 (deprecated)
      v2

v2beta2 is removed. See release notes for required actions.

### REST resources (aka API objects)

Consider a hypothetical REST resource named Widget, which was present in API v1
in the above timeline, and which needs to be deprecated. We document and
[announce](https://groups.google.com/forum/#!forum/kubernetes-announce) the
deprecation in sync with release X+1. The Widget resource still exists in API
version v1 (deprecated) but not in v2alpha1. The Widget resource continues to
exist and function in releases up to and including X+8. Only in release X+9,
when API v1 has aged out, does the Widget resource cease to exist, and the
behavior get removed.

Starting in Kubernetes v1.19, making an API request to a deprecated REST API endpoint:

1. Returns a `Warning` header
   (as defined in [RFC7234, Section 5.5](https://tools.ietf.org/html/rfc7234#section-5.5)) in the API response.
1. Adds a `"k8s.io/deprecated":"true"` annotation to the
   [audit event](/docs/tasks/debug/debug-cluster/audit/) recorded for the request.
1. Sets an `apiserver_requested_deprecated_apis` gauge metric to `1` in the `kube-apiserver`
   process. The metric has labels for `group`, `version`, `resource`, `subresource` that can be joined
   to the `apiserver_request_total` metric, and a `removed_release` label that indicates the
   Kubernetes release in which the API will no longer be served. The following Prometheus query
   returns information about requests made to deprecated APIs which will be removed in v1.22:

   ```promql
   apiserver_requested_deprecated_apis{removed_release="1.22"} * on(group,version,resource,subresource) group_right() apiserver_request_total
   ```

### Fields of REST resources

As with whole REST resources, an individual field which was present in API v1
must exist and function until API v1 is removed. Unlike whole resources, the
v2 APIs may choose a different representation for the field, as long as it can
be round-tripped. For example a v1 field named "magnitude" which was
deprecated might be named "deprecatedMagnitude" in API v2. When v1 is
eventually removed, the deprecated field can be removed from v2.

### Enumerated or constant values

As with whole REST resources and fields thereof, a constant value which was
supported in API v1 must exist and function until API v1 is removed.

### Component config structures

Component configs are versioned and managed similar to REST resources.

### Future work

Over time, Kubernetes will introduce more fine-grained API versions, at which
point these rules will be adjusted as needed.

## Deprecating a flag or CLI

The Kubernetes system is comprised of several different programs cooperating.
Sometimes, a Kubernetes release might remove flags or CLI commands
(collectively "CLI elements") in these programs. The individual programs
naturally sort into two main groups - user-facing and admin-facing programs,
which vary slightly in their deprecation policies. Unless a flag is explicitly
prefixed or documented as "alpha" or "beta", it is considered GA.

CLI elements are effectively part of the API to the system, but since they are
not versioned in the same way as the REST API, the rules for deprecation are as
follows:

**Rule #5a: CLI elements of user-facing components (e.g. kubectl) must function
after their announced deprecation for no less than:**

* **GA: 12 months or 2 releases (whichever is longer)**
* **Beta: 3 months or 1 release (whichever is longer)**
* **Alpha: 0 releases**

**Rule #5b: CLI elements of admin-facing components (e.g. kubelet) must function
after their announced deprecation for no less than:**

* **GA: 6 months or 1 release (whichever is longer)**
* **Beta: 3 months or 1 release (whichever is longer)**
* **Alpha: 0 releases**

**Rule #5c: Command line interface (CLI) elements cannot be deprecated in favor of
less stable CLI elements**

Similar to the Rule #3 for APIs, if an element of a command line interface is being replaced with an
alternative implementation, such as by renaming an existing element, or by switching to
use configuration sourced from a file
instead of a command line argument, that recommended alternative must be of
the same or higher stability level.

**Rule #6: Deprecated CLI elements must emit warnings (optionally disable)
when used.**

## Deprecating a feature or behavior

Occasionally a Kubernetes release needs to deprecate some feature or behavior
of the system that is not controlled by the API or CLI. In this case, the
rules for deprecation are as follows:

**Rule #7: Deprecated behaviors must function for no less than 1 year after their
announced deprecation.**

If the feature or behavior is being replaced with an alternative implementation
that requires work to adopt the change, there should be an effort to simplify
the transition whenever possible. If an alternative implementation is under
Kubernetes organization control, the following rules apply:

**Rule #8: The feature of behavior must not be deprecated in favor of an alternative
implementation that is less stable**

For example, a generally available feature cannot be deprecated in favor of a Beta replacement.
The Kubernetes project does, however, encourage users to adopt and transitions to alternative
implementations even before they reach the same maturity level. This is particularly important
for exploring new use cases of a feature or getting an early feedback on the replacement.

Alternative implementations may sometimes be external tools or products,
for example a feature may move from the kubelet to container runtime
that is not under Kubernetes project control. In such cases, the rule cannot be
applied, but there must be an effort to ensure that there is a transition path
that does not compromise on components' maturity levels. In the example with
container runtimes, the effort may involve trying to ensure that popular container runtimes
have versions that offer the same level of stability while implementing that replacement behavior.

Deprecation rules for features and behaviors do not imply that all changes
to the system are governed by this policy.
These rules apply only to significant, user-visible behaviors which impact the
correctness of applications running on Kubernetes or that impact the
administration of Kubernetes clusters, and which are being removed entirely.

An exception to the above rule is _feature gates_. Feature gates are key=value
pairs that allow for users to enable/disable experimental features.

Feature gates are intended to cover the development life cycle of a feature - they
are not intended to be long-term APIs. As such, they are expected to be deprecated
and removed after a feature becomes GA or is dropped.

As a feature moves through the stages, the associated feature gate evolves.
The feature life cycle matched to its corresponding feature gate is:

* Alpha: the feature gate is disabled by default and can be enabled by the user.
* Beta: the feature gate is enabled by default and can be disabled by the user.
* GA: the feature gate is deprecated (see ["Deprecation"](#deprecation)) and becomes
  non-operational.
* GA, deprecation window complete: the feature gate is removed and calls to it are
  no longer accepted.

### Deprecation

Features can be removed at any point in the life cycle prior to GA. When features are
removed prior to GA, their associated feature gates are also deprecated.

When an invocation tries to disable a non-operational feature gate, the call fails in order
to avoid unsupported scenarios that might otherwise run silently.

In some cases, removing pre-GA features requires considerable time. Feature gates can remain
operational until their associated feature is fully removed, at which point the feature gate
itself can be deprecated.

When removing a feature gate for a GA feature also requires considerable time, calls to
feature gates may remain operational if the feature gate has no effect on the feature,
and if the feature gate causes no errors.

Features intended to be disabled by users should include a mechanism for disabling the
feature in the associated feature gate.

Versioning for feature gates is different from the previously discussed components,
therefore the rules for deprecation are as follows:

**Rule #9: Feature gates must be deprecated when the corresponding feature they control
transitions a lifecycle stage as follows. Feature gates must function for no less than:**

* **Beta feature to GA: 6 months or 2 releases (whichever is longer)**
* **Beta feature to EOL: 3 months or 1 release (whichever is longer)**
* **Alpha feature to EOL: 0 releases**

**Rule #10: Deprecated feature gates must respond with a warning when used. When a feature gate
is deprecated it must be documented in both in the release notes and the corresponding CLI help.
Both warnings and documentation must indicate whether a feature gate is non-operational.**

## Deprecating a metric

Each component of the Kubernetes control-plane exposes metrics (usually the
`/metrics` endpoint), which are typically ingested by cluster administrators.
Not all metrics are the same: some metrics are commonly used as SLIs or used
to determine SLOs, these tend to have greater import. Other metrics are more
experimental in nature or are used primarily in the Kubernetes development
process.

Accordingly, metrics fall under three stability classes (`ALPHA`, `BETA` `STABLE`);
this impacts removal of a metric during a Kubernetes release. These classes
are determined by the perceived importance of the metric. The rules for
deprecating and removing a metric are as follows:

**Rule #11a: Metrics, for the corresponding stability class, must function for no less than:**

* **STABLE: 4 releases or 12 months (whichever is longer)**
* **BETA: 2 releases or 8 months (whichever is longer)**
* **ALPHA: 0 releases**

**Rule #11b: Metrics, after their _announced deprecation_, must function for no less than:**

* **STABLE: 3 releases or 9 months (whichever is longer)**
* **BETA: 1 releases or 4 months (whichever is longer)**
* **ALPHA: 0 releases**

Deprecated metrics will have their description text prefixed with a deprecation notice
string '(Deprecated from x.y)' and a warning log will be emitted during metric
registration. Like their stable undeprecated counterparts, deprecated metrics will
be automatically registered to the metrics endpoint and therefore visible.

On a subsequent release (when the metric's `deprecatedVersion` is equal to
_current_kubernetes_version - 3_), a deprecated metric will become a _hidden_ metric.
**_Unlike_** their deprecated counterparts, hidden metrics will _no longer_ be
automatically registered to the metrics endpoint (hence hidden). However, they
can be explicitly enabled through a command line flag on the binary
(`--show-hidden-metrics-for-version=`). This provides cluster admins an
escape hatch to properly migrate off of a deprecated metric, if they were not
able to react to the earlier deprecation warnings. Hidden metrics should be
deleted after one release.

## Exceptions

No policy can cover every possible situation. This policy is a living
document, and will evolve over time. In practice, there will be situations
that do not fit neatly into this policy, or for which this policy becomes a
serious impediment. Such situations should be discussed with SIGs and project
leaders to find the best solutions for those specific cases, always bearing in
mind that Kubernetes is committed to being a stable system that, as much as
possible, never breaks users. Exceptions will always be announced in all
relevant release notes.

reviewers    bgrant0607   lavalamp   thockin title  Kubernetes Deprecation Policy content type  concept weight  40           overview     This document details the deprecation policy for various facets of the system        body     Kubernetes is a large system with many components and many contributors  As with any such software  the feature set naturally evolves over time  and sometimes a feature may need to be removed  This could include an API  a flag  or even an entire feature  To avoid breaking existing users  Kubernetes follows a deprecation policy for aspects of the system that are slated to be removed      Deprecating parts of the API  Since Kubernetes is an API driven system  the API has evolved over time to reflect the evolving understanding of the problem space  The Kubernetes API is actually a set of APIs  called  API groups   and each API group is independently versioned   API versions   docs reference using api  api versioning  fall into 3 main tracks  each of which has different policies for deprecation     Example    Track                                                                                v1         GA  generally available  stable      v1beta1    Beta  pre release                    v1alpha1   Alpha  experimental                 A given release of Kubernetes can support any number of API groups and any number of versions of each   The following rules govern the deprecation of elements of the API  This includes     REST resources  aka API objects    Fields of REST resources   Annotations on REST resources  including  beta  annotations but not   including  alpha  annotations    Enumerated or constant values   Component config structures  These rules are enforced between official releases  not between arbitrary commits to master or release branches     Rule  1  API elements may only be removed by incrementing the version of the API group     Once an API element has been added to an API group at a particular version  it can not be removed from that version or have its behavior significantly changed  regardless of track    For historical reasons  there are 2  monolithic  API groups    core   no group name  and  extensions   Resources will incrementally be moved from these legacy API groups into more domain specific API groups      Rule  2  API objects must be able to round trip between API versions in a given release without information loss  with the exception of whole REST resources that do not exist in some versions     For example  an object can be written as v1 and then read back as v2 and converted to v1  and the resulting v1 resource will be identical to the original  The representation in v2 might be different from v1  but the system knows how to convert between them in both directions  Additionally  any new field added in v2 must be able to round trip to v1 and back  which means v1 might have to add an equivalent field or represent it as an annotation     Rule  3  An API version in a given track may not be deprecated in favor of a less stable API version       GA API versions can replace beta and alpha API versions    Beta API versions can replace earlier beta and alpha API versions  but  may not  replace GA API versions    Alpha API versions can replace earlier alpha API versions  but  may not  replace GA or beta API versions     Rule  4a  API lifetime is determined by the API stability level      GA API versions may be marked as deprecated  but must not be removed within a major version of Kubernetes   Beta API versions are deprecated no more than 9 months or 3 minor releases after introduction  whichever is longer     and are no longer served 9 months or 3 minor releases after deprecation  whichever is longer    Alpha API versions may be removed in any release without prior deprecation notice  This ensures beta API support covers the  maximum supported version skew of 2 releases   releases version skew policy    and that APIs don t stagnate on unstable beta versions  accumulating production usage that will be disrupted when support for the beta API ends    There are no current plans for a major version revision of Kubernetes that removes GA APIs     Until   52185  https   github com kubernetes kubernetes issues 52185  is resolved  no API versions that have been persisted to storage may be removed  Serving REST endpoints for those versions may be disabled  subject to the deprecation timelines in this document   but the API server must remain capable of decoding converting previously persisted data from storage      Rule  4b  The  preferred  API version and the  storage version  for a given group may not advance until after a release has been made that supports both the new version and the previous version    Users must be able to upgrade to a new release of Kubernetes and then roll back to a previous release  without converting anything to the new API version or suffering breakages  unless they explicitly used features only available in the newer version   This is particularly evident in the stored representation of objects   All of this is best illustrated by examples  Imagine a Kubernetes release  version X  which introduces a new API group  A new Kubernetes release is made every approximately 4 months  3 per year   The following table describes which API versions are supported in a series of subsequent releases    table     thead       tr         th Release  th         th API Versions  th         th Preferred Storage Version  th         th Notes  th        tr      thead     tbody       tr         td X  td         td v1alpha1  td         td v1alpha1  td         td   td        tr       tr         td X 1  td         td v1alpha2  td         td v1alpha2  td         td           ul              li v1alpha1 is removed  See release notes for required actions   li            ul          td        tr       tr         td X 2  td         td v1beta1  td         td v1beta1  td         td           ul             li v1alpha2 is removed  See release notes for required actions   li            ul          td        tr       tr         td X 3  td         td v1beta2  v1beta1  deprecated   td         td v1beta1  td         td           ul             li v1beta1 is deprecated  See release notes for required actions   li            ul          td        tr       tr         td X 4  td         td v1beta2  v1beta1  deprecated   td         td v1beta2  td         td   td        tr       tr         td X 5  td         td v1  v1beta1  deprecated   v1beta2  deprecated   td         td v1beta2  td         td           ul             li v1beta2 is deprecated  See release notes for required actions   li            ul          td        tr       tr         td X 6  td         td v1  v1beta2  deprecated   td         td v1  td         td           ul             li v1beta1 is removed  See release notes for required actions   li            ul          td        tr       tr         td X 7  td         td v1  v1beta2  deprecated   td         td v1  td         td   td        tr       tr         td X 8  td         td v2alpha1  v1  td         td v1  td         td           ul             li v1beta2 is removed  See release notes for required actions   li            ul          td        tr       tr         td X 9  td         td v2alpha2  v1  td         td v1  td         td           ul              li v2alpha1 is removed  See release notes for required actions   li            ul          td        tr       tr         td X 10  td         td v2beta1  v1  td         td v1  td         td           ul             li v2alpha2 is removed  See release notes for required actions   li            ul          td        tr       tr         td X 11  td         td v2beta2  v2beta1  deprecated   v1  td         td v1  td         td           ul             li v2beta1 is deprecated  See release notes for required actions   li            ul          td        tr       tr         td X 12  td         td v2  v2beta2  deprecated   v2beta1  deprecated   v1  deprecated   td         td v1  td         td           ul             li v2beta2 is deprecated  See release notes for required actions   li             li v1 is deprecated in favor of v2  but will not be removed  li            ul          td        tr       tr         td X 13  td         td v2  v2beta1  deprecated   v2beta2  deprecated   v1  deprecated   td         td v2  td         td   td        tr       tr         td X 14  td         td v2  v2beta2  deprecated   v1  deprecated   td         td v2  td         td           ul             li v2beta1 is removed  See release notes for required actions   li            ul          td        tr       tr         td X 15  td         td v2  v1  deprecated   td         td v2  td         td           ul             li v2beta2 is removed  See release notes for required actions   li            ul          td        tr      tbody    table       REST resources  aka API objects   Consider a hypothetical REST resource named Widget  which was present in API v1 in the above timeline  and which needs to be deprecated  We document and  announce  https   groups google com forum   forum kubernetes announce  the deprecation in sync with release X 1  The Widget resource still exists in API version v1  deprecated  but not in v2alpha1  The Widget resource continues to exist and function in releases up to and including X 8  Only in release X 9  when API v1 has aged out  does the Widget resource cease to exist  and the behavior get removed   Starting in Kubernetes v1 19  making an API request to a deprecated REST API endpoint   1  Returns a  Warning  header     as defined in  RFC7234  Section 5 5  https   tools ietf org html rfc7234 section 5 5   in the API response  1  Adds a   k8s io deprecated   true   annotation to the     audit event   docs tasks debug debug cluster audit   recorded for the request  1  Sets an  apiserver requested deprecated apis  gauge metric to  1  in the  kube apiserver     process  The metric has labels for  group    version    resource    subresource  that can be joined    to the  apiserver request total  metric  and a  removed release  label that indicates the    Kubernetes release in which the API will no longer be served  The following Prometheus query    returns information about requests made to deprecated APIs which will be removed in v1 22         promql    apiserver requested deprecated apis removed release  1 22     on group version resource subresource  group right   apiserver request total             Fields of REST resources  As with whole REST resources  an individual field which was present in API v1 must exist and function until API v1 is removed  Unlike whole resources  the v2 APIs may choose a different representation for the field  as long as it can be round tripped  For example a v1 field named  magnitude  which was deprecated might be named  deprecatedMagnitude  in API v2  When v1 is eventually removed  the deprecated field can be removed from v2       Enumerated or constant values  As with whole REST resources and fields thereof  a constant value which was supported in API v1 must exist and function until API v1 is removed       Component config structures  Component configs are versioned and managed similar to REST resources       Future work  Over time  Kubernetes will introduce more fine grained API versions  at which point these rules will be adjusted as needed      Deprecating a flag or CLI  The Kubernetes system is comprised of several different programs cooperating  Sometimes  a Kubernetes release might remove flags or CLI commands  collectively  CLI elements   in these programs  The individual programs naturally sort into two main groups   user facing and admin facing programs  which vary slightly in their deprecation policies  Unless a flag is explicitly prefixed or documented as  alpha  or  beta   it is considered GA   CLI elements are effectively part of the API to the system  but since they are not versioned in the same way as the REST API  the rules for deprecation are as follows     Rule  5a  CLI elements of user facing components  e g  kubectl  must function after their announced deprecation for no less than         GA  12 months or 2 releases  whichever is longer        Beta  3 months or 1 release  whichever is longer        Alpha  0 releases      Rule  5b  CLI elements of admin facing components  e g  kubelet  must function after their announced deprecation for no less than         GA  6 months or 1 release  whichever is longer        Beta  3 months or 1 release  whichever is longer        Alpha  0 releases      Rule  5c  Command line interface  CLI  elements cannot be deprecated in favor of less stable CLI elements    Similar to the Rule  3 for APIs  if an element of a command line interface is being replaced with an alternative implementation  such as by renaming an existing element  or by switching to use configuration sourced from a file instead of a command line argument  that recommended alternative must be of the same or higher stability level     Rule  6  Deprecated CLI elements must emit warnings  optionally disable  when used        Deprecating a feature or behavior  Occasionally a Kubernetes release needs to deprecate some feature or behavior of the system that is not controlled by the API or CLI  In this case  the rules for deprecation are as follows     Rule  7  Deprecated behaviors must function for no less than 1 year after their announced deprecation     If the feature or behavior is being replaced with an alternative implementation that requires work to adopt the change  there should be an effort to simplify the transition whenever possible  If an alternative implementation is under Kubernetes organization control  the following rules apply     Rule  8  The feature of behavior must not be deprecated in favor of an alternative implementation that is less stable    For example  a generally available feature cannot be deprecated in favor of a Beta replacement  The Kubernetes project does  however  encourage users to adopt and transitions to alternative implementations even before they reach the same maturity level  This is particularly important for exploring new use cases of a feature or getting an early feedback on the replacement   Alternative implementations may sometimes be external tools or products  for example a feature may move from the kubelet to container runtime that is not under Kubernetes project control  In such cases  the rule cannot be applied  but there must be an effort to ensure that there is a transition path that does not compromise on components  maturity levels  In the example with container runtimes  the effort may involve trying to ensure that popular container runtimes have versions that offer the same level of stability while implementing that replacement behavior   Deprecation rules for features and behaviors do not imply that all changes to the system are governed by this policy  These rules apply only to significant  user visible behaviors which impact the correctness of applications running on Kubernetes or that impact the administration of Kubernetes clusters  and which are being removed entirely   An exception to the above rule is  feature gates   Feature gates are key value pairs that allow for users to enable disable experimental features   Feature gates are intended to cover the development life cycle of a feature   they are not intended to be long term APIs  As such  they are expected to be deprecated and removed after a feature becomes GA or is dropped   As a feature moves through the stages  the associated feature gate evolves  The feature life cycle matched to its corresponding feature gate is     Alpha  the feature gate is disabled by default and can be enabled by the user    Beta  the feature gate is enabled by default and can be disabled by the user    GA  the feature gate is deprecated  see   Deprecation    deprecation   and becomes   non operational    GA  deprecation window complete  the feature gate is removed and calls to it are   no longer accepted       Deprecation  Features can be removed at any point in the life cycle prior to GA  When features are removed prior to GA  their associated feature gates are also deprecated   When an invocation tries to disable a non operational feature gate  the call fails in order to avoid unsupported scenarios that might otherwise run silently   In some cases  removing pre GA features requires considerable time  Feature gates can remain operational until their associated feature is fully removed  at which point the feature gate itself can be deprecated   When removing a feature gate for a GA feature also requires considerable time  calls to feature gates may remain operational if the feature gate has no effect on the feature  and if the feature gate causes no errors   Features intended to be disabled by users should include a mechanism for disabling the feature in the associated feature gate   Versioning for feature gates is different from the previously discussed components  therefore the rules for deprecation are as follows     Rule  9  Feature gates must be deprecated when the corresponding feature they control transitions a lifecycle stage as follows  Feature gates must function for no less than         Beta feature to GA  6 months or 2 releases  whichever is longer        Beta feature to EOL  3 months or 1 release  whichever is longer        Alpha feature to EOL  0 releases      Rule  10  Deprecated feature gates must respond with a warning when used  When a feature gate is deprecated it must be documented in both in the release notes and the corresponding CLI help  Both warnings and documentation must indicate whether a feature gate is non operational        Deprecating a metric  Each component of the Kubernetes control plane exposes metrics  usually the   metrics  endpoint   which are typically ingested by cluster administrators  Not all metrics are the same  some metrics are commonly used as SLIs or used to determine SLOs  these tend to have greater import  Other metrics are more experimental in nature or are used primarily in the Kubernetes development process   Accordingly  metrics fall under three stability classes   ALPHA    BETA   STABLE    this impacts removal of a metric during a Kubernetes release  These classes are determined by the perceived importance of the metric  The rules for deprecating and removing a metric are as follows     Rule  11a  Metrics  for the corresponding stability class  must function for no less than         STABLE  4 releases or 12 months  whichever is longer        BETA  2 releases or 8 months  whichever is longer        ALPHA  0 releases      Rule  11b  Metrics  after their  announced deprecation   must function for no less than         STABLE  3 releases or 9 months  whichever is longer        BETA  1 releases or 4 months  whichever is longer        ALPHA  0 releases    Deprecated metrics will have their description text prefixed with a deprecation notice string   Deprecated from x y   and a warning log will be emitted during metric registration  Like their stable undeprecated counterparts  deprecated metrics will be automatically registered to the metrics endpoint and therefore visible   On a subsequent release  when the metric s  deprecatedVersion  is equal to  current kubernetes version   3    a deprecated metric will become a  hidden  metric     Unlike    their deprecated counterparts  hidden metrics will  no longer  be automatically registered to the metrics endpoint  hence hidden   However  they can be explicitly enabled through a command line flag on the binary     show hidden metrics for version     This provides cluster admins an escape hatch to properly migrate off of a deprecated metric  if they were not able to react to the earlier deprecation warnings  Hidden metrics should be deleted after one release      Exceptions  No policy can cover every possible situation  This policy is a living document  and will evolve over time  In practice  there will be situations that do not fit neatly into this policy  or for which this policy becomes a serious impediment  Such situations should be discussed with SIGs and project leaders to find the best solutions for those specific cases  always bearing in mind that Kubernetes is committed to being a stable system that  as much as possible  never breaks users  Exceptions will always be announced in all relevant release notes


kubernetes reference liggitt weight 45 reviewers title Deprecated API Migration Guide contenttype reference thockin lavalamp smarterclayton

Answer:
---
reviewers:
- liggitt
- lavalamp
- thockin
- smarterclayton
title: "Deprecated API Migration Guide"
weight: 45
content_type: reference
---

<!-- overview -->

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.

<!-- body -->

## Removed APIs by release

### v1.32

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

#### Flow control resources {#flowcontrol-resources-v132}

The **flowcontrol.apiserver.k8s.io/v1beta3** API version of FlowSchema and PriorityLevelConfiguration will no longer be served in v1.32.

* Migrate manifests and API clients to use the **flowcontrol.apiserver.k8s.io/v1** API version, available since v1.29.
* All existing persisted objects are accessible via the new API
* Notable changes in **flowcontrol.apiserver.k8s.io/v1**:
  * The PriorityLevelConfiguration `spec.limited.nominalConcurrencyShares` field only defaults to 30 when unspecified, and an explicit value of 0 is not changed to 30.

### v1.29

The **v1.29** release stopped serving the following deprecated API versions:

#### Flow control resources {#flowcontrol-resources-v129}

The **flowcontrol.apiserver.k8s.io/v1beta2** API version of FlowSchema and PriorityLevelConfiguration is no longer served as of v1.29.

* Migrate manifests and API clients to use the **flowcontrol.apiserver.k8s.io/v1** API version, available since v1.29, or 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/v1**:
  * The PriorityLevelConfiguration `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.
* Notable changes in **flowcontrol.apiserver.k8s.io/v1beta3**:
  * The PriorityLevelConfiguration `spec.limited.assuredConcurrencyShares` field is renamed to `spec.limited.nominalConcurrencyShares`

### v1.27

The **v1.27** release stopped serving the following deprecated API versions:

#### CSIStorageCapacity {#csistoragecapacity-v127}

The **storage.k8s.io/v1beta1** API version of CSIStorageCapacity is no longer served as of 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 {#flowcontrol-resources-v126}

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/v1beta2** API version.
* All existing persisted objects are accessible via the new API
* No notable changes

#### HorizontalPodAutoscaler {#horizontalpodautoscaler-v126}

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
* Notable changes:
  * `targetAverageUtilization` is replaced with `target.averageUtilization` and `target.type: Utilization`. See [Autoscaling on multiple metrics and custom metrics](/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/#autoscaling-on-multiple-metrics-and-custom-metrics).
### v1.25

The **v1.25** release stopped serving the following deprecated API versions:

#### CronJob {#cronjob-v125}

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 {#endpointslice-v125}

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 deprecated `topology["kubernetes.io/hostname"]` field
  * use per Endpoint `zone` field instead of deprecated `topology["topology.kubernetes.io/zone"]` field
  * `topology` is replaced with the `deprecatedTopology` field which is not writable in v1

#### Event {#event-v125}

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 to `Normal` and `Warning`
  * `involvedObject` is renamed to `regarding`
  * `action`, `reason`, `reportingController`, 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 `reportingController` 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)

#### HorizontalPodAutoscaler {#horizontalpodautoscaler-v125}

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
* Notable changes:
  * `targetAverageUtilization` is replaced with `target.averageUtilization` and `target.type: Utilization`. See [Autoscaling on multiple metrics and custom metrics](/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/#autoscaling-on-multiple-metrics-and-custom-metrics).

#### PodDisruptionBudget {#poddisruptionbudget-v125}

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 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 {#psp-v125}

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](/docs/concepts/security/pod-security-admission/)
or a [3rd party admission webhook](/docs/reference/access-authn-authz/extensible-admission-controllers/).
For a migration guide, see [Migrate from PodSecurityPolicy to the Built-In PodSecurity Admission Controller](/docs/tasks/configure-pod-container/migrate-from-psp/).
For more information on the deprecation, see [PodSecurityPolicy Deprecation: Past, Present, and Future](/blog/2021/04/06/podsecuritypolicy-deprecation-past-present-and-future/).

#### RuntimeClass {#runtimeclass-v125}

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 {#webhook-resources-v122}

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 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 {#customresourcedefinition-v122}

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 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](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-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](https://github.com/kubernetes/kubernetes/issues/66531))

#### APIService {#apiservice-v122}

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 {#tokenreview-v122}

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 {#subjectaccessreview-resources-v122}

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 to `spec.groups` in v1 (fixes [#32709](https://github.com/kubernetes/kubernetes/issues/32709))

#### CertificateSigningRequest {#certificatesigningrequest-v122}

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](/docs/reference/access-authn-authz/certificate-signing-requests/#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 {#lease-v122}

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 {#ingress-v122}

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 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 {#ingressclass-v122}

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 {#rbac-resources-v122}

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 {#priorityclass-v122}

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 {#storage-resources-v122}

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 {#networkpolicy-v116}

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 {#daemonset-v116}

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 {#deployment-v116}

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 {#statefulset-v116}

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 {#replicaset-v116}

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 {#psp-v116}

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+](/blog/2020/09/03/warnings/#deprecation-warnings)
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](/docs/reference/kubernetes-api/).

  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](https://github.com/kubernetes/kubectl/issues/725)
  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](/docs/tasks/tools/install-kubectl-linux/#install-kubectl-convert-plugin),
  [macOS](/docs/tasks/tools/install-kubectl-macos/#install-kubectl-convert-plugin), or
  [Windows](/docs/tasks/tools/install-kubectl-windows/#install-kubectl-convert-plugin).

reviewers    liggitt   lavalamp   thockin   smarterclayton title   Deprecated API Migration Guide  weight  45 content type  reference           overview      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        body         Removed APIs by release      v1 32  The   v1 32   release will stop serving the following deprecated API versions        Flow control resources   flowcontrol resources v132   The   flowcontrol apiserver k8s io v1beta3   API version of FlowSchema and PriorityLevelConfiguration will no longer be served in v1 32     Migrate manifests and API clients to use the   flowcontrol apiserver k8s io v1   API version  available since v1 29    All existing persisted objects are accessible via the new API   Notable changes in   flowcontrol apiserver k8s io v1        The PriorityLevelConfiguration  spec limited nominalConcurrencyShares  field only defaults to 30 when unspecified  and an explicit value of 0 is not changed to 30       v1 29  The   v1 29   release stopped serving the following deprecated API versions        Flow control resources   flowcontrol resources v129   The   flowcontrol apiserver k8s io v1beta2   API version of FlowSchema and PriorityLevelConfiguration is no longer served as of v1 29     Migrate manifests and API clients to use the   flowcontrol apiserver k8s io v1   API version  available since v1 29  or 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 v1        The PriorityLevelConfiguration  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    Notable changes in   flowcontrol apiserver k8s io v1beta3        The PriorityLevelConfiguration  spec limited assuredConcurrencyShares  field is renamed to  spec limited nominalConcurrencyShares       v1 27  The   v1 27   release stopped serving the following deprecated API versions        CSIStorageCapacity   csistoragecapacity v127   The   storage k8s io v1beta1   API version of CSIStorageCapacity is no longer served as of 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   flowcontrol resources v126   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 v1beta2   API version    All existing persisted objects are accessible via the new API   No notable changes       HorizontalPodAutoscaler   horizontalpodautoscaler v126   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   Notable changes       targetAverageUtilization  is replaced with  target averageUtilization  and  target type  Utilization   See  Autoscaling on multiple metrics and custom metrics   docs tasks run application horizontal pod autoscale walkthrough  autoscaling on multiple metrics and custom metrics       v1 25  The   v1 25   release stopped serving the following deprecated API versions        CronJob   cronjob v125   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   endpointslice v125   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 deprecated  topology  kubernetes io hostname    field     use per Endpoint  zone  field instead of deprecated  topology  topology kubernetes io zone    field      topology  is replaced with the  deprecatedTopology  field which is not writable in v1       Event   event v125   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 to  Normal  and  Warning       involvedObject  is renamed to  regarding       action    reason    reportingController   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  reportingController  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        HorizontalPodAutoscaler   horizontalpodautoscaler v125   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   Notable changes       targetAverageUtilization  is replaced with  target averageUtilization  and  target type  Utilization   See  Autoscaling on multiple metrics and custom metrics   docs tasks run application horizontal pod autoscale walkthrough  autoscaling on multiple metrics and custom metrics         PodDisruptionBudget   poddisruptionbudget v125   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 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   psp v125   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   docs concepts security pod security admission   or a  3rd party admission webhook   docs reference access authn authz extensible admission controllers    For a migration guide  see  Migrate from PodSecurityPolicy to the Built In PodSecurity Admission Controller   docs tasks configure pod container migrate from psp    For more information on the deprecation  see  PodSecurityPolicy Deprecation  Past  Present  and Future   blog 2021 04 06 podsecuritypolicy deprecation past present and future          RuntimeClass   runtimeclass v125   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   webhook resources v122   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 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   customresourcedefinition v122   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 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   docs tasks extend kubernetes custom resources custom resource definitions  specifying 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  https   github com kubernetes kubernetes issues 66531         APIService   apiservice v122   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   tokenreview v122   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   subjectaccessreview resources v122   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 to  spec groups  in v1  fixes   32709  https   github com kubernetes kubernetes issues 32709         CertificateSigningRequest   certificatesigningrequest v122   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   docs reference access authn authz certificate signing requests  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   lease v122   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   ingress v122   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 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   ingressclass v122   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   rbac resources v122   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   priorityclass v122   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   storage resources v122   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   networkpolicy v116   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   daemonset v116   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   deployment v116   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   statefulset v116   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   replicaset v116   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   psp v116   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    blog 2020 09 03 warnings  deprecation warnings  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   docs reference kubernetes api            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  https   github com kubernetes kubectl issues 725    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   docs tasks tools install kubectl linux  install kubectl convert plugin      macOS   docs tasks tools install kubectl macos  install kubectl convert plugin   or    Windows   docs tasks tools install kubectl windows  install kubectl convert plugin