diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates.md b/content/en/docs/reference/command-line-tools-reference/feature-gates.md index 626cc6931f605..2305964556789 100644 --- a/content/en/docs/reference/command-line-tools-reference/feature-gates.md +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates.md @@ -205,6 +205,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 | | @@ -729,6 +730,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. diff --git a/content/en/docs/reference/using-api/api-concepts.md b/content/en/docs/reference/using-api/api-concepts.md index 3c7c0fa8ccbb5..f960b70fb03e3 100644 --- a/content/en/docs/reference/using-api/api-concepts.md +++ b/content/en/docs/reference/using-api/api-concepts.md @@ -226,6 +226,63 @@ 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 API 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). The bookmark event includes the resource for that +watch bookmark. After sending the bookmark event, the API server continues as for any other **watch** +request. + +When you set `sendInitialEvents=true` in the query string, Kubernetes also requires that you set +`resourceVersionMatch` to `NotOlderThan` value. +If you provided `resourceVersion` in the query string without providing a value or don't provide +it at all, 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. + +### Example {#example-streaming-lists} + +An example: you want to watch a collection of Pods. For that collection, the current resource version +is 10245 and there are two pods: `foo` and `bar`. Then sending the following request (explicitly requesting +_consistent read_ by setting empty resource version using `resourceVersion=`) 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"} } +} +... + +``` + ## Retrieving large results sets in chunks {{< feature-state for_k8s_version="v1.9" state="beta" >}}