Comments

keps/sig-api-machinery/3352-aggregated-discovery/README.md

@@ -181,7 +181,7 @@ to minimize diff churn on updates.
 -->
 
 
-The operations that a Kubernetes API server support is dictated
+The operations that a Kubernetes API server supports are reported
 through a collection of small documents partitioned by group-version.
 All clients of Kubernetes APIs must send a request to every
 group-version in order to "discover" the available APIs. This causes a
@@ -207,18 +207,17 @@ typically queried to then build the requests to correct APIs.
 Unfortunately, the “Discovery” API is made of lots of small objects
 that need to be queried individually, causing possibly a lot of delay
 due to the latency of each individual request (up to 80 requests, with
-most objects being less than 1,024 bytes). The more complex the APIs
+most objects being less than 1,024 bytes). The more numerous the APIs
 provided by the Kubernetes cluster, the more requests need to be
 performed.
 
 The most well known Kubernetes client that uses the discovery
 mechanism is `kubectl`, and more specifically the
 `CachedDiscoveryClient` in `client-go`. To mitigate some of this
-latency, kubectl has implemented a (10 minute timer) 6 hours(!) timer
-during which the discovery API is not refreshed. The drawback of this
-approach is that the freshness of the cache is doubtful and the entire
-discovery API needs to be refreshed after 6 hours, even if it hasn’t
-expired.
+latency, kubectl has implemented a 6 hour timer during which the
+discovery API is not refreshed. The drawback of this approach is that
+the freshness of the cache is doubtful and the entire discovery API
+needs to be refreshed after 6 hours, even if it hasn’t expired.
 
 This not only impacts kubectl, but all clients of kubernetes. We can
 do better.
@@ -236,10 +235,9 @@ How will we know that this has succeeded? -->
 <!-- What is out of scope for this KEP? Listing non-goals helps to
 focus discussion and make progress. -->
 
-- Since the current discovery separated by group-version is already
-  GA, removal of the endpoint will be difficult. This KEP will solely
-  focus on introducing the new aggregated endpoint and will not cover
-  deprecation.
+Since the current discovery separated by group-version is already GA,
+removal of the endpoint will not be attempted. This KEP will solely
+focus on introducing the new aggregated endpoint.
 
 ## Proposal
 
@@ -381,6 +379,9 @@ For the aggregation layer on the server, a new controller will be
 created to aggregate discovery for built-in types, apiextensions types
 (CRDs), and types from aggregated api servers.
 
+A post start hook will be added and the kube-apiserver health check should only pass if the discovery document is ready.
+
+
 ### Client
 
 The `client-go` interface will be modified to add a new method to
@@ -683,18 +684,18 @@ the next question. -->
 
 <!-- Pick one more of these and delete the rest. -->
 
-- [ ] Metrics
-  - Metric name:
-  - [Optional] Aggregation method:
-  - Components exposing the metric:
-- [ ] Other (treat as last resort)
-  - Details:
+- [x] Metrics
+  - Metric name: `aggregator_discovery_aggregation_duration`
+  - Components exposing the metric: `kube-server`
+  - This is a metric for exposing the time it took to aggregate all the
 
 ###### Are there any missing metrics that would be useful to have to improve observability of this feature?
 
 <!-- Describe the metrics themselves and the reasons why they weren't
 added (e.g., cost, implementation difficulties, etc.). -->
 
+Yes. A metric for the regeneration count of the discovery document. `aggregator_discovery_aggregation_count`
+
 ### Dependencies
 
 <!-- This section must be completed when targeting beta to a release.
@@ -856,4 +857,4 @@ cache control headers. Clients can then recognize if the names have
 changed or stayed the same, and re-use files that have kept the same
 name without downloading them again.
 
-For a comparison between Discovery Cache Busting and Aggregated Discovery, please refer to the [Google Doc](https://docs.google.com/document/d/1sdf8nz5iTi86ErQy9OVxvQh_0RWfeU3Vyu0nlA10LNM).
+Aggregated Discovery was selected because of the amount of requests that are saved both on startup and on changes involving multiple group versions. For a full comparison between Discovery Cache Busting and Aggregated Discovery, please refer to the [Google Doc](https://docs.google.com/document/d/1sdf8nz5iTi86ErQy9OVxvQh_0RWfeU3Vyu0nlA10LNM).