Skip to content

Commit

Permalink
Bump version to v0.17.2 and add docs (#1075)
Browse files Browse the repository at this point in the history
Signed-off-by: John Schnake <jschnake@vmware.com>
  • Loading branch information
johnSchnake authored Jan 28, 2020
1 parent f8c047f commit eb9343d
Show file tree
Hide file tree
Showing 26 changed files with 1,263 additions and 2 deletions.
2 changes: 1 addition & 1 deletion pkg/buildinfo/version.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 8 additions & 1 deletion site/_config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions site/_data/toc-mapping.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
32 changes: 32 additions & 0 deletions site/_data/v0-17-2toc.yml
Original file line number Diff line number Diff line change
@@ -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
180 changes: 180 additions & 0 deletions site/docs/v0.17.2/README.md
Original file line number Diff line number Diff line change
@@ -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=<your.google.cloud.email@example.org>
```

## 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
125 changes: 125 additions & 0 deletions site/docs/v0.17.2/airgap.md
Original file line number Diff line number Diff line change
@@ -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
Loading

0 comments on commit eb9343d

Please sign in to comment.