Merge pull request #330 from brandonvin/configure-cluster-profile-doc-updates

Improve cluster profile setup docs

Author: chadlwilson

docs/configure_cluster_profile.md

@@ -2,24 +2,49 @@
 
 ### Configure Cluster Profile
 
-1. Login to `GoCD server` as admin and navigate to **_Admin_** _>_ **_Elastic Agent Configurations_**
-2. Click on **_Add_** button and select `Kubernetes Elastic Agent Plugin` from the plugin ID dropdown.
-    1. Specify `Cluster Profile Name` for the new cluster
-    1. Optionally specify `Go Server URL`, if GoCD secure site URL is not configured.
-    2. Optionally Specify `Agent auto-register timeout (in minutes)`, Defaults to `10` (mintues).
-    3. Optionally Specify `Maximum pending pods`, Defaults to `10` (pods).
-    4. Specify `Cluster URL`.
-    5. Optionally Specify `Namespace`, Defaults to `default`. Note: If you have multiple GoCD servers with cluster profiles pointing to the same Kubernetes cluster, make sure that the namespace is different. Otherwise, the plugin of one GoCD server will end up terminating pods started by the plugin in the other GoCD servers.
-    6. Specify `Security token`, The token must have permission to perform the following operations -
-        ```
-        - nodes: list, get
-        - events: list, watch
-        - namespace: list, get
-        - pods, pods/log: *
-        ```
-    7. Optionally, Specify `Cluster CA certificate data`.
-    
-    !["Kubernetes Cluster Profile"][1]
-    
+1. Log in to the GoCD server as admin and navigate to **_Admin_** _>_ **_Elastic Agent Configurations_**.
+
+1. Click on the **_Add_** button and select `Kubernetes Elastic Agent Plugin` from the plugin ID dropdown.
+
+1. Specify `Cluster Profile Name` for the new cluster.
+
+1. Optionally specify `Go Server URL`. If your GoCD server has a [secure site URL][secure site URL]
+   configured, then the secure site URL is used as a default. Otherwise, a URL must be specified here.
+
+1. Optionally specify `Agent auto-register timeout (in minutes)`. This defaults to 10 (minutes) if not provided.
+
+1. Optionally Specify `Maximum pending pods`. This defaults to 10 (pods) if not provided.
+
+1. Specify `Cluster URL`.
+
+1. Optionally specify `Namespace`. If not provided, the plugin will launch GoCD
+   agent pods in the default Kubernetes namespace. Note: If you have multiple
+   GoCD servers with cluster profiles pointing to the same Kubernetes cluster,
+   make sure that the namespace used by each GoCD server is different.
+   Otherwise, the plugin of one GoCD server will end up terminating pods
+   started by the plugin in the other GoCD servers.
+
+1. Specify `Security token`. This should be a Kubernetes API token with the
+   following permissions:
+
+   | Resource       | Actions     |
+   | -------------- | ----------- |
+   | nodes          | list        |
+   | events         | list        |
+   | pods, pods/log | *           |
+
+   If the plugin is using a non-default namespace, then the pods and pods/log permissions
+   can be limited to that namespace (using a role + role binding), and the plugin
+   will still work. Nodes list and events list need to be attached at the cluster
+   level (using a cluster role + cluster role binding) regardless of the
+   namespace chosen.
+
+1. Optionally specify `Cluster CA certificate data`. This should be the base-64-encoded certificate
+   of the Kubernetes API server. It can be omitted in the rare case that the Kubernetes API
+   is configured to serve plain HTTP.
+
+!["Kubernetes Cluster Profile"][1]
+
 
 [1]: images/cluster-profile.png     "Kubernetes Cluster Profile"
+[secure site URL]: https://docs.gocd.org/current/installation/configuring_server_details.html