From 7570df3828c957d60cfc10bc71ac62065d00a298 Mon Sep 17 00:00:00 2001
From: Nimrod Gilboa Markevich <59927337+nimrod-up9@users.noreply.github.com>
Date: Mon, 10 Jan 2022 15:36:16 +0200
Subject: [PATCH] Document ways to edit permissions (#616)

Document the ways by which users can overwrite / add to Mizu's permissions.
---
 docs/PERMISSIONS.md | 96 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 86 insertions(+), 10 deletions(-)

diff --git a/docs/PERMISSIONS.md b/docs/PERMISSIONS.md
index b200b7da6..2f3a0129c 100644
--- a/docs/PERMISSIONS.md
+++ b/docs/PERMISSIONS.md
@@ -1,16 +1,92 @@
 ![Mizu: The API Traffic Viewer for Kubernetes](../assets/mizu-logo.svg)
+
 # Kubernetes permissions for MIZU  
 
-This document describes in details all permissions required for full and correct operation of Mizu
+This document describes in details all permissions required for full and correct operation of Mizu.
+
+## Editting permissions
+
+During installation, Mizu creates a `ServiceAccount` and the roles it requires. No further action is required.
+However, if there is a need, it is possible to make changes to Mizu permissions.
+
+### Adding permissions on top of Mizu's defaults
+
+Mizu pods use the `ServiceAccount` `mizu-service-account`. Permissions can be added to Mizu by creating `ClusterRoleBindings` and `RoleBindings` that target that `ServiceAccount`.
+
+For example, in order to add a `PodSecurityPolicy` which allows Mizu to run `hostNetwork` and `privileged` pods, create the following resources:
+
+```yaml
+apiVersion: policy/v1beta1
+kind: PodSecurityPolicy
+metadata:
+  name: my-mizu-psp
+spec:
+  hostNetwork: true
+  privileged: true
+  allowedCapabilities:
+    - "*"
+  fsGroup:
+    rule: RunAsAny
+  runAsUser:
+    rule: RunAsAny
+  seLinux:
+    rule: RunAsAny
+  supplementalGroups:
+    rule: RunAsAny
+  volumes:
+  - "*"
+---
+kind: ClusterRole
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  name: my-mizu-clusterrole
+rules:
+- apiGroups:
+  - policy
+  resources:
+  - podsecuritypolicies
+  verbs:
+  - use
+  resourceNames:
+  - my-mizu-psp
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: my-mizu-clusterrolebinding
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: my-mizu-clusterrole
+subjects:
+- kind: ServiceAccount
+  name: mizu-service-account # The service account used by Mizu
+  namespace: mizu
+```
+
+With this setup, when Mizu starts and creates `mizu-service-account`, this account will be subject to `my-mizu-psp` via `my-mizu-clusterrolebinding`.
+When Mizu cleans up resources, the above resources will remain available for future executions.
+
+### Replacing Mizu's default permissions with custom permissions
+
+Mizu does not create its `ServiceAccounts`, `ClusterRoles`, `ClusterRoleBindings`, `Roles` or `RoleBindings` if resources by the same name already exist. In order to replace Mizu's defaults, simply create your resources before running Mizu.
+
+For example, creating a `ClusterRole` by the name of `mizu-cluster-role` before running Mizu will cause Mizu to use that `ClusterRole` instead of the default one created by Mizu.
+
+Notes:
+
+1. The resource names must match Mizu's default names.
+2. User-managed resources must not have the label `app.kubernetes.io/managed-by=mizu`. Remove the label or set it to another value.
+
+## List of permissions
 
 We broke down this list into few categories:
+
 - Required - what is needed for `mizu` to run properly on your k8s cluster
-- Optional - permissions needed for proper name resolving for service & pod IPs 
-   - addition required for policy validation 
- 
+- Optional - permissions needed for proper name resolving for service & pod IPs
+  - addition required for policy validation
 
-
-# Required permissions
+### Required permissions
 
 Mizu needs following permissions on your Kubernetes cluster to run properly
 
@@ -57,7 +133,7 @@ Mizu needs following permissions on your Kubernetes cluster to run properly
   - get
 ```
 
-## Permissions required running with install command or (optional) for service / pod name resolving
+#### Permissions required running with install command or (optional) for service / pod name resolving
 
 Mandatory permissions for running with install command.
 
@@ -178,7 +254,7 @@ Optional for service/pod name resolving in non install standalone
   - watch
 ```
 
-## Permissions for Policy rules validation feature (opt)
+#### Permissions for Policy rules validation feature (opt)
 
 Optionally, in order to use the policy rules validation feature, Mizu requires the following additional permissions:
 
@@ -195,7 +271,7 @@ Optionally, in order to use the policy rules validation feature, Mizu requires t
 
 - - -
 
-## Namespace-Restricted mode
+#### Namespace-Restricted mode
 
 Alternatively, in order to restrict Mizu to one namespace only (by setting `agent.namespace` in the config file), Mizu needs the following permissions in that namespace:
 
@@ -235,7 +311,7 @@ Alternatively, in order to restrict Mizu to one namespace only (by setting `agen
   - get
 ```
 
-### Name resolving in Namespace-Restricted mode (opt)
+##### Name resolving in Namespace-Restricted mode (opt)
 
 To restrict Mizu to one namespace while also resolving IPs, Mizu needs the following permissions in that namespace: