Merge pull request #8466 from adellape/enterprise-3.9

[enterprise-3.9] Update APB tool user permission reqs for 3.9

Author: adellape

apb_devel/cli_tooling.adoc

@@ -32,24 +32,52 @@ The `docker` daemon must be correctly installed and running on the system.
 [[apb-devel-cli-install-prereqs-access-permissions]]
 ==== Access Permissions
 
-You must be logged in via `oc` as a user with *cluster-admin* permissions:
+The `apb` tool requires you to be logged in as a tokened cluster user; the
+default *system:admin* system user is not sufficient because it does not have a
+token that can be used for the tool's authentication. In addition, there are a
+number of local roles (project-scoped) and cluster roles (cluster-wide) that
+must exist to permit the full breadth of the `apb` tool's functions (see
+xref:../architecture/additional_concepts/authorization.adoc#cluster-and-local-rbac[Cluster and Local RBAC]).
+
+The easiest option is to ensure the user has the *cluster-admin* cluster role.
+To add this role to another user, you can run the following as a user that
+already has such permissions (for example, the *system:admin* default system
+user):
+
+[WARNING]
+====
+This is effectively cluster *root* and should only be used in a development
+setting.
+====
 
 ----
+$ oc adm policy add-cluster-role-to-user cluster-admin <user>
 $ oc login -u <user> <openshift_server>
 ----
 
-To add this role to another user, you can run the following as a user that
-already has such permissions (for example, the *system:admin* default system
-user):
+If you would like a more strictly permissioned environment, an OpenShift
+template is provided that by default will permission a user called *developer*.
+The template must be run by a user with sufficient permissions to create the
+various roles. The *developer* user does not have such permissions, but the
+*system:admin* user is sufficient.
+
+To run the template:
 
+. Download the
+link:https://raw.githubusercontent.com/ansibleplaybookbundle/ansible-playbook-bundle/master/templates/openshift-permissions.template.yaml[*_openshift-permissions.template.yaml_*]
+file locally. 
+
+. Run the following command:
++
 ----
-$ oc adm policy \
-    add-cluster-role-to-user \
-    cluster-admin <user>
+$ oc process -f openshift-permissions.template.yaml \
+   -p BROKER_NAMESPACE=openshift-ansible-service-broker \
+   [-p USER=<your_desired_user>] \//<1>
+   | oc create -f -
 ----
-
-This permission requirement is so that the development lifecycle of the `apb`
-tool can function.
+<1> By default, the template will permission the *developer* user. You can
+optionally use the `-p` flag to override this default value with your desired
+user.
 
 ifdef::openshift-origin[]
 [[apb-devel-cli-install-containerized]]