Fix some beta API documentation now that they are off by default

1 files changed, 17 insertions, 5 deletions

diff --git a/contributors/devel/sig-architecture/api_changes.md b/contributors/devel/sig-architecture/api_changes.md
index ccadaa2f..f16da644 100644
--- a/contributors/devel/sig-architecture/api_changes.md
+++ b/contributors/devel/sig-architecture/api_changes.md
@@ -922,7 +922,10 @@ doing!
 Check out the [E2E docs](../sig-testing/e2e-tests.md) for detailed information about how to
 write end-to-end tests for your feature.
 Make sure the E2E tests are running in the default presubmits for a feature that
-is being promoted to Beta (enabled by default).
+is being promoted to Beta (disabled by default, make sure to enable with flag).
+This behavior changed with Kubernetes v1.24 (see the 
+[KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-architecture/3136-beta-apis-off-by-default/README.md) 
+for more details) and only applies to new beta API introduced after v1.24.
 
 ## Examples and docs
 
@@ -985,7 +988,11 @@ complexity of upgradeability and lack of long-term support and lack of
 upgradability.
 - Beta level:
   - Object Versioning: API version name contains `beta` (e.g. `v2beta3`)
-  - Availability: in official Kubernetes releases, and enabled by default
+  - Availability: in official Kubernetes releases; feature is disabled by default, 
+but may be enabled by flag. This applies to new beta API introduced after v1.24 
+(see [KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-architecture/3136-beta-apis-off-by-default/README.md) 
+for more deatils). Beta APIs which were introduced before v1.24 are enabled by 
+default.
   - Audience: users interested in providing feedback on features
   - Completeness: all API operations, CLI commands, and UI support should be
 implemented; end-to-end tests complete; the API has had a thorough API review
@@ -1191,7 +1198,7 @@ provides some details
 
 In future Kubernetes versions:
 
-* if the feature progresses to beta or stable status, the feature gate can be removed or be enabled by default.
+* if the feature progresses to stable status, the feature gate can be removed or be enabled by default.
 * if the schema of the alpha field must change in an incompatible way, a new field name must be used.
 * if the feature is abandoned, or the field name is changed, the field should be removed from the go struct, with a tombstone comment ensuring the field name and protobuf tag are not reused:
 
@@ -1253,7 +1260,12 @@ This ensures a cluster with multiple servers at skewed releases (which happens d
 will not allow data to be persisted which the previous release of the API server would choke on.
 
 Typically, a feature gate is used to do this rollout, starting in alpha and disabled by default in release 1,
-and graduating to beta and enabled by default in release 2.
+and graduating to stable and enabled by default in release 2.
+With beta as an intermediate step, release 3 (stable) would enable the feature gate by default.
+The behavior changed with Kubernetes v1.24 
+(for details see the [KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-architecture/3136-beta-apis-off-by-default/README.md)).
+Beta APIs introduced before v1.24 will be enabled by default.
+Beta API introduced after v1.24 will be disabled by default.
 
 1. Add a feature gate to the API server to control enablement of the new enum value (and associated function):
 
@@ -1342,7 +1354,7 @@ The recommended place to do this is in the REST storage strategy's Validate/Vali
     }
     ```
 
-5. After at least one release, the feature can be promoted to beta or GA and enabled by default.
+5. After at least one release, the feature can be promoted to beta or GA. But it will only be enabled by default for GA.
 
     In [staging/src/k8s.io/apiserver/pkg/features/kube_features.go](https://git.k8s.io/kubernetes/staging/src/k8s.io/apiserver/pkg/features/kube_features.go):