Kubernetes Deprecation Policy [page]deterministic
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.
> Note: 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.
> Note: There are no current plans for a major version revision of K …(trimmed)