From 4c266265d1fa474585a190bb5ed28aa4e43ee522 Mon Sep 17 00:00:00 2001 From: Jessica Yao Date: Mon, 13 Nov 2017 12:25:46 -0500 Subject: [PATCH] highlight prereqs in readme Signed-off-by: Jessica Yao --- README.md | 35 ++++++++++++++++++++++------------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 66438b44a..2339e8281 100644 --- a/README.md +++ b/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 ```