Clarify API version stability and guidelines

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)

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
 

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.