docs: aligning to latest API version

projectcapsule · Aug 21, 2021 · 4e437e6 · 4e437e6
1 parent d03b0b9
commit 4e437e6
Showing 1 changed file with 117 additions and 27 deletions.
diff --git a/README.md b/README.md
@@ -38,6 +38,7 @@ Current implementation filters the following requests:
 * `api/v1/nodes{/name}`
 * `apis/storage.k8s.io/v1/storageclasses{/name}`
 * `apis/networking.k8s.io/{v1,v1beta1}/ingressclasses{/name}`
+* `api/scheduling.k8s.io/{v1}/priorityclasses{/name}`
 
 All other requests are proxied transparently to the APIs server, so no side effects are expected. We're planning to add new APIs in the future, so PRs are welcome!
 
@@ -53,6 +54,38 @@ An Helm Chart is available [here](./charts/capsule-proxy/README.md).
 
 Yes, it works by intercepting all the requests from the `kubectl` client directed to the APIs server. It works with both users who use the TLS certificate authentication and those who use OIDC.
 
+## How RBAC is put in place?
+
+Each Tenant owner can have their capabilities managed pretty similar to a standard RBAC.
+
+```yaml
+apiVersion: capsule.clastix.io/v1beta1
+kind: Tenant
+metadata:
+  name: my-tenant
+spec:
+  owners:
+  - kind: User
+    name: alice
+    proxySettings:
+    - kind: IngressClasses
+      operations:
+      - List
+```
+
+The proxy setting `kind` is an __enum__ accepting the supported resources:
+
+- `Nodes`
+- `StorageClasses`
+- `IngressClasses`
+- `PriorityClasses`
+
+Each Resource kind can be granted with several verbs, such as:
+
+- `List`
+- `Update`
+- `Delete`
+
 ### Namespaces
 
 As tenant owner `alice`, you can use `kubectl` to create some namespaces:
@@ -78,16 +111,18 @@ When a Tenant defines a `.spec.nodeSelector`, the nodes matching that labels can
 The annotation `capsule.clastix.io/enable-node-listing` allows the ability for the owners to retrieve the node list (useful in shared HW scenarios).
 
 ```yaml
-apiVersion: capsule.clastix.io/v1alpha1
+apiVersion: capsule.clastix.io/v1beta1
 kind: Tenant
 metadata:
   name: oil
-  annotations:
-    capsule.clastix.io/enable-node-listing: "true"
 spec:
-  owner:
-    kind: User
+  owners:
+  - kind: User
     name: alice
+    proxySettings:
+    - kind: Nodes
+      operations:
+        - List
   nodeSelector:
     kubernetes.io/hostname: capsule-gold-qwerty
 ```
@@ -109,16 +144,18 @@ capsule-gold-qwerty     Ready    <none>   43h   v1.19.1
 A Tenant may be limited to use a set of allowed Storage Class resources, as follows.
 
 ```yaml
-apiVersion: capsule.clastix.io/v1alpha1
+apiVersion: capsule.clastix.io/v1beta1
 kind: Tenant
 metadata:
   name: oil
-  annotations:
-    capsule.clastix.io/enable-storageclass-listing: "true"
 spec:
-  owner:
-    kind: User
+  owners:
+  - kind: User
     name: alice
+    proxySettings:
+    - kind: StorageClasses
+      operations:
+      - List
   storageClasses:
     allowed:
       - custom
@@ -158,20 +195,23 @@ glusterfs            rook.io/glusterfs        Delete          WaitForFirstConsum
 As for Storage Class, also Ingress Class can be enforced.
 
 ```yaml
-apiVersion: capsule.clastix.io/v1alpha1
+apiVersion: capsule.clastix.io/v1beta1
 kind: Tenant
 metadata:
   name: oil
-  annotations:
-    capsule.clastix.io/enable-ingressclass-listing: "true"
 spec:
-  owner:
-    kind: User
+  owners:
+  - kind: User
     name: alice
