Add docs and bump to v0.55.1

Signed-off-by: John Schnake <jschnake@vmware.com>

pkg/buildinfo/version.go

@@ -21,7 +21,7 @@ package buildinfo
 
 // Version is the current version of Sonobuoy, set by the go linker's -X flag at build time.
 // Ensure that this is bumped manually as well so that Sonobuoy, as a library, also has the right version.
-var Version = "v0.55.0"
+var Version = "v0.55.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.yaml

@@ -32,9 +32,10 @@ params:
   docs_search_index_name: index_name
   docs_search_api_key: api_key
   docs_versioning: true
-  docs_latest: v0.55.0
+  docs_latest: v0.55.1
   docs_versions:
     - main
+    - v0.55.1
     - v0.55.0
     - v0.54.0
     - v0.53.2

site/content/docs/v0.55.1/_index.md

@@ -0,0 +1,252 @@
+---
+version: v0.55.1
+cascade:
+  layout: docs
+  gh: https://github.com/vmware-tanzu/sonobuoy/tree/v0.55.1
+---
+# ![Sonobuoy Logo](img/sonobuoy-logo.png)
+
+[![Test](https://github.com/vmware-tanzu/sonobuoy/actions/workflows/ci-test.yaml/badge.svg)](https://github.com/vmware-tanzu/sonobuoy/actions/workflows/ci-test.yaml/badge.svg)
+[![Lint](https://github.com/vmware-tanzu/sonobuoy/actions/workflows/ci-lint.yaml/badge.svg)](https://github.com/vmware-tanzu/sonobuoy/actions/workflows/ci-lint.yaml/badge.svg)
+
+## [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
+
+Starting v0.20, Sonobuoy supports Kubernetes v1.17 or later. Sonobuoy releases will be independent of Kubernetes
+release, while ensuring that new releases continue to work functionally across different versions of Kubernetes. Read
+more about the new release cycles in [our blog][decoupling-sonobuoy-k8s].
+
+> 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].
+
+## Installation
+
+1. Download the [latest release][releases] for your client platform.
+2. Extract the tarball:
+
+   ```
+   tar -xvf <RELEASE_TARBALL_NAME>.tar.gz
+   ```
+
+   Move the extracted `sonobuoy` executable to somewhere on your `PATH`.
+
+## 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].
+
+## Docker Hub rate limit
+
+This year, Docker has started rate limiting image pulls from Docker Hub. We're planning a future release with a better
+user interface to work around this. Until then, this is the recommended approach.
+
+### Sonobuoy Pod
+
+Sonobuoy by default pulls from Docker Hub for [`sonobuoy/sonobuoy` image](https://hub.docker.com/r/sonobuoy/sonobuoy).
+If you're encountering rate limit on this, you can use VMware-provided mirror with:
+
+```bash
+sonobuoy run --sonobuoy-image projects.registry.vmware.com/sonobuoy/sonobuoy:<VERSION>
+```
+
+### Conformance
+
+Kubernetes end-to-end conformance test pulls several images from Docker Hub as part of testing. To override this, you
+will need to create a registry manifest file locally (e.g. `conformance-image-config.yaml`) containing the following:
+
+```yaml
+dockerLibraryRegistry: mirror.gcr.io/library
+```
+
+Then on running conformance:
+
+```bash
+sonobuoy run --sonobuoy-image projects.registry.vmware.com/sonobuoy/sonobuoy:<VERSION> --e2e-repo-config conformance-image-config.yaml
+```
+
+Technically `dockerGluster` is also a registry pulling from Docker Hub, but it's not part of Conformance test suite at
+the moment, so overriding `dockerLibraryRegistry` should be enough.
+
+## 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=<your.google.cloud.email@example.org>
+```
+
+### Run on Kubernetes for Docker Desktop
+
+We don't recommend running via a cluster set up via Docker Desktop. Known issues include:
+
+- `kubectl logs` will not function
+- `sonobuoy logs` will not function
+- `sonobuoy retrieve` will not function
+- `systemd-logs` plugin will hang
+
+Most of these issues revolve around issues with kube-proxy on Docker Desktop so if you know of how to resolve these
+issues, let us know.
+
+### Certified-Conformance bug (versions v0.53.0 and v0.53.1)
+
+These versions of Sonobuoy have a bug that runs the wrong set of tests without additional actions. See more
+details [here][issue1388]. The simplest way to avoid this is to update your version of Sonobuoy to >= v0.53.2.
+
+## 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.
+
+[decoupling-sonobuoy-k8s]: https://sonobuoy.io/decoupling-sonobuoy-and-kubernetes
+
+[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/main/CODE_OF_CONDUCT.md
+
+[contrib]: https://github.com/vmware-tanzu/sonobuoy/blob/main/CONTRIBUTING.md
+
+[docker]: https://docs.docker.com/get-docker/
+
+[docs]: https://sonobuoy.io/docs/v0.55.1
+
+[e2ePlugin]: e2eplugin
+
+[customPlugins]: plugins
+
+[gen]: gen
+
+[issue]: https://github.com/vmware-tanzu/sonobuoy/issues
+
+[issue1388]: issue1388
+
+[k8s]: https://github.com/kubernetes/kubernetes
+
+[linux]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#tabset-1
+
+[oview]: https://youtu.be/8QK-Hg2yUd4
+
+[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/content/docs/v0.55.1/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 k8s.gcr.io/conformance:$CLUSTER_VERSION
+docker tag k8s.gcr.io/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