From 94fd79836827312d82034c2ab623ec893e8cea9d Mon Sep 17 00:00:00 2001 From: Khoi Nguyen Date: Thu, 16 Jun 2022 11:50:10 -0400 Subject: [PATCH] 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 | 106 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 81 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 54c5b72..04842a1 100644 --- a/README.md +++ b/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 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.