Skip to content

Commit

Permalink
Bump version and docs for v0.54.0 release
Browse files Browse the repository at this point in the history 
Releasing as a new minor version since it has been 1.5 months
since a release and I think there are quite a few new features
and changes here.

Signed-off-by: John Schnake <[email protected]>
  • Loading branch information
@johnSchnake
johnSchnake committed Oct 11, 2021
1 parent b214bb7 commit 08bb70f
Show file tree
Hide file tree
Showing 28 changed files with 1,500 additions and 2 deletions.
2 changes: 1 addition & 1 deletion pkg/buildinfo/version.go
View file
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.53.2"
var Version = "v0.54.0"

// 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
3 changes: 2 additions & 1 deletion site/config.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,10 @@ params:
docs_search_index_name: index_name
docs_search_api_key: api_key
docs_versioning: true
docs_latest: v0.53.2
docs_latest: v0.54.0
docs_versions:
- main
- v0.54.0
- v0.53.2
- v0.53.1
- v0.53.0
Expand Down
252 changes: 252 additions & 0 deletions site/content/docs/v0.54.0/_index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,252 @@
---
version: v0.54.0
cascade:
layout: docs
gh: https://github.com/vmware-tanzu/sonobuoy/tree/v0.54.0
---
# ![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=<[email protected]>
```

### 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.54.0

[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
125 changes: 125 additions & 0 deletions site/content/docs/v0.54.0/airgap.md
View file
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 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
Loading

0 comments on commit 08bb70f

Please sign in to comment.