Skip to content

Commit 2ec502a

Browse files
committed
Fix some beta API documentation now that they are off by default
1 parent 6951126 commit 2ec502a

File tree

1 file changed

+17
-5
lines changed

1 file changed

+17
-5
lines changed

contributors/devel/sig-architecture/api_changes.md

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -922,7 +922,10 @@ doing!
922922
Check out the [E2E docs](../sig-testing/e2e-tests.md) for detailed information about how to
923923
write end-to-end tests for your feature.
924924
Make sure the E2E tests are running in the default presubmits for a feature that
925-
is being promoted to Beta (enabled by default).
925+
is being promoted to Beta (disabled by default, make sure to enable with flag).
926+
This behavior changed with Kubernetes v1.24 (see the
927+
[KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-architecture/3136-beta-apis-off-by-default/README.md)
928+
for more details) and only applies to new beta API introduced after v1.24.
926929

927930
## Examples and docs
928931

@@ -985,7 +988,11 @@ complexity of upgradeability and lack of long-term support and lack of
985988
upgradability.
986989
- Beta level:
987990
- Object Versioning: API version name contains `beta` (e.g. `v2beta3`)
988-
- Availability: in official Kubernetes releases, and enabled by default
991+
- Availability: in official Kubernetes releases; feature is disabled by default,
992+
but may be enabled by flag. This applies to new beta API introduced after v1.24
993+
(see [KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-architecture/3136-beta-apis-off-by-default/README.md)
994+
for more deatils). Beta APIs which were introduced before v1.24 are enabled by
995+
default.
989996
- Audience: users interested in providing feedback on features
990997
- Completeness: all API operations, CLI commands, and UI support should be
991998
implemented; end-to-end tests complete; the API has had a thorough API review
@@ -1191,7 +1198,7 @@ provides some details
11911198

11921199
In future Kubernetes versions:
11931200

1194-
* if the feature progresses to beta or stable status, the feature gate can be removed or be enabled by default.
1201+
* if the feature progresses to stable status, the feature gate can be removed or be enabled by default.
11951202
* if the schema of the alpha field must change in an incompatible way, a new field name must be used.
11961203
* 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:
11971204

@@ -1253,7 +1260,12 @@ This ensures a cluster with multiple servers at skewed releases (which happens d
12531260
will not allow data to be persisted which the previous release of the API server would choke on.
12541261

12551262
Typically, a feature gate is used to do this rollout, starting in alpha and disabled by default in release 1,
1256-
and graduating to beta and enabled by default in release 2.
1263+
and graduating to stable and enabled by default in release 2.
1264+
With beta as an intermediate step, release 3 (stable) would enable the feature gate by default.
1265+
The behavior changed with Kubernetes v1.24
1266+
(for details see the [KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-architecture/3136-beta-apis-off-by-default/README.md)).
1267+
Beta APIs introduced before v1.24 will be enabled by default.
1268+
Beta API introduced after v1.24 will be disabled by default.
12571269

12581270
1. Add a feature gate to the API server to control enablement of the new enum value (and associated function):
12591271

@@ -1342,7 +1354,7 @@ The recommended place to do this is in the REST storage strategy's Validate/Vali
13421354
}
13431355
```
13441356

1345-
5. After at least one release, the feature can be promoted to beta or GA and enabled by default.
1357+
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.
13461358

13471359
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):
13481360

0 commit comments

Comments
 (0)