# Sonobuoy for Kubernetes: conformance testing and cluster diagnostics

> Sonobuoy runs Kubernetes conformance tests and custom plugins as pods inside a cluster, then packages the results into one retrievable archive. Here is how it installs, how a run works, and where it stops being the right tool.

**vmware-tanzu/sonobuoy** — 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 and other plugins in an accessible and non-destructive manner.

- Repository: https://github.com/vmware-tanzu/sonobuoy
- Website: https://sonobuoy.io
- Stars: 3,051 · Forks: 361
- Language: Go
- License: Apache-2.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/vmware-tanzu-sonobuoy

## The gap Sonobuoy fills between kubectl and a full e2e harness

Certifying that a Kubernetes distribution behaves like Kubernetes is not something kubectl can answer. The upstream end-to-end suite can, but running it by hand means vendoring test binaries, wiring a driver, and collecting output from dozens of pods. Sonobuoy wraps that work. The README describes it as a diagnostic tool that runs a set of plugins, including the Kubernetes conformance tests, "in an accessible and non-destructive manner", and lists three intended uses: integrated end-to-end conformance testing, workload debugging, and custom data collection through extensible plugins.

The audience is narrow and fairly senior. You need an admin kubeconfig with KUBECONFIG set, and the README points at AWS Quickstart or KinD if you have no cluster yet. This is a tool for platform engineers validating a distribution, for vendors preparing a conformance submission, and for anyone who has to explain why a cluster is misbehaving without shelling into every node. It is not a monitoring agent and it does not run continuously.

## Plugins, a namespace, and one tarball: how a Sonobuoy run is structured

A run is a small orchestration. Sonobuoy creates a few resources and expects to run inside its own namespace, and the aggregator is what holds the run together: the repository Dockerfile sets the container command to `/sonobuoy aggregator --no-exit -v 3 --logtostderr`. Plugins run as separate pods, report back to that aggregator, and the aggregator assembles their output into a single results archive that the client downloads.

The plugin model is the interesting design decision. The conformance tests ship as one plugin, but the README notes that the same plugin also carries the wider Kubernetes end-to-end suite, including storage tests, performance tests, scaling tests and provider-specific tests. Anything outside that suite goes through custom plugins. So the extension point is not a scripting hook bolted onto a fixed pipeline; it is the same mechanism the conformance tests use. The cost of that uniformity is that you configure plugin behaviour through Sonobuoy's own flags and config files rather than through whatever interface the underlying test binary already had.

On the client side, the codebase is a Go CLI built on cobra and viper, with client-go v0.27.1 against k8s.io/api v0.27.1. Since v0.20 the releases are decoupled from Kubernetes releases, and the README states Sonobuoy supports Kubernetes v1.17 or later, with the caveat that you can bypass version enforcement with `--skip-preflight`.

## Installing Sonobuoy and running your first conformance pass

Two install paths are documented. On macOS, Homebrew:

```bash
brew install sonobuoy
```

Everywhere else, download the release tarball for your client platform, extract it, and put the binary on your PATH:

```bash
tar -xvf <RELEASE_TARBALL_NAME>.tar.gz
```

The README does not pin a version in that command; you substitute the tarball you downloaded. After either path, `sonobuoy version` is the obvious sanity check, though the README does not document that subcommand.

A first real run is one command. This launches the conformance tests and blocks until they finish:

```bash
sonobuoy run --wait
```

If you only want to confirm that your Sonobuoy and Kubernetes configuration works before committing to a full suite, the README recommends `--mode quick`, which runs a single test and shortens the runtime significantly. While it is running, `sonobuoy status` shows each plugin, and `sonobuoy logs` prints the logs of all Sonobuoy containers.

When the run finishes, pull the archive and summarise it:

```bash
results=$(sonobuoy retrieve)
sonobuoy results $results
```

The results command lists the number of failed tests and their names. The README points out that it has further options and that the retrieved archive also contains much more detailed data about the cluster if you extract it. Cleanup is not optional: Sonobuoy creates cluster-scoped resources as well as its namespace, and removing them means running `sonobuoy delete --wait`. The `--wait` matters, because without it a follow-up run started quickly can collide with the namespace still being torn down.

## Docker Hub rate limits and the mirror config you will probably need

The most practical failure mode documented in the README is image pulling. Sonobuoy's own pod pulls `sonobuoy/sonobuoy` from Docker Hub by default, and the conformance suite pulls several more images from the same registry. Under Docker Hub rate limiting, a run can stall on image pulls rather than on tests.

The documented workaround is a local registry manifest file, for example `conformance-image-config.yaml`, containing a single key:

```yaml
dockerLibraryRegistry: mirror.gcr.io/library
```

You then pass it into the run along with an explicit Sonobuoy image:

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

The README notes that `dockerGluster` also pulls from Docker Hub but is not part of the conformance suite at the moment, so overriding `dockerLibraryRegistry` should be enough. Note the shape of that workaround: it is a file you maintain and a flag you must remember, not a default. The README also says a future release is planned with a better user interface for this, which is an admission that the current one is awkward.

## Where Sonobuoy is the wrong choice

The README is unusually direct about environments where it simply does not work. Running against a cluster set up via Docker Desktop is not recommended, and the listed symptoms are severe: `kubectl logs` will not function, `sonobuoy logs` will not function, `sonobuoy retrieve` will not function, and the `systemd-logs` plugin will hang. Since retrieve is how you get results at all, that combination makes the tool useless there. The README attributes most of it to kube-proxy on Docker Desktop.

