Bump version to v0.17.2 and add docs (#1075)

Signed-off-by: John Schnake <[email protected]>

Author: johnSchnake

pkg/buildinfo/version.go

@@ -20,7 +20,7 @@ limitations under the License.
 package buildinfo
 
 // Version is the current version of Sonobuoy, set by the go linker's -X flag at build time
-var Version = "v0.17.1"
+var Version = "v0.17.2"
 
 // GitSHA is the actual commit that is being built, set by the go linker's -X flag at build time.
 var GitSHA string

site/_config.yml

@@ -52,6 +52,12 @@ defaults:
       version: master
       gh: https://github.com/vmware-tanzu/sonobuoy/tree/master
       layout: "docs"
+  - scope:
+      path: docs/v0.17.2
+    values:
+      version: v0.17.2
+      gh: https://github.com/vmware-tanzu/sonobuoy/tree/v0.17.2
+      layout: "docs"
   - scope:
       path: docs/v0.17.1
     values:
@@ -173,9 +179,10 @@ collections:
   - plugin-list
 
 versioning: true
-latest: v0.17.1
+latest: v0.17.2
 versions:
 - master
+- v0.17.2
 - v0.17.1
 - v0.17.0
 - v0.16.5

site/_data/toc-mapping.yml

@@ -5,6 +5,7 @@
 # Below is a commented out example of what this may look like:
 
 master: master-toc
+v0.17.2: v0-17-2toc
 v0.17.1: v0-17-1toc
 v0.17.0: v0-17-0toc
 v0.16.5: v0-16-5toc

site/_data/v0-17-2toc.yml

@@ -0,0 +1,32 @@
+toc:
+  - title: Basics
+    subfolderitems:
+      - page: Overview
+        url: /index.html
+      - page: Checking Results
+        url: /results
+  - title: Plugins
+    subfolderitems:
+      - page: Overview
+        url: /plugins
+      - page: E2E & Conformance
+        url: /e2eplugin
+      - page: Examples
+        url: /examples
+        github: true
+  - title: Advanced
+    subfolderitems:
+      - page: Detailed result contents
+        url: /snapshot
+      - page: Configuration Options
+        url: /sonobuoy-config
+      - page: Custom Registries & Airgap Testing
+        url: /airgap
+      - page: Using Private Images
+        url: /pullsecrets
+      - page: Advanced Customization
+        url: /gen
+  - title: Resources
+    subfolderitems:
+      - page: Frequently Asked Questions
+        url: /faq

site/docs/v0.17.2/README.md

@@ -0,0 +1,180 @@
+# <img src="img/sonobuoy-logo.png" width="400px" alt="Sonobuoy logo" > [![CircleCI](https://circleci.com/gh/vmware-tanzu/sonobuoy.svg?style=svg)](https://circleci.com/gh/vmware-tanzu/sonobuoy)
+
+## [Overview][oview]
+
+Sonobuoy is a diagnostic tool that makes it easier to understand the
+state of a Kubernetes cluster by running a set of plugins (including [Kubernetes][k8s] conformance
+tests) in an accessible and non-destructive manner. It is a customizable,
+extendable, and cluster-agnostic way to generate clear, informative reports
+about your cluster.
+
+Its selective data dumps of Kubernetes resource objects and cluster nodes allow
+for the following use cases:
+
+* Integrated end-to-end (e2e) [conformance-testing][e2ePlugin]
+* Workload debugging
+* Custom data collection via extensible plugins
+
+Sonobuoy supports 3 Kubernetes minor versions: the current release and 2 minor versions before. Sonobuoy is currently versioned to track the Kubernetes minor version to clarify the support matrix. For example, Sonobuoy v0.14.x would support Kubernetes 1.14.x, 1.13.x, and 1.12.x.
+
+> Note: You can skip this version enforcement by running Sonobuoy with the `--skip-preflight` flag.
+
+## Prerequisites
+
+* Access to an up-and-running Kubernetes cluster. If you do not have a cluster,
+  we recommend following the [AWS Quickstart for Kubernetes][quickstart] instructions.
+
+* An admin `kubeconfig` file, and the KUBECONFIG environment variable set.
+
+* For some advanced workflows it may be required to have `kubectl` installed. See [installing via Homebrew (MacOS)][brew] or [building
+  the binary (Linux)][linux].
+
+* The `sonobuoy images` subcommand requires [Docker](https://www.docker.com) to be installed. See [installing Docker](docker).
+
+## Installing
+
+We recommend installing Sonobuoy via downloading one of the releases directly from [here][releases].
+
+You can use the web UI to download a release or from the terminal:
+
+```
+$ VERSION=0.16.1 OS=darwin && \
+    curl -L "https://github.com/vmware-tanzu/sonobuoy/releases/download/v${VERSION}/sonobuoy_${VERSION}_${OS}_amd64.tar.gz" --output $HOME/bin/sonobuoy.tar.gz && \
+    tar -xzf $HOME/bin/sonobuoy.tar.gz -C $HOME/bin && \
+    chmod +x $HOME/bin/sonobuoy && \
+    rm $HOME/bin/sonobuoy.tar.gz
+```
+
+> Note: Be sure to update the OS to your local value. Supported values are: "linux", "darwin", and "windows".
+
+If building locally, you should clone the repository and run `make`. To build locally, Docker is required.
+
+## Getting Started
+
+To launch conformance tests (ensuring [CNCF][cncf] conformance) and wait until they are finished run:
+
+```bash
+sonobuoy run --wait
+```
+
+> Note: Using `--mode quick` will significantly shorten the runtime of Sonobuoy. It runs just a single test, helping to quickly validate your Sonobuoy and Kubernetes configuration.
+
+Get the results from the plugins (e.g. e2e test results):
+
+```bash
+results=$(sonobuoy retrieve)
+```
+
+Inspect results for test failures.  This will list the number of tests failed and their names:
+
+```bash
+sonobuoy results $results
+```
+
+> Note: The `results` command has lots of useful options for various situations. See the [results page][results] for more details.
+
+You can also extract the entire contents of the file to get much more [detailed data][snapshot] about your cluster.
+
+Sonobuoy creates a few resources in order to run and expects to run within its
+own namespace.
+
+Deleting Sonobuoy entails removing its namespace as well as a few cluster
+scoped resources.
+
+```bash
+sonobuoy delete --wait
+```
+
+> Note: The --wait option ensures the Kubernetes namespace is deleted, avoiding conflicts if another Sonobuoy run is started quickly.
+
+### Other Tests
+
+By default, `sonobuoy run` runs the Kubernetes conformance tests but this can easily be configured. The same plugin that has the conformance tests has all the Kubernetes end-to-end tests which include other tests such as:
+
+* tests for specific storage features
+* performance tests
+* scaling tests
+* provider specific tests
+* and many more
+
+To modify which tests you want to run, checkout our page on the [e2e plugin][e2ePlugin].
+
+If you want to run other tests or tools which are not a part of the Kubernetes end-to-end suite, refer to our documentation on [custom plugins][customPlugins].
+
+### Monitoring Sonobuoy during a run
+
+You can check on the status of each of the plugins running with:
+
+```bash
+sonobuoy status
+```
+
+You can also inspect the logs of all Sonobuoy containers:
+
+```bash
+sonobuoy logs
+```
+
+## Troubleshooting
+
+If you encounter any problems that the documentation does not address, [file an
+issue][issue].
+
+## Known Issues
+
+### Leaked End-to-end namespaces
+
+There are some Kubernetes e2e tests that may leak resources. Sonobuoy can
+help clean those up as well by deleting all namespaces prefixed with `e2e`:
+
+```bash
+sonobuoy delete --all
+```
+
+### Run on Google Cloud Platform (GCP)
+
+Sonobuoy requires admin permissions which won't be automatic if you are running via Google Kubernetes Engine (GKE) cluster. You must first create an admin role for the user under which you run Sonobuoy:
+
+```bash
+kubectl create clusterrolebinding <your-user-cluster-admin-binding> --clusterrole=cluster-admin --user=<[email protected]>
+```
+
+## Contributing
+
+Thanks for taking the time to join our community and start contributing! We
+welcome pull requests. Feel free to dig through the [issues][issue] and jump in.
+
+### Before you start
+
+* Please familiarize yourself with the [Code of Conduct][coc] before
+  contributing.
+* See [CONTRIBUTING.md][contrib] for instructions on the developer certificate
+  of origin that we require.
+* There is a [Slack channel][slack] if you want to
+  interact with other members of the community
+
+## Changelog
+
+See [the list of releases][releases] to find out about feature changes.
+
+[airgap]: airgap
+[brew]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-with-homebrew-on-macos
+[cncf]: https://github.com/cncf/k8s-conformance#certified-kubernetes
+[coc]: https://github.com/vmware-tanzu/sonobuoy/blob/master/CODE_OF_CONDUCT.md
+[contrib]: https://github.com/vmware-tanzu/sonobuoy/blob/master/CONTRIBUTING.md
+[docker]: https://docs.docker.com/install
+[docs]: https://sonobuoy.io/docs/v0.17.2
+[e2ePlugin]: e2eplugin
+[customPlugins]: plugins
+[gen]: gen
+[issue]: https://github.com/vmware-tanzu/sonobuoy/issues
+[k8s]: https://github.com/kubernetes/kubernetes
+[linux]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#tabset-1
+[oview]: https://youtu.be/k-P4hXdruRs?t=9m27s
+[plugins]: plugins
+[quickstart]: https://aws.amazon.com/quickstart/architecture/vmware-kubernetes/
+[releases]: https://github.com/vmware-tanzu/sonobuoy/releases
+[results]: results
+[slack]: https://kubernetes.slack.com/messages/sonobuoy
+[snapshot]:snapshot
+[sonobuoyconfig]: sonobuoy-config

site/docs/v0.17.2/airgap.md

@@ -0,0 +1,125 @@
+# Custom registries and air-gapped testing
+
+In air-gapped deployments where there is no access to the public Docker registries Sonobuoy supports running the end-to-end tests with custom registries.
+This enables you to test your air-gapped deployment once you've loaded the necessary images into a registry that is reachable by your cluster.
+
+You will need to make the Sonobuoy image available as well as the images for any plugins you wish to run.
+Below, you will find the details of how to use the Sonobuoy image, as well as the images for the `e2e` and `systemd-logs` plugins in this kind of deployment.
+
+## Sonobuoy Image
+To run any Sonobuoy plugin in an air-gapped deployment, you must ensure that the Sonobuoy image is available in a registry that is reachable by your cluster.
+You will need to pull, tag, and then push the image as follows:
+
+```
+PRIVATE_REG=<your private registry>
+SONOBUOY_VERSION=<version of Sonobuoy you are targeting; e.g. v0.16.0>
+
+docker pull sonobuoy/sonobuoy:$SONOBUOY_VERSION
+docker tag sonobuoy/sonobuoy:$SONOBUOY_VERSION $PRIVATE_REG/sonobuoy:$SONOBUOY_VERSION
+docker push $PRIVATE_REG/sonobuoy:$SONOBUOY_VERSION
+```
+
+By default, Sonobuoy will attempt to use the image available in the public registry.
+To use the image in your own registry, you will need to override it when using the `gen` or `run` command with the `--sonobuoy-image` flag as follows:
+
+```
+sonobuoy run --sonobuoy-image $PRIVATE_REG/sonobuoy:$SONOBUOY_VERSION
+```
+
+## E2E Plugin
+
+To use the `e2e` plugin, the conformance test image and the images the tests use must be available in your registry.
+
+### Conformance Image
+The process for making the conformance image available in your registry is the same as the Sonobuoy image.
+You need to pull, tag, and then push the image.
+To ensure you use the correct version of the conformance image, check your server version using `kubectl version`.
+
+
+```
+PRIVATE_REG=<private registry>
+CLUSTER_VERSION=<version of k8s you are targeting; e.g. v1.16.0>
+
+docker pull gcr.io/google-containers/conformance:$CLUSTER_VERSION
+docker tag gcr.io/google-containers/conformance:$CLUSTER_VERSION $PRIVATE_REG/conformance:$CLUSTER_VERSION
+docker push $PRIVATE_REG/conformance:$CLUSTER_VERSION
+```
+
+To use the conformance image in your registry, you will need to override the default when using the `gen` or `run` commands with the `--kube-conformance-image` flag as follows:
+
+```
+sonobuoy run --kube-conformance-image $PRIVATE_REG/conformance:$CLUSTER_VERSION
+```
+
+### Test Images
+
+The end-to-end tests use a number of different images across multiple registries.
+When running the `e2e` plugin, you must provide a mapping that details which custom registries should be used instead of the public registries.
+
+This mapping is a YAML file which maps the registry category to the corresponding registry URL.
+The keys in this file are specified in the Kubernetes test framework.
+The tests for each minor version of Kubernetes use a different set of registries so the mapping you create will depend on which Kubernetes version you are testing against.
+
+To create this mapping, you can use the `gen default-image-config` command to provide the mapping with the default registry values for your cluster version.
+The following is an example of using this command with a v1.16 cluster:
+
+```
+$ sonobuoy gen default-image-config
+dockerLibraryRegistry: docker.io/library
+e2eRegistry: gcr.io/kubernetes-e2e-test-images
+gcRegistry: k8s.gcr.io
+googleContainerRegistry: gcr.io/google-containers
+sampleRegistry: gcr.io/google-samples
+```
+
+You can save this output to a file and modify it to specify your own registries instead.
+You can modify all of the registry values or just a subset.
+If you specify only a subset, the defaults will be used instead.
+
+Sonobuoy provides the command `images` to help you easily pull the test images and push them to your own custom registries.
+First, you must pull the images to your local machine using the following command:
+
+```
+sonobuoy images pull
+```
+
+> **NOTE:** Some versions of Kubernetes reference images that do not exist or cannot be pulled without authentication.
+> You may see these errors when running the above command. This is expected behaviour.
+> These images are referenced by some end-to-end tests, but **not** by the conformance tests.
+
+To push the images, you must provide the mapping using the `--e2e-repo-config` flag as follows: 
+
+```
+sonobuoy images push --e2e-repo-config <path/to/custom-repo-config.yaml>
+```
+
+Sonobuoy will read the mapping config and will push the images to the repositories defined in that mapping.
+
+When running the `e2e` plugin, you will need to provide this file using the same flag as follows:
+
+```
+sonobuoy run --e2e-repo-config <path/to/custom-repo-config.yaml>
+```
+
+## systemd-logs plugin
+
+If you want to run the `systemd-logs` plugin you will again need to pull, tag, and push the image.
+
+
+```
+PRIVATE_REG=<private registry>
+
+docker pull gcr.io/heptio-images/sonobuoy-plugin-systemd-logs:latest
+docker tag gcr.io/heptio-images/sonobuoy-plugin-systemd-logs:latest $PRIVATE_REG/sonobuoy-plugin-systemd-logs:latest
+docker push $PRIVATE_REG/sonobuoy-plugin-systemd-logs:latest
+```
+
+To use the image in your own registry, you will need to override the default when using the `gen` or `run` commands with the `--systemd-logs-image` flag as follows:
+
+```
+sonobuoy run --systemd-logs-image $PRIVATE_REG/sonobuoy-plugin-systemd-logs:latest
+```
+
+If you do not wish to run this plugin, you can remove it from the list of [plugins][plugins] to be run within the manifest, or you can explicitly specify which plugin you with to run with the `--plugin` flag.
+
+[plugins]: plugins.md#choosing-which-plugins-to-run