Merge pull request #12 from observatorium/document_permissions

docs: document granting privileges

.github/workflows/ci.yml

@@ -55,19 +55,7 @@ jobs:
         data:
           server: "$SERVER"
         EOF
-        cat <<EOF | kubectl apply -f -
-        apiVersion: rbac.authorization.k8s.io/v1
-        kind: ClusterRole
-        metadata:
-          name: namespace-provisioner-grant
-        rules:
-        - apiGroups:
-          - ""
-          resources:
-          - pods
-          verbs:
-          - list
-        EOF
+        kubectl apply -f manifests/example-grants/pods.yaml
         kubectl -n namespace-provisioner set image deployment namespace-provisioner namespace-provisioner=quay.io/observatorium/namespace-provisioner:test
         kubectl -n namespace-provisioner rollout status deployment namespace-provisioner --timeout 1m
     - name: Test namespace-provisioner

README.md

@@ -15,9 +15,10 @@ Currently, the API only allows clients to authenticate via a bearer token, which
 
 ### Privileges
 
-The Namespace Provisioner provides the client with a Kubeconfig to operate the Namespaces it creates.
-The privileges given to this Kubeconfig can be controlled by providing the Namespace Provisioner a file containing a Kubernete RBAC Role at run-time with the `--role=<path-to-role>` flag.
-The Role contained in the file will be created in every provisioned Namespace and bound to the returned Kubeconfig. 
+The Namespace Provisioner provides the client with a Kubeconfig to operate the Namespaces it creates and binds a ClusterRole it to give it privileges.
+The ClusterRole is bound to the Kubeconfig using a RoleBinding, scoping the permissions down to only the newly created Namespace.
+By default, the Namespace Provisioner uses a ClusterRole named `namespace-provisioner-grant`, which grants no permissions to the subject.
+To control the permissions granted to the returned Kubeconfig, administrators can edit the `namespace-provisioner-grant` ClusterRole or change the target ClusterRole by specifying a different `--cluster-role=<name>` flag passed to the Namespace Provisioner.
 
 ### API Server
 

manifests/example-grants/pods.yaml

@@ -0,0 +1,13 @@
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: namespace-provisioner-grant
+  labels:
+    app.kubernetes.io/name: namespace-provisioner-grant
+    app.kubernetes.io/part-of: namespace-provisioner
+rules:
+- apiGroups:
+  - ""
+  resources:
+  - pods
+  verbs: ["*"]

manifests/namespace-provisioner.yaml

@@ -17,6 +17,15 @@ metadata:
 stringData:
   token: PASSWORD
 ---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: namespace-provisioner-grant
+  labels:
+    app.kubernetes.io/name: namespace-provisioner-grant
+    app.kubernetes.io/part-of: namespace-provisioner
+rules: []
+---
 apiVersion: v1
 kind: ConfigMap
 metadata: