Skip to content

Add feature gate WatchListClient for v1.30 #47261

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Add feature gate WatchListClient for v1.30 #47261

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions .../docs/reference/command-line-tools-reference/feature-gates/watch-list-client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
title: WatchListClient
Copy link
Contributor

@p0lyn0mial p0lyn0mial Jul 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The WatchListClient is defined for a client (the client-go library) and not for the server.

It enables the client to request a stream of data rather than an entire list. The streamed data is then transformed into a list response on the client side.

Another way to think about this feature is that it essentially replaces standard LIST calls with WATCH calls under the hood.
Individual list items are delivered via the WATCH call and transformed into a list response on the client.
This process is completely opaque to the client requesting a list.
For the client, it doesn’t matter whether the library issues a LIST or WATCH request/verb.
The client only cares about the result, which will be a list response.

Also, for the WatchListClient to work, the server must support API Streaming, which is controlled by a server-side WatchList feature flag. If the server doesn't support the API Streaming and the WatchListClient is enabled then the client falls back/issues to a standard LIST request.

Copy link
Contributor

@sftim sftim Jul 26, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will this feature gate be configurable on API clients such as: the kubelet, kube-controller-manager, the scheduler?

Copy link
Contributor Author

@tengqm tengqm Jul 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The WatchListClient is defined for a client (the client-go library) and not for the server.

So if I'm interacting with a Kubernetes cluster using pure RESTful API, and I'm developing
a client tool in Python or Rust, this feature gate doesn't matter at all. But ...
it is listed in the command line options for kube-apiserver, kube-controller-manager, kube-scheduler, kube-proxy and kubelet. Right?

Copy link
Contributor

@sftim sftim Jul 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume you can configure some of those components to enable or not enable this feature when acting as a client of the API server.

Copy link
Contributor

@p0lyn0mial p0lyn0mial Jul 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sftim 2 minutes ago
Well this feature gate be configurable on API clients such as: the kubelet, kube-controller-manager, the scheduler?

yes, kubernetes will expose the WatchListClient feature gate via command line options for some/all control plane components. Initially we were planning to enable the WatchListClient by default only for KCM.

Copy link
Contributor

@p0lyn0mial p0lyn0mial Jul 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So if I'm interacting with a Kubernetes cluster using pure RESTful API, and I'm developing
a client tool in Python or Rust, this feature gate doesn't matter at all

yes, that is correct, in that case, the WatchList feature gate on the server-side matters.

content_type: feature_gate
_build:
list: never
render: false

stages:
- stage: beta
defaultValue: false
fromVersion: "1.30"
---
This enables an API client (inlcuding some control plane components) to
request a stream of data rather than an entire list. The behavior change
is implemented in the client-go library and it is opaque to the client.
Comment on lines +13 to +15
Copy link
Contributor

@sftim sftim Jul 27, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo in “inlcuding“.

Revised suggestion:

Suggested change
This enables an API client (inlcuding some control plane components) to
request a stream of data rather than an entire list. The behavior change
is implemented in the client-go library and it is opaque to the client.
Enable selected control plane components to fetch collections using **watch** rather
than **list** requests, as an optimization.
If you enable this feature gate, you should also check that any custom authorization rules allow
kube-controller-manager and its service identities to perform **watch** requests, otherwise
you will not benefit from the improvement.
If you do not use custom authorization rules, you only need to enable the feature gate.

Copy link
Contributor Author

@tengqm tengqm Jul 28, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Em ... why we want to touch the authorization topic in this feature gate?

Copy link
Contributor

@sftim sftim Jul 28, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked and actually the control plane should be able to fall back to list, so no authz changes are needed. I edited the suggestion.

To enable this optimization, you need to enable `WatchList` feature on
the API server.