Streaming lists documentation

Author: wojtek-t

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

@@ -199,6 +199,7 @@ For a reference to old feature gates that are removed, please refer to
 | `UserNamespacesStatelessPodsSupport` | `false` | Alpha | 1.25 | |
 | `ValidatingAdmissionPolicy` | `false` | Alpha | 1.26 | |
 | `VolumeCapacityPriority` | `false` | Alpha | 1.21 | - |
+| `WatchList` | false | Alpha | 1.27 | - |
 | `WinDSR` | `false` | Alpha | 1.14 | |
 | `WinOverlay` | `false` | Alpha | 1.14 | 1.19 |
 | `WinOverlay` | `true` | Beta | 1.20 | |
@@ -748,6 +749,7 @@ Each feature gate is designed for enabling/disabling a specific feature:
 - `VolumeCapacityPriority`: Enable support for prioritizing nodes in different
   topologies based on available PV capacity.
 - `WatchBookmark`: Enable support for watch bookmark events.
+- `WatchList` : Enable support for [streaming initial state of objects in watch requests](/docs/reference/using-api/api-concepts/#streaming-lists).
 - `WinDSR`: Allows kube-proxy to create DSR loadbalancers for Windows.
 - `WinOverlay`: Allows kube-proxy to run in overlay mode for Windows.
 - `WindowsHostNetwork`: Enables support for joining Windows containers to a hosts' network namespace.

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

@@ -226,6 +226,58 @@ As a client, you can request `BOOKMARK` events by setting the
 assume bookmarks are returned at any specific interval, nor can clients assume that
 the API server will send any `BOOKMARK` event even when requested.
 
+## Streaming lists
+
+{{< feature-state for_k8s_version="v1.27" state="alpha" >}}
+
+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 - including version {{< skew currentVersion >}} - provides alpha support
+for 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
+in a watch request. If set, the server starts the watch stream with synthetic init
+events to build the whole state of all existing objects followed by a `BOOKMARK` event
+(if requested via `allowWatchBookmarks=true` option) containing a resource version after
+which the server continue streaming events.
+
+When `sendInitialEvents=true` in the query string is set, we require `ResourceVersionMatch` to be set
+to `NotOlderThan`. If the provided `ResourceVersion` is unset, this is interpreted
+as a request for _consistent read_; the bookmark event is sent when the state is synced at
+least to the moment of a consistent read from when the request started to be
+processed. If you specify `resourceVersion` (in the query string), the bookmark event is sent when
+the state is synced at least to the provided resource version.
+
+As an example imagine a case when the current resource version is 10245 and there
+exist two pods: `foo` and `bar`. Then sending the following request could result
+in the following sequence of events:
+
+```console
+GET /api/v1/namespaces/test/pods?watch=1&sendInitialEvents=true&allowWatchBookmarks=true&resourceVersion=&resourceVersionMatch=NotOlderThan
+---
+200 OK
+Transfer-Encoding: chunked
+Content-Type: application/json
+
+{
+  "type": "ADDED",
+  "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "8467", "name": "foo"}, ...}
+}
+{
+  "type": "ADDED",
+  "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "5726", "name": "bar"}, ...}
+}
+{
+  "type": "BOOKMARK",
+  "object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "10245"} }
+}
+...
+<followed by regular watch stream starting from resourceVersion="10245">
+```
+
 ## Retrieving large results sets in chunks
 
 {{< feature-state for_k8s_version="v1.9" state="beta" >}}