storage capacity: more review feedback

Author: pohly

keps/sig-storage/1472-storage-capacity-tracking/README.md

@@ -844,7 +844,8 @@ enhancement:
   the enablement)?**
   Yes.
 
-  When disabling support in the API server, the new object type
+  Registration of the `CSIStorageCapacity` type is controlled by the feature
+  gate, so when disabling support in the API server, the new object type
   will disappear together with the new flag in
   `CSIDriver`, which will then cause kube-scheduler to revert to
   provisioning without capacity information. However, the new objects
@@ -902,7 +903,8 @@ events that quote `node(s) did not have enough free storage` as reason
 when the cluster is not really running out of storage capacity.
 
 Another is a degradation in apiserver metrics (increased CPU or memory
-consumption, increased latency).
+consumption, increased latency), specifically
+[`apiserver_request_duration_seconds`](https://github.com/kubernetes/kubernetes/blob/645c40fcf6f1fca133a00c8186674bcbcecc4b8e/staging/src/k8s.io/apiserver/pkg/endpoints/metrics/metrics.go#L98).
 
 * **Were upgrade and rollback tested? Was upgrade->downgrade->upgrade path tested?**
 
@@ -917,10 +919,18 @@ No.
 
 * **How can an operator determine if the feature is in use by workloads?**
 
-The feature is used if all of the following points apply:
-- `CSIDriver.spec.storageCapacity` is true for a CSI driver.
-- There are storage classes for that driver.
-- Volumes are using those storage classes.
+The feature itself is not used by workloads. It is used when
+scheduling workloads onto nodes, but not while those run.
+
+That a CSI driver provides storage capacity information can seen in the
+following metric data that will be provided by external-provisioner instances:
+- total number of `CSIStorageCapacity` objects that the external-provisioner
+  is currently meant to manage for the driver
+- actual number of such objects that currently exist
+- work queue length for creating, updating or deleting objects
+
+The CSI driver name will be used as label. When using distributed
+provisioning, the node name will be used as additional label.
 
 * **What are the SLIs (Service Level Indicators) an operator can use to
   determine the health of the service?**
@@ -937,12 +947,6 @@ calls will be recorded with their non-OK status code as value.
 
 * **What are the reasonable SLOs (Service Level Objectives) for the above SLIs?**
 
-This depends on the workload and CSI driver. A very low rate of
-provisioned volumes per second and few total number of volumes overall
-may be fine for some workloads (long-running applications which use
-specialize storage like PMEM) while others may need a much higher rate
-(adding a local LVM scratch volume to every pod in the system).
-
 The goal is to achieve the same provisioning rates with the feature
 enabled as those that currently can be achieved without it.