Merge pull request #48512 from p0lyn0mial/doc-update-watch-list-1-32

Document KEP 3157 (watch-list) for milestone 1.32

content/en/docs/reference/command-line-tools-reference/feature-gates/watch-list-client.md

@@ -0,0 +1,17 @@
+---
+title: WatchListClient
+content_type: feature_gate
+_build:
+  list: never
+  render: false
+
+stages:
+  - stage: beta
+    defaultValue: false
+    fromVersion: "1.30"
+---
+Allows an API client to request a stream of data rather than fetching a full list. 
+This functionality is available in `client-go` and requires the 
+[WatchList](/docs/reference/command-line-tools-reference/feature-gates/) 
+feature to be enabled on the server. 
+If the `WatchList` is not supported on the server, the client will seamlessly fall back to a standard list request.

content/en/docs/reference/command-line-tools-reference/feature-gates/watch-list.md

@@ -9,5 +9,9 @@ stages:
   - stage: alpha 
     defaultValue: false
     fromVersion: "1.27"
+    toVersion: "1.31"
+  - stage: beta
+    defaultValue: true
+    fromVersion: "1.32"
 ---
 Enable support for [streaming initial state of objects in watch requests](/docs/reference/using-api/api-concepts/#streaming-lists).

content/en/docs/reference/using-api/api-concepts.md

@@ -443,13 +443,11 @@ the API server will send any `BOOKMARK` event even when requested.
 
 On large clusters, retrieving the collection of some resource types may result in
 a significant increase of resource usage (primarily RAM) on the control plane.
-In order to alleviate its impact and simplify the user experience of the **list** + **watch**
-pattern, Kubernetes v1.27 introduces as an alpha feature the support
-for requesting the initial state (previously requested via the **list** request) as part of
-the **watch** request.
+To alleviate the impact and simplify the user experience of the **list** + **watch**
+pattern, Kubernetes v1.32 promotes to beta the feature that allows requesting the initial state 
+(previously requested via the **list** request) as part of the **watch** request.
 
-Provided that the `WatchList` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
-is enabled, this can be achieved by specifying `sendInitialEvents=true` as query string parameter
+On the client-side the initial state can be requested by specifying `sendInitialEvents=true` as query string parameter
 in a **watch** request. If set, the API server starts the watch stream with synthetic init
 events (of type `ADDED`) to build the whole state of all existing objects followed by a
 [`BOOKMARK` event](/docs/reference/using-api/api-concepts/#watch-bookmarks)