Merge pull request vmware-tanzu#142 from abiogenesis-now/jyao/readme-…

…prereqs

[docs] Highlight prerequisites in README
Signed-off-by: Jesse Hamilton [email protected]

Signed-off-by: Jesse Hamilton [email protected]

README.md

@@ -26,6 +26,20 @@ To ensure that your cluster is running the appropriate Kubernetes version for yo
 | v0.9.0 / 1.8 | >= 1.7 | For earlier cluster versions (e.g. 1.6), some issues may exist. |
 | v0.8.0 / 1.7 | N/A | N/A |
 
+## Prerequisites
+
+* **You should have access to an up-and-running Kubernetes cluster.** If you do not have a cluster, follow the [AWS Quickstart Kubernetes Tutorial][5] to set one up with a single command.
+
+* **You should have `kubectl` installed.** If not, follow the instructions for [installing via Homebrew (MacOS)][6] or [building the binary (Linux)][7].
+
+* **You must run the `kubectl apply` commands for Sonobuoy as an admin user.**
+
+* **Your firewall settings must allow Sonobuoy to communicate with your cluster.**
+
+* **Your cluster must have the appropriate RBAC ClusterRole and ClusterRoleBinding configured.** By default, the Sonobuoy YAML assumes that your cluster is running with `--authorization-mode=RBAC`, and includes the required RBAC configurations.
+
+  (If you don't have RBAC enabled, subsequent documentation addresses how to handle this.)
+
 ## Up and running
 
 To easily get a Sonobuoy scan started on your cluster, use the browser-based [Sonobuoy Scanner tool][18]. Sonobuoy Scanner also provides a more user-friendly way of viewing your scan results.
@@ -45,12 +59,6 @@ This guide executes a Sonobuoy run on your cluster, and records the following re
 * *(Via plugin)* [`systemd`][14] logs from each host
 * *(Via plugin)* The results of a single e2e conformance test ("Pods should be submitted and removed"). See the [conformance guide][13] for configuration details.
 
-### 0. Prerequisites
-
-* *You should have access to an up-and-running Kubernetes cluster.* If you do not have a cluster, follow the [AWS Quickstart Kubernetes Tutorial][5] to set one up with a single command.
-
-* *You should have `kubectl` installed.* If not, follow the instructions for [installing via Homebrew (MacOS)][6] or [building the binary (Linux)][7].
-
 ### 1. Download
 Clone or fork the Sonobuoy repo:
 ```
@@ -59,20 +67,21 @@ git clone https://github.com/heptio/sonobuoy.git
 
 ### 2. Run
 
-Determine if your `kube-apiserver` supports RBAC with the following command:
+First, make sure that you're in your Sonobuoy root directory.
+
+If your cluster is not running RBAC, you'll need to regenerate the quickstart YAML files. To determine whether your cluster is running RBAC, run the command below:
+
 ```
-export RBAC_ENABLED=$(kubectl api-versions | grep "rbac.authorization.k8s.io/v1beta1" -c)
+export RBAC_ENABLED=$(kubectl api-versions | grep "rbac.authorization.k8s.io/v1" -c)
 ```
-The environment variable you set here indicates whether RBAC-related resources should be included in the autogenerated, standalone YAML file. In an cluster running with `--authorization-mode=RBAC`, these resources are required to allow Sonobuoy to run properly.
 
-Generate the YAML example:
+Use the environment variable you just set to regenerate `examples/quickstart.yaml`:
+
 ```
 make generate
 ```
 
-This should create `examples/quickstart.yaml`.
-
-To actually deploy a Sonobuoy pod to your cluster, run the following command in the Sonobuoy root directory:
+Now you're ready to deploy a Sonobuoy pod to your cluster! Run the following command:
 ```
 kubectl apply -f examples/quickstart.yaml
 ```