improve the motivation section

keps/sig-api-machinery/34-storage-hash.md

@@ -1,5 +1,5 @@
 ---
-kep-number: 31
+kep-number: 34
 title: Enabling clients to tell if resource endpoints serve the same set of objects
 authors:
   - "@xuchao"
@@ -21,9 +21,8 @@ status: provisional
 
       * [Summary](#summary)
       * [Motivation](#motivation)
-            * [Broken forward compatibility](#broken-forward-compatibility)
-            * [Inaccurate resource quota counting](#inaccurate-resource-quota-counting)
-            * [Inefficiency of API-discovery based dynamic clients](#inefficiency-of-api-discovery-based-dynamic-clients)
+            * [Correctness](#correctness)
+            * [Efficiency](#efficiency)
       * [Goals](#goals)
       * [Proposal](#proposal)
          * [API changes to the discovery API](#api-changes-to-the-discovery-api)
@@ -40,44 +39,55 @@ referring the same set of objects.
 
 ## Motivation
 
-Sometimes clients want to process every object in the cluster (examples below).
-Lack of visibility makes it hard for clients to understand which resources they
-need to process in that case.
-
-#### Broken forward compatibility
-
-For example, if we configure an admission webhook to validate all replicasets,
-one would set the webhook configuration this way:
-```yaml
-rules:
-  - apiGroups:
-    - "extensions,apps"
-    apiVersions:
-    - "*"
-    resources:
-    - replicasets
-```
+Today, some workload objects (e.g., `replicasets`) are accessible from both the
+`extensions` and the `apps` endpoints. This can happen to more of Kubernetes
+APIs in the future. Enabling the clients to programmatically detect aliasing
+endpoints can improve both the correctness and the efficiency.
+
+#### Correctness
+* Resource quotas: although `extensions/v1beta1/replicasets` and
+  `apps/v1/replicasets` refer to the same set of objects, they have separate
+  resource quotas today. User can bypass the resource quota of one endpoint by
+  using the other endpoint.
+
+* [Admission webhook rules][]: after a cluster upgrade, if a
+  resource becomes accessible from a new group, the new endpoint will bypass
+  existing rules. For example, here is a webhook configuration that will enforce
+  webhook checks on all replicasets.
+
+  ```yaml
+  rules:
+    - apiGroups:
+      - "extensions,apps"
+      apiVersions:
+      - "*"
+      resources:
+      - replicasets
+  ```
+
+  However, if in a future release, replicasets are accessible via
+  `fancy-apps/v1` as well, requests sent to `fancy-apps/v1` will be left
+  unchecked. Note that the admins of cluster upgrades are not necessarily the
+  admins of the admission webhooks, so it is not always possible to coordinate
+  cluster upgrades with webhook configuration upgrades.
+
+  If the webhook controller can detect all aliasing resource endpoints, then it
+  can convert `fancy-apps/v1` replicasets to the `apps/v1` and send it to the
+  webhook.
 
-If in a future Kubernetes release, replicasets are accessible via
-`fancy-apps/v1` as well, requests sent to `fancy-apps/v1` will be left
-unchecked. Note that the admins of cluster upgrades are not necessarily the
-admins of the admission webhooks, so it is not always possible to coordinate
-cluster upgrades with webhook configuration upgrades.
+[Admission webhook rules]:https://github.com/kubernetes/kubernetes/blob/18778ea4a151d5f8b346332cb2822b2b0f9d1981/staging/src/k8s.io/api/admissionregistration/v1beta1/types.go#L29
 
-#### Inaccurate resource quota counting
+  As a side note, one would expect the [RBAC rules][] would suffer the same
+  problem. However, RBAC is deny by default, so access to the new endpoint is
+  denied unless admin explicitly updates the policy, which is what we want.
 
-Although `extensions/v1beta1/replicasets` and `apps/v1/replicasets` refer to the
-same set of objects, they have separate resource quotas. User can bypass the 
-resource quota of one endpoint by using the other endpoint.
+[RBAC rules]:https://github.com/kubernetes/kubernetes/blob/18778ea4a151d5f8b346332cb2822b2b0f9d1981/staging/src/k8s.io/api/authorization/v1/types.go#L249
 
-#### Inefficiency of API-discovery based dynamic clients
+#### Efficiency
 
-For example, the Kubernetes [garbage collector][] watches all discoverable
-resource endpoints and thus wasting bandwidth. As another example, the [storage
-migrator][] migrates the same objects multiple times if they are served via
-multiple endpoints.
+* The [storage migrator][] migrates the same objects multiple times if they are
+served via multiple endpoints.
 
-[garbage collector]:https://github.com/kubernetes/kubernetes/tree/master/pkg/controller/garbagecollector
 [storage migrator]:https://github.com/kubernetes-sigs/kube-storage-version-migrator