Kubernetes Deprecation Policy
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 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.
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: minimum 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 must be supported for 9 months or 3 releases (whichever is longer) after deprecation
- 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.
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 |
|
| X+2 | v1beta1 | v1beta1 |
|
| X+3 | v1beta2, v1beta1 (deprecated) | v1beta1 |
|
| X+4 | v1beta2, v1beta1 (deprecated) | v1beta2 | |
| X+5 | v1, v1beta1 (deprecated), v1beta2 (deprecated) | v1beta2 |
|
| X+6 | v1, v1beta2 (deprecated) | v1 |
|
| X+7 | v1, v1beta2 (deprecated) | v1 | |
| X+8 | v2alpha1, v1 | v1 |
|
| X+9 | v2alpha2, v1 | v1 |
|
| X+10 | v2beta1, v1 | v1 |
|
| X+11 | v2beta2, v2beta1 (deprecated), v1 | v1 |
|
| X+12 | v2, v2beta2 (deprecated), v2beta1 (deprecated), v1 (deprecated) | v1 |
|
| X+13 | v2, v2beta1 (deprecated), v2beta2 (deprecated), v1 (deprecated) | v2 | |
| X+14 | v2, v2beta2 (deprecated), v1 (deprecated) | v2 |
|
| X+15 | v2, v1 (deprecated) | v2 |
|
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
Starting in Kubernetes v1.19, making an API request to a deprecated REST API endpoint: Adds a Sets an 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. 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 configs are versioned and managed similar to REST resources. Over time, Kubernetes will introduce more fine-grained API versions, at which
point these rules will be adjusted as needed. 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: Rule #5b: CLI elements of admin-facing components (e.g. kubelet) must function
after their announced deprecation for no less than: Rule #6: Deprecated CLI elements must emit warnings (optionally disable)
when used. 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. This does not imply that all changes to the system are governed by this policy.
This applies 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: 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 #8: 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: Rule #9: 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. Each component of the Kubernetes control-plane exposes metrics (usually the
Accordingly, metrics fall under two stability classes ( Rule #9a: Metrics, for the corresponding stability class, must function for no less than: Rule #9b: Metrics, after their announced deprecation, must function for no less than: 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 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.
"k8s.io/deprecated":"true" annotation to the audit event recorded for the request.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:apiserver_requested_deprecated_apis{removed_release="1.22"} * on(group,version,resource,subresource) group_right() apiserver_request_total
Fields of REST resources
Enumerated or constant values
Component config structures
Future work
Deprecating a flag or CLI
Deprecating a feature or behavior
Deprecation
Deprecating a metric
/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.ALPHA and 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:
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