From a302735ff0eaeee93b612d678ecb1636fdf5a1f9 Mon Sep 17 00:00:00 2001 From: Chao Xu Date: Thu, 3 Jan 2019 16:35:31 -0800 Subject: [PATCH] improve the motivation section --- keps/sig-api-machinery/34-storage-hash.md | 82 +++++++++++++---------- 1 file changed, 46 insertions(+), 36 deletions(-) diff --git a/keps/sig-api-machinery/34-storage-hash.md b/keps/sig-api-machinery/34-storage-hash.md index 4bf93cc031b2..4b9e0b4fdf32 100644 --- a/keps/sig-api-machinery/34-storage-hash.md +++ b/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