Bump version to 0.15.1 and add versioned docs

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

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.15.0"
+var Version = "v0.15.1"
 
 // 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

@@ -49,6 +49,12 @@ defaults:
       version: master
       gh: https://github.com/heptio/sonobuoy/tree/master
       layout: "docs"
+  - scope:
+      path: docs/v0.15.1
+    values:
+      version: v0.15.1
+      gh: https://github.com/heptio/sonobuoy/tree/v0.15.1
+      layout: "docs"
   - scope:
       path: docs/v0.15.0
     values:
@@ -97,9 +103,10 @@ collections:
   - casestudies
 
 versioning: true
-latest: v0.15.0
+latest: v0.15.1
 versions:
 - master
+- v0.15.1
 - v0.15.0
 - v0.14.3
 - v0.14.2

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.15.1: v0-15-1toc
 v0.15.0: v0-15-0toc
 v0.14.3: v0-14-3toc
 v0.14.2: v0-14-2toc

site/_data/v0-15-1toc.yml

@@ -0,0 +1,30 @@
+toc:
+  - title: Setting up
+    subfolderitems:
+      - page: Getting started
+        url: /index.html
+      - page: Config
+        url: /sonobuoy-config
+      - page: Snapshot layout
+        url: /snapshot
+      - page: Viewing Results
+        url: /results
+      - page: ImagePullSecrects
+        url: /pullsecrets
+  - title: Use cases
+    subfolderitems:
+      - page: Conformance testing
+        url: /conformance-testing
+      - page: Custom Registries & Airgap Testing
+        url: /airgap
+      - page: Plugins
+        url: /plugins
+  - title: Next steps
+    subfolderitems:
+      - page: Customization
+        url: /gen
+      - page: Make your own plugins
+        url: /examples
+        github: true
+      - page: Cut a Release
+        url: /release

site/docs/v0.15.1/README.md

