Repository files navigation

Sonobuoy is a diagnostic tool that makes it easier to understand the state of a Kubernetes cluster by running a set ofplugins (includingKubernetes conformance tests) in an accessible and non-destructive manner. It is acustomizable, 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

Starting v0.20, Sonobuoy supports Kubernetes v1.17 or later. Sonobuoy releases will be independent of Kubernetesrelease, while ensuring that new releases continue to work functionally across different versions of Kubernetes. Readmore about the new release cycles inour blog.

Note: You can skip this version enforcement by running Sonobuoy with the--skip-preflight flag.

• Access to an up-and-running Kubernetes cluster. If you do not have a cluster, we recommend either:

  • following theAWS Quickstart for Kubernetes instructions.
  • setting up a local cluster usingKinD

• An adminkubeconfig file, and the KUBECONFIG environment variable set.

• For some advanced workflows it may be required to havekubectl installed.Seeinstalling via Homebrew (MacOS) orbuilding the binary (Linux).

• Thesonobuoy images subcommand requiresDocker to be installed.Seeinstalling Docker.

The following methods exist for installing Sonobuoy:

1. Download thelatest release for your client platform.

2. Extract the tarball:

   tar -xvf <RELEASE_TARBALL_NAME>.tar.gz

   Move the extractedsonobuoy executable to somewhere on yourPATH.

1. Run the command:

   brew install sonobuoy

To launch conformance tests (ensuringCNCF 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: Theresults command has lots of useful options for various situations. See theresults page for more details.

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

If you have an issue with permissions in your cluster but you still want to run Sonobuoy, you can use--aggregator-permissions flag. Read more details about ithere.

By default,sonobuoy run runs the Kubernetes conformance tests but this can easily be configured. The same plugin thathas 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 thee2e plugin.

If you want to run other tests or tools which are not a part of the Kubernetes end-to-end suite, refer to ourdocumentation oncustom plugins.

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

If you encounter any problems that the documentation does not address,file an issue.

This year, Docker has started rate limiting image pulls from Docker Hub. We're planning a future release with a betteruser interface to work around this. Until then, this is the recommended approach.

Sonobuoy by default pulls from Docker Hub forsonobuoy/sonobuoy image.

Kubernetes end-to-end conformance test pulls several images from Docker Hub as part of testing. To override this, youwill need to create a registry manifest file locally (e.g.conformance-image-config.yaml) containing the following:

dockerLibraryRegistry:mirror.gcr.io/library

Then on running conformance:

sonobuoy run --sonobuoy-image sonobuoy/sonobuoy:<VERSION> --e2e-repo-config conformance-image-config.yaml

TechnicallydockerGluster is also a registry pulling from Docker Hub, but it's not part of Conformance test suite atthe moment, so overridingdockerLibraryRegistry should be enough.

There are some Kubernetes e2e tests that may leak resources. Sonobuoy can help clean those up as well by deleting allnamespaces prefixed withe2e:

sonobuoy delete --all

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>

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 theseissues, let us know.

These versions of Sonobuoy have a bug that runs the wrong set of tests without additional actions. See moredetailshere. The simplest way to avoid this is to update your version of Sonobuoy to >= v0.53.2.

See our currentstrategy document androadmap for context on what our highest priority use cases and work itemswill be. Feel free to make comments on Github or start conversations in Slack.

Thanks for taking the time to join our community and start contributing! We welcome pull requests. Feel free to digthrough theissues and jump in.

The most common build/test functions are called via the Makefile:

// Build the binary$ make build// Run local unit tests$ make test

If you make changes which change output, you may fail tests which utilize the golden file testing pattern (e.g. correct data is stored in external files), update them by running:

$ make golden

In most cases, running integration tests is more simply done in CI when you open a pull request.You can dig into scripts/build_funcs.sh and our .github/workflows/ci-test.yaml for exact details of existing test flows.

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

Seethe list of releases to find out about feature changes.