From 3794a9a601f71a38768c476074b1390e6c992130 Mon Sep 17 00:00:00 2001 From: Lukasz Szaszkiewicz Date: Wed, 23 Oct 2024 13:27:09 +0200 Subject: [PATCH 1/2] Update documentation for the WatchList feature --- .../feature-gates/watch-list.md | 4 ++++ content/en/docs/reference/using-api/api-concepts.md | 10 ++++------ 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates/watch-list.md b/content/en/docs/reference/command-line-tools-reference/feature-gates/watch-list.md index cd258d1afd54a..1595cd251dce2 100644 --- a/content/en/docs/reference/command-line-tools-reference/feature-gates/watch-list.md +++ b/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). diff --git a/content/en/docs/reference/using-api/api-concepts.md b/content/en/docs/reference/using-api/api-concepts.md index fca124e1cf858..a583951429328 100644 --- a/content/en/docs/reference/using-api/api-concepts.md +++ b/content/en/docs/reference/using-api/api-concepts.md @@ -400,13 +400,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) From 45ef57279f1802d6217938ae25f5319299fa3399 Mon Sep 17 00:00:00 2001 From: Lukasz Szaszkiewicz Date: Tue, 12 Nov 2024 13:51:17 +0100 Subject: [PATCH 2/2] Provide documentation for the WatchListClient feature --- .../feature-gates/watch-list-client.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 content/en/docs/reference/command-line-tools-reference/feature-gates/watch-list-client.md diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates/watch-list-client.md b/content/en/docs/reference/command-line-tools-reference/feature-gates/watch-list-client.md new file mode 100644 index 0000000000000..826e19712c81f --- /dev/null +++ b/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.