@@ -0,0 +1,171 @@
+# <img src="img/sonobuoy-logo.png" width="400px" > [![Build Status][status]][travis]
+
+## [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][e2e]
+* 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
+
+Download one of the releases directly from [here][releases].
+
+Alternatively, you can install the CLI by running:
+
+```bash
+go get -u -v github.com/heptio/sonobuoy
+```
+
+Golang version 1.12 or greater is recommended. Golang can be installed via
+[gimme][gimme].
+
+## 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 e2e $results
+```
+
+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 it's 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.
+
+### 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
+```
+
+## More information
+
+[The documentation][docs] provides further information about:
+
+* [conformance tests][conformance]
+* [plugins][plugins]
+* Testing of [air gapped clusters][airgap].
+* [Customization][gen] of YAML prior to running.
+* The [Sonobuoy config file][sonobuoyconfig] file and how to edit it.
+
+## 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.md
+[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/heptio/sonobuoy/blob/master/CODE_OF_CONDUCT.md
+[contrib]: https://github.com/heptio/sonobuoy/blob/master/CONTRIBUTING.md
+[conformance]: conformance-testing.md
+[docker]: https://docs.docker.com/install
+[docs]: https://sonobuoy.io/docs/v0.15.0/
+[e2e]: conformance-testing.md
+[gen]: gen.md
+[gimme]: https://github.com/travis-ci/gimme
+[issue]: https://github.com/heptio/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.md
+[quickstart]: https://aws.amazon.com/quickstart/architecture/vmware-kubernetes/
+[releases]: https://github.com/heptio/sonobuoy/releases
+[slack]: https://kubernetes.slack.com/messages/sonobuoy
+[snapshot]: snapshot.md
+[sonobuoyconfig]: sonobuoy-config.md
+[status]: https://travis-ci.org/heptio/sonobuoy.svg?branch=master
+[travis]: https://travis-ci.org/heptio/sonobuoy/#

site/docs/v0.15.1/airgap.md

@@ -0,0 +1,60 @@
+# Custom registries and air-gapped testing
+
+In air-gapped deployments where there is no access to the public Docker registries
+Sonobuoy supports running 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.
+
+## Test images
+
+Just provide the `--e2e-repo-config` parameter and pass it the path to a local
+YAML file pointing to the registries you'd like to use. This will instruct the
+Kubernetes end-to-end suite to use your registries instead of the default ones.
+
+```
+sonobuoy run --e2e-repo-config custom-repos.yaml
+```
+
+The registry list is a YAML document specifying a few different registry
+categories and their values:
+
+```
+dockerLibraryRegistry: docker.io/library
+e2eRegistry: gcr.io/kubernetes-e2e-test-images
+gcRegistry: k8s.gcr.io
+etcdRegistry: quay.io/coreos
+privateRegistry: gcr.io/k8s-authenticated-test
+sampleRegistry: gcr.io/google-samples
+```
+
+The keys in that file are specified in the Kubernetes test framework itself. You
+may provide a subset of those and the defaults will be used for the others.
+
+## Other required images
+
+The list of custom registries is consumed by the Kubernetes end-to-end tests, but outside of that there are 2 images you will need to be able to access:
+ - the sonobuoy image
+ - the conformance image
+
+To get those images into your cluster you need to pull/tag/push those images yourself:
+
+```
+PRIVATE_REG=<private registry>
+SONO_VERSION=<version of Sonobuoy you are targeting; e.g. v0.14.0>
+CLUSTER_VERSION=<version of k8s you are targeting; e.g. v1.14.0>
+
+docker pull gcr.io/google-containers/conformance:$CLUSTER_VERSION
+docker pull gcr.io/heptio-images/sonobuoy:$SONO_VERSION
+
+docker tag gcr.io/google-containers/conformance:$CLUSTER_VERSION $PRIVATE_REG/conformance:$CLUSTER_VERSION
+docker tag gcr.io/heptio-images/sonobuoy:$SONO_VERSION $PRIVATE_REG/sonobuoy:$SONO_VERSION
+
+docker push $PRIVATE_REG/conformance:$CLUSTER_VERSION
+docker push $PRIVATE_REG/sonobuoy:$SONO_VERSION
+```
+
+If you want to run the systemd_logs plugin you'll need to pull/tag/push it as well. In addition, you'll have to manually specify the image you want to use via `sonobuoy gen` -> `kubectl apply` since that image is not overridable on the CLI. The default value is: `gcr.io/heptio-images/sonobuoy-plugin-systemd-logs:latest`
+
+If you do not wish to run it in your air-gapped cluster, just remove it from the list of [plugins][plugins] to be run (again, using `sonobuoy gen` -> `kubectl apply`).
+
+[plugins]: plugins.md#choosing-which-plugins-to-run

site/docs/v0.15.1/conformance-testing.md

@@ -0,0 +1,44 @@
+# Conformance Testing - [1.11+][6]
+
+## Overview
+
+With such a [wide array][2] of Kubernetes distributions available, *conformance tests* help ensure that a Kubernetes cluster meets the minimal set of features. They are a subset of end-to-end (e2e) tests that should pass on any Kubernetes cluster.
+
+A conformance-passing cluster provides the following guarantees:
+
+* **Best practices**: Your Kubernetes is properly configured. This is useful to know whether you are running a distribution out of the box or handling your own custom setup.
+
+* **Predictability**: All your cluster behavior is well-documented. Available features in the official Kubernetes documentation can be taken as a given. Unexpected bugs should be rare, because distribution-specific issues are weeded out during the conformance tests.
+
+* **Interoperability**: Workloads from other conforming clusters can be ported into your cluster, or vice versa. This standardization of Kubernetes is a key advantage of open source software, and allows you to avoid vendor lock-in.
+
+Individual Kubernetes distributions may offer additional features beyond conformance testing, but if you change distributions, these features can't be expected to be provided.
+
+**NOTE:** Kubernetes documentation also describes the concept of "node conformance tests". Although they are useful, these tests are more component-focused than system-wide. They validate only the behavior of a specific node, not cluster behavior as a whole.
+
+See the [official documentation][4] for Kubernetes's existing conformance tests.
+
+## Integration with Sonobuoy
+
+Sonobuoy's [plugin architecture][5] enables you to integrate conformance test results into your reporting.  The e2e tests can be configured with the plugin. The default configuration runs the basic set of conformance tests against a local provider.
+
+To customize the set of tests that are run as part of the report, the following environmental variables can be set in the [plugin-specific YAML config][7]. Typically you set this via a flow that involves the [gen command][8]:
+
+| Variable | Default Value | Description |
+|---|---|---|
+| `E2E_FOCUS` | "Conformance" | The test suite to run.<br><br>*NOTE*: Because the real conformance suite can take up to an hour to run, the quickstart example's [e2e config][7] specifies just a single test, "Pods should be submitted and removed". |
+| `E2E_SKIP` | "Alpha&#124;Disruptive&#124;Feature&#124;Flaky" | Which subset of tests to skip |
+| `E2E_PROVIDER` | "local" | The platform that the cluster is running on |
+| `E2E_DRYRUN` | "" | Setting any non-empty value results in skipping the actual test execution but reporting the tests as successful. This is helpful when fine tuning your focus/skip regular expressions to target the desired tests. |
+
+*NOTE: The length of time it takes to run conformance can vary based on the size of your cluster---the timeout can be adjusted in the Server.timeoutseconds field of the Sonobuoy `config.json`.*
+
+[0]: #overview
+[1]: #integration-with-sonobuoy
+[2]: https://docs.google.com/spreadsheets/d/1LxSqBzjOxfGx3cmtZ4EbB_BGCxT_wlxW_xgHVVa23es/edit#gid=0
+[3]: https://kubernetes.io/docs/admin/node-conformance/
+[4]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-testing/e2e-tests.md#conformance-tests
+[5]: plugins.md
+[6]: https://github.com/kubernetes/kubernetes/issues/49313
+[7]: https://github.com/heptio/sonobuoy/examples/plugins.d/e2e.yaml#L9
+[8]: gen.md

site/docs/v0.15.1/gen.md

@@ -0,0 +1,24 @@
+# Customization
+
+Sonobuoy provides many flags to customize your run but sometimes you have a special use case that isn't supported yet.  For these cases, Sonobuoy provides `sonobuoy gen`.
+
+The command `sonobuoy gen` will print the YAML for your run to stdout instead of actually creating it. It accepts all of the relevant flags for customizing the run just like `sonobuoy run` would. You can then edit it yourself and apply it as if Sonobuoy had run it.
+
+Output the YAML Sonobuoy would create to a file:
+
+```
+sonobuoy gen --e2e-focus="sig-networking" --e2e-skip="Alpha" > sonobuoy.yaml
+```
+
+Then manually modify it as necessary. Maybe you need special options for plugins or want your own sidecar to be running with the images.
+
+Finally, create the resources yourself via kubectl.
+
+```
+kubectl apply -f sonobuoy.yaml
+```
+
+> Note: If you find that you need this flow to accomplish your work, talk to us about it in our [Slack][slack] channel or file an [issue][issue] in Github. Others may have the same need and we'd love to help support you.
+
+[slack]: https://kubernetes.slack.com/messages/sonobuoy
+[issue]: https://github.com/heptio/sonobuoy/issues

site/docs/v0.15.1/img/README.md

@@ -0,0 +1 @@
+Some of these diagrams (for instance sonobuoy-plugins.png), have been created on [draw.io](https://www.draw.io), using the "Include a copy of my diagram" option.  If you want to make changes to these diagrams, try importing them into draw.io, and you should have access to the original shapes/text that went into the originals.