-  ingressClasses:
-    allowed:
-      - custom
-    allowedRegex: "\\w+-lb"
+    proxySettings:
+    - kind: IngressClasses
+      operations:
+      - List
+  ingressOptions:
+    allowedClasses:
+        allowed:
+          - custom
+        allowedRegex: "\\w+-lb"
 ```
 
 In the Kubernetes cluster we could have more Ingress Class resources, some of them forbidden and non-usable by the Tenant owner.
@@ -189,22 +229,62 @@ nginx             nginx.plus/ingress
 The expected output using `capsule-proxy` is the retrieval of the `custom` Ingress Class as well the other ones matching the regex `\w+-lb`.
 
 ```bash
-$ kubectl --context admin@mycluster get ingressclasses
+$ kubectl --context alice-oidc@mycluster get ingressclasses
 NAME              CONTROLLER                 PARAMETERS                                      AGE
 custom            example.com/custom         IngressParameters.k8s.example.com/custom        24h
 external-lb       example.com/external       IngressParameters.k8s.example.com/external-lb   2s
 internal-lb       example.com/internal       IngressParameters.k8s.example.com/internal-lb   15m
 ```
 
-> The following Tenant annotations allow a sort of RBAC on the Ingress Class operations:
->
-> - `capsule.clastix.io/enable-ingressclass-listing`: allows listing of Ingress Class and Ingress Classes retrieval
-> - `capsule.clastix.io/enable-ingressclass-update`: allows the update of the Ingress Class
-> - `capsule.clastix.io/enable-ingressclass-deletion`: allows deletion of the Ingress Class
+### Priority Classes
+
+Allowed PriorityClasses assigned to a Tenant Owner can be enforced as follows.
+
+```yaml
+apiVersion: capsule.clastix.io/v1beta1
+kind: Tenant
+metadata:
+  name: oil
+spec:
+  owners:
+  - kind: User
+    name: alice
+    proxySettings:
+    - kind: IngressClasses
+      operations:
+      - List
+  priorityClasses:
+    allowed:
+      - best-effort
+    allowedRegex: "\\w+priority"
+```
 
-### Storage and Ingress class required label
+In the Kubernetes cluster we could have more PriorityClasses resources, some of them forbidden and non-usable by the Tenant owner.
 
-For Storage and Ingress Class resources, the `name` label reflecting the resource name is mandatory, otherwise filtering of resources cannot be put in place.
+```bash
+$ kubectl --context admin@mycluster get priorityclasses.scheduling.k8s.io
+NAME                      VALUE        GLOBAL-DEFAULT   AGE
+custom                    1000         false            18s
+maxpriority               1000         false            18s
+minpriority               1000         false            18s
+nonallowed                1000         false            8m54s
+system-cluster-critical   2000000000   false            3h40m
+system-node-critical      2000001000   false            3h40m
+```
+
+The expected output using `capsule-proxy` is the retrieval of the `custom` PriorityClass as well the other ones matching the regex `\w+priority`.
+
+```bash
+$ kubectl --context alice-oidc@mycluster get ingressclasses
+NAME                      VALUE        GLOBAL-DEFAULT   AGE
+custom                    1000         false            18s
+maxpriority               1000         false            18s
+minpriority               1000         false            18s
+```
+
+### Storage/Ingress class and PriorityClass required label
+
+For Storage Class, Ingress Class and Priority Class resources, the `name` label reflecting the resource name is mandatory, otherwise filtering of resources cannot be put in place.
 
 ```yaml
 ---
@@ -228,6 +308,16 @@ spec:
     apiGroup: k8s.example.com
     kind: IngressParameters
     name: external-lb
+---
+apiVersion: scheduling.k8s.io/v1
+kind: PriorityClass
+metadata:
+  labels:
+    name: best-effort
+  name: best-effort
+value: 1000
+globalDefault: false
+description: "Priority class for best-effort Tenants"
 ```
 
 ## Does it work with my preferred Kubernetes dashboard?