Docs: User Imper warnings, ImperWebhook References (#393)

* update docs

* fix markdown lint

* update installation instruction

* update docs

* update docs to match remote resource

* Update README.md

* Update README.md

Co-authored-by: Alex Lewitt <48691328+alewitt2@users.noreply.github.com>

README.md

@@ -14,9 +14,19 @@ defined in the `.spec.templates`, and finally apply the processed yaml to the cl
 
 ## Install
 
-```shell
-kubectl apply -f "https://github.com/razee-io/MustacheTemplate/releases/latest/download/resource.yaml"
-```
+[Razee Deploy Delta](https://github.com/razee-io/razeedeploy-delta) is the
+recommended way to install MustacheTemplate.
+
+Optional: [Advanced Controller Options](#cluster-wide-controls)
+
+**Warning:** By default, Razeedeploy runs as cluster wide admin. Any user that has
+permission to create a razeedeploy resource (RemoteResource or MustacheTemplate)
+has the ability to escalate their privileges. To prevent privilege escalation,
+cluster owners should restrict which users are allowed to create razeedeploy
+resources. Alternatively, you can setup [ImpersonationWebhook](https://github.com/razee-io/ImpersonationWebhook)
+and then [enable user impersonation](#enable-cluster-wide-user-impersonation) to
+ensure razeedeploy only allows users to do operations that they have already been
+granted access to do.
 
 ## Resource Definition
 
@@ -149,19 +159,22 @@ spec:
 
 **Path:** `.spec.clusterAuth.impersonateUser`
 
-**Description:** Impersonates a user for the given resource. This includes all
-actions the controller must make related to the resource (fetching envs, getting
-resources, applying resources, etc.). The RazeeDeploy resource must be created in
-the razeedeploy namespace in order to use impersonateUser, all other namespaces
-will ignore impersonateUser and default to the razeedeploy user (eg. no user impersonation).
-ImpersonateUser only applies to the single RazeeDeploy resource that it has been
-added to.
+**Description:** [Impersonates](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation)
+a user for the given resource. This includes all actions the controller must
+make related to the resource (fetching envs, getting resources, applying
+resources, etc.). ImpersonateUser only applies to the single RazeeDeploy
+resource that it has been added to.
 
-**Note:**: If cluster owners want to prevent users, with direct cluster access, from
-using user-impersonation, they should prevent those users from creating RazeeDeploy
-resources in the razeedeploy namespace. In the future we will have an Admission
-Controller that should improve security and eliminate the need for the razeedeploy
-namespace scoping. [razeedeploy-core #189](https://github.com/razee-io/razeedeploy-core/issues/189)
+**Enable Feature:** [Enable User Impersonation](#enable-cluster-wide-user-impersonation)
+
+**Warning:** By default, Razeedeploy runs as cluster wide admin. Any user that has
+permission to create a razeedeploy resource (RemoteResource or MustacheTemplate)
+has the ability to escalate their privileges. To prevent privilege escalation,
+cluster owners should restrict which users are allowed to create razeedeploy
+resources. Alternatively, you can setup [ImpersonationWebhook](https://github.com/razee-io/ImpersonationWebhook)
+and then [enable user impersonation](#enable-cluster-wide-user-impersonation) to
+ensure razeedeploy only allows users to do operations that they have already been
+granted access to do.
 
 **Schema:**
 
@@ -540,15 +553,58 @@ If you want to have the EnsureExist behavior, see [Resource Update Mode](#Resour
 
 - ie: `kubectl label mtp <your-mtp> deploy.razee.io/debug=true`
 
-### Lock Cluster Updates
+## Cluster Wide Controls
+
+The optional `razeedeploy-config` ConfigMap can be used to customize the
+controller for cluster wide actions.
+
+Because the ConfigMap is optional, if it is created the first time, you must
+restart controller pods, so the deployment can mount the ConfigMap
+as a volume.
+
+Example:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: razeedeploy-config
+  namespace: razeedeploy
+data:
+  lock-cluster: "false"
+  enable-impersonation: "false"
+```
+
+### Lock Cluster
+
+**Key:** `lock-cluster`
+
+**Options:**
+
+- DEFAULT: `false`
+  - Allows the controller to continue normal operations on the cluster.
+- `true`
+  - Prevents the controller from updating resources on the cluster.
+
+### Enable Cluster Wide User Impersonation
+
+**Key:** `enable-impersonation`
+
+**Options:**
 
-Prevents the controller from updating resources on the cluster. If this is the
-first time creating the `razeedeploy-config` ConfigMap, you must delete the running
-controller pods so the deployment can mount the ConfigMap as a volume. If the
-`razeedeploy-config` ConfigMap already exists, just add the pair `lock-cluster: true`.
+- DEFAULT: `false`
+  - Prevents the controller from performing [user impersonation](#user-impersonation)
+    in all namespaces. Continues to allow user impersonation in the `razeedeploy`
+    namespace. To prevent privildge escalation, users should be restricted from
+    creating razeedeploy resources.
+- `true`
+  - Allows the controller to perform [user impersonation](#user-impersonation)
+    in all namespaces. **See important note below about steps that should be taken
+    to properly configure this feature before enabling.**
 
-1. `export CONTROLLER_NAME=mustachetemplate-controller && export CONTROLLER_NAMESPACE=razee`
-1. `kubectl create cm razeedeploy-config -n $CONTROLLER_NAMESPACE --from-literal=lock-cluster=true`
-1. `kubectl delete pods -n $CONTROLLER_NAMESPACE $(kubectl get pods -n`
-   `$CONTROLLER_NAMESPACE | grep $CONTROLLER_NAME | awk '{print $1}'`
-   `| paste -s -d ',' -)`
+**IMPORTANT:** it is highly advised to set up [ImpersonationWebhook](https://github.com/razee-io/ImpersonationWebhook)
+before enabling cluster-wide impersonation. If ImpersonationWebhook is not installed
+before enabling impersonation, any user on the cluster that is allowed to create
+razeedeploy resources will be able to impersonate any other user. Once the ImpersonationWebhook
+controller is installed and all necessary config and authorizations in place, impersonation
+can be safely enabled in the `razeedeploy-config` configmap.