Permissions are the second boundary. Sonobuoy needs admin access, and on GKE that is not automatic; you have to bind the cluster-admin role to your user first. There is a partial escape hatch in the `--aggregator-permissions` flag for clusters where permissions are restricted, and the README links to further detail rather than explaining it inline. If your organisation will not grant cluster-admin to a diagnostic tool, that flag is your only documented route, and the README does not describe what it changes.

There is also a known correctness trap in older releases. The README lists a certified-conformance bug affecting v0.53.0 and v0.53.1 that "runs the wrong set of tests" without additional configuration (the sentence is truncated in the README). The lesson is not that Sonobuoy is unreliable; it is that a conformance result is only as good as the client version that produced it, so record the version alongside the archive. Finally, e2e tests can leak resources. Sonobuoy cleans up namespaces prefixed with `e2e` via `sonobuoy delete --all`, which is a destructive command aimed at a naming convention, not at a tracked list.

## Sonobuoy against kubectl, kube-bench and the e2e binary directly

The honest alternative for many teams is not another product but the pieces Sonobuoy assembles. Running the Kubernetes e2e binary yourself gives you total control over which tests run, how they are parallelised and how output is stored, and it removes Sonobuoy's namespace and cluster-scoped resources from the picture. What you give up is the aggregator: you rebuild result collection, plugin fan-in and the single-archive output that `sonobuoy retrieve` provides.

A second comparison is with configuration and security scanners rather than test runners. Those inspect manifests, API objects or node configuration against a rule set and report violations. Sonobuoy does something different: it executes tests and collects data, and its README frames the output as selective dumps of Kubernetes resource objects and cluster nodes. A scanner tells you a setting is wrong; Sonobuoy tells you a test failed and hands you the cluster state around it. Teams often want both, and neither substitutes for the other.

Where Sonobuoy genuinely wins is portability across clusters. It is described as cluster-agnostic, the plugin interface is the same one the conformance suite uses, and a run reduces to one command plus one archive. If your problem is "produce a defensible conformance result on a cluster I do not own", the alternative is a bespoke harness you maintain yourself.

## Maintenance, licensing and what a Sonobuoy upgrade costs you

The repository is not archived, and the last push was on 2026-07-27. Releases are infrequent and irregular rather than steady: v0.57.5 on 2026-07-01, v0.57.3 on 2025-02-19, and v0.57.2 on 2024-08-29. That cadence is worth weighing. Sonobuoy is a diagnostic client that must keep pace with Kubernetes API changes, and the go.mod pins k8s.io/client-go at v0.27.1. Upgrading Sonobuoy is therefore not just a binary swap; you should re-run a conformance pass on the new version before trusting its output, precisely because of the kind of version-specific bug recorded for v0.53.0 and v0.53.1.

Licensing is Apache-2.0, the same licence as Kubernetes itself, which is the least surprising outcome for a CNCF-adjacent tool and keeps it usable in commercial distribution pipelines. That is a statement about the licence text in the LICENSE file, not legal advice; if you are redistributing a modified build, read the NOTICE and attribution requirements yourself.

Operational cost is mostly in the cluster, not the client. Each run creates a namespace and cluster-scoped resources, so a forgotten `sonobuoy delete --wait` leaves them behind. The conformance suite itself is heavy: it pulls many images, and without the mirror configuration described above it competes for Docker Hub pull quota. On a shared cluster, schedule the run rather than firing it off during peak hours.

## Conclusion

Adopt Sonobuoy if you need a CNCF conformance run or a repeatable cluster snapshot and you hold admin kubeconfig, because a single sonobuoy run --wait followed by sonobuoy retrieve gives you one archive instead of a hand-built test harness. Do not adopt it on Docker Desktop Kubernetes, where the README says logs, retrieve and the systemd-logs plugin all fail, and do not treat it as continuous monitoring: it creates a namespace per run and expects sonobuoy delete --wait afterwards. Before you commit, verify two things on the exact cluster you will certify: that your kubeconfig has cluster-admin, and whether Docker Hub rate limits force you to add an --e2e-repo-config file pointing at a mirror.

## FAQ

### What is Sonobuoy used for in Kubernetes?

It runs a set of plugins, including the Kubernetes conformance tests, against a cluster and produces a report. The README lists integrated end-to-end conformance testing, workload debugging and custom data collection as its use cases.

### How do I install Sonobuoy?

Download the release tarball for your client platform and extract it, or on macOS run brew install sonobuoy. Either way you need the binary on your PATH plus an admin kubeconfig with KUBECONFIG set.

### How do I run a quick Sonobuoy check instead of the full conformance suite?

The README recommends the --mode quick flag, which runs just a single test and significantly shortens the runtime, as a way to validate your Sonobuoy and Kubernetes configuration first.

### How do I clean up after a Sonobuoy run?

Run sonobuoy delete --wait, which removes the namespace and the cluster-scoped resources the run created. The --wait option ensures the namespace is gone, avoiding conflicts if another run starts soon after.

## Sources

- [License: Apache-2.0](https://github.com/vmware-tanzu/sonobuoy/blob/main/LICENSE)
- [Project website](https://sonobuoy.io)
- [README](https://github.com/vmware-tanzu/sonobuoy/blob/main/README.md)
- [Releases](https://github.com/vmware-tanzu/sonobuoy/releases)
- [vmware-tanzu/sonobuoy on GitHub](https://github.com/vmware-tanzu/sonobuoy)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vmware-tanzu-sonobuoy