Skip to content
Sonobuoy is a diagnostic tool that makes it easier to understand the state of a Kubernetes cluster by running a set of Kubernetes conformance tests in an accessible and non-destructive manner.
Go CSS HTML Ruby JavaScript Shell Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Tweaks to CI (#964) Oct 15, 2019
.github Fixes the recently merged issue templates to function properly Jul 2, 2018
cmd/sonobuoy/app Make timeouts more clear (#938) Oct 11, 2019
examples Update repo throughout codebase (#924) Sep 30, 2019
pkg Sleep forever after systemd logs plugin finishes (#971) Oct 21, 2019
scripts Update github org in one of our scripts (#960) Oct 15, 2019
site Add older blog posts and author images (#958) Oct 11, 2019
test Unity integration testing and remove Travis (#949) Oct 10, 2019
.dockerignore Add .dockerignore Jul 27, 2017
.gitignore Move to go modules (#935) Oct 7, 2019
.goreleaser.yml Update repo throughout codebase (#924) Sep 30, 2019
CODE_OF_CONDUCT.md Initial commit Jul 26, 2017
CONTRIBUTING.md Remove unnecessary legacy branding (#873) Sep 12, 2019
Dockerfile add arm support for sonobuoy (#491) Jul 26, 2018
LICENSE Initial commit Jul 26, 2017
Makefile Unity integration testing and remove Travis (#949) Oct 10, 2019
README.md Improve docs organization and E2E descriptions (#951) Oct 11, 2019
go.mod Move to go modules (#935) Oct 7, 2019
go.sum Move to go modules (#935) Oct 7, 2019
heptio-images-c14f11347d8b.json.enc Add image building/pushing back to Travis (#835) Aug 14, 2019
kind-config.yaml Update our registry to dockerhub and use our latest kind-node (#927) Oct 2, 2019
main.go Update repo throughout codebase (#924) Sep 30, 2019
netlify.toml Adding in Jekyll site May 16, 2019

README.md

CircleCI

Overview

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 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
  • 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

Installing

We recommend installing Sonobuoy via downloading one of the releases directly from here.

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 conformance) and wait until they are finished run:

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):

results=$(sonobuoy retrieve)

Inspect results for test failures. This will list the number of tests failed and their names:

sonobuoy results $results

Note: The results command has lots of useful options for various situations. See the results page for more details.

You can also extract the entire contents of the file to get much more detailed data 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.

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.

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.

Monitoring Sonobuoy during a run

You can check on the status of each of the plugins running with:

sonobuoy status

You can also inspect the logs of all Sonobuoy containers:

sonobuoy logs

Troubleshooting

If you encounter any problems that the documentation does not address, file an 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:

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:

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 and jump in.

Before you start

  • Please familiarize yourself with the Code of Conduct before contributing.
  • See CONTRIBUTING.md for instructions on the developer certificate of origin that we require.
  • There is a Slack channel if you want to interact with other members of the community

Changelog

See the list of releases to find out about feature changes.

You can’t perform that action at this time.