diff --git a/content/en/docs/concepts/overview/kubernetes-api.md b/content/en/docs/concepts/overview/kubernetes-api.md index 6badc01ea0..5dc5c25bdc 100644 --- a/content/en/docs/concepts/overview/kubernetes-api.md +++ b/content/en/docs/concepts/overview/kubernetes-api.md @@ -181,8 +181,9 @@ through multiple API versions. For example, suppose there are two API versions, `v1` and `v1beta1`, for the same resource. If you originally created an object using the `v1beta1` version of its -API, you can later read, update, or delete that object -using either the `v1beta1` or the `v1` API version. +API, you can later read, update, or delete that object using either the `v1beta1` +or the `v1` API version, until the `v1beta1` version is deprecated and removed. +At that point you can continue accessing and modifying the object using the `v1` API. ### API changes @@ -197,14 +198,19 @@ Elimination of resources or fields requires following the Kubernetes makes a strong commitment to maintain compatibility for official Kubernetes APIs once they reach general availability (GA), typically at API version `v1`. Additionally, -Kubernetes keeps compatibility even for _beta_ API versions wherever feasible: -if you adopt a beta API you can continue to interact with your cluster using that API, -even after the feature goes stable. +Kubernetes maintains compatibility with data persisted via _beta_ API versions of official Kubernetes APIs, +and ensures that data can be converted and accessed via GA API versions when the feature goes stable. + +If you adopt a beta API version, you will need to transition to a subsequent beta or stable API version +once the API graduates. The best time to do this is while the beta API is in its deprecation period, +since objects are simultaneously accessible via both API versions. Once the beta API completes its +deprecation period and is no longer served, the replacement API version must be used. {{< note >}} Although Kubernetes also aims to maintain compatibility for _alpha_ APIs versions, in some circumstances this is not possible. If you use any alpha API versions, check the release notes -for Kubernetes when upgrading your cluster, in case the API did change. +for Kubernetes when upgrading your cluster, in case the API did change in incompatible +ways that require deleting all existing alpha objects prior to upgrade. {{< /note >}} Refer to [API versions reference](/docs/reference/using-api/#api-versioning) diff --git a/content/en/docs/reference/using-api/_index.md b/content/en/docs/reference/using-api/_index.md index 182bbd4fe6..5f0e21871b 100644 --- a/content/en/docs/reference/using-api/_index.md +++ b/content/en/docs/reference/using-api/_index.md @@ -50,27 +50,31 @@ Here's a summary of each level: - Alpha: - The version names contain `alpha` (for example, `v1alpha1`). - - The software may contain bugs. Enabling a feature may expose bugs. A - feature may be disabled by default. - - The support for a feature may be dropped at any time without notice. + - Built-in alpha API versions are disabled by default and must be explicitly enabled in the `kube-apiserver` configuration to be used. + - The software may contain bugs. Enabling a feature may expose bugs. + - Support for an alpha API may be dropped at any time without notice. - The API may change in incompatible ways in a later software release without notice. - The software is recommended for use only in short-lived testing clusters, due to increased risk of bugs and lack of long-term support. - Beta: - The version names contain `beta` (for example, `v2beta3`). + - Built-in beta API versions are disabled by default and must be explicitly enabled in the `kube-apiserver` configuration to be used + (**except** for beta versions of APIs introduced prior to Kubernetes 1.22, which were enabled by default). + - Built-in beta API versions have a maximum lifetime of 9 months or 3 minor releases (whichever is longer) from introduction + to deprecation, and 9 months or 3 minor releases (whichever is longer) from deprecation to removal. - The software is well tested. Enabling a feature is considered safe. - Features are enabled by default. - The support for a feature will not be dropped, though the details may change. - The schema and/or semantics of objects may change in incompatible ways in - a subsequent beta or stable release. When this happens, migration - instructions are provided. Schema changes may require deleting, editing, and - re-creating API objects. The editing process may not be straightforward. + a subsequent beta or stable API version. When this happens, migration + instructions are provided. Adapting to a subsequent beta or stable API version + may require editing or re-creating API objects, and may not be straightforward. The migration may require downtime for applications that rely on the feature. - The software is not recommended for production uses. Subsequent releases - may introduce incompatible changes. If you have multiple clusters which - can be upgraded independently, you may be able to relax this restriction. + may introduce incompatible changes. Use of beta API versions is + required to transition to subsequent beta or stable API versions + once the beta API version is deprecated and no longer served. {{< note >}} Please try beta features and provide feedback. After the features exit beta, it @@ -79,7 +83,8 @@ Here's a summary of each level: - Stable: - The version name is `vX` where `X` is an integer. - - The stable versions of features appear in released software for many subsequent versions. + - Stable API versions remain available for all future releases within a Kubernetes major version, + and there are no current plans for a major version revision of Kubernetes that removes stable APIs. ## API groups diff --git a/content/en/docs/reference/using-api/deprecation-policy.md b/content/en/docs/reference/using-api/deprecation-policy.md index 9612e1df39..9bf80456e4 100644 --- a/content/en/docs/reference/using-api/deprecation-policy.md +++ b/content/en/docs/reference/using-api/deprecation-policy.md @@ -79,13 +79,15 @@ might have to add an equivalent field or represent it as an annotation. * 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** +**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 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** + * 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/). +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 Kubernetes that removes GA APIs.