From 6058540f3d0edc405a1f1b8a96bd82ceca99c240 Mon Sep 17 00:00:00 2001 From: Lukasz Szaszkiewicz Date: Fri, 1 Sep 2023 10:48:36 +0200 Subject: [PATCH] storage: document ProgressNotify from storage.ListOptions At first glance, it seems that the fields storage.ListOptions.ProgressNotify and storage.ListOptions.Predicate.AllowWatchBookmarks are the same. Unfortunately, this is not the case. This PR documents the differences and motivations for why these fields are actually distinct. --- .../src/k8s.io/apiserver/pkg/storage/interfaces.go | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/staging/src/k8s.io/apiserver/pkg/storage/interfaces.go b/staging/src/k8s.io/apiserver/pkg/storage/interfaces.go index 76123fde864..5489660809d 100644 --- a/staging/src/k8s.io/apiserver/pkg/storage/interfaces.go +++ b/staging/src/k8s.io/apiserver/pkg/storage/interfaces.go @@ -282,6 +282,19 @@ type ListOptions struct { Recursive bool // ProgressNotify determines whether storage-originated bookmark (progress notify) events should // be delivered to the users. The option is ignored for non-watch requests. + // + // Firstly, note that this field is different from the Predicate.AllowWatchBookmarks field. + // Secondly, this field is intended for internal clients only such as the watch cache. + // + // This means that external clients do not have the ability to set this field directly. + // For example by setting the allowWatchBookmarks query parameter. + // + // The motivation for this approach is the fact that the frequency + // of bookmark events from a storage like etcd might be very high. + // As the number of watch requests increases, the server load would also increase. + // + // Furthermore, the server is not obligated to provide bookmark events at all, + // as described in https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/956-watch-bookmark#proposal ProgressNotify bool // SendInitialEvents, when set together with Watch option, // begin the watch stream with synthetic init events to build the