Sonobuoy
Maintainers: Heptio
Overview
Heptio 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. It is a customizable, extendable, and cluster-agnostic way to generate clear, informative reports about your cluster--regardless of your deployment details.
Its selective data dumps of Kubernetes resource objects and cluster nodes allow for the following use cases:
Supported Versions
NOTE: The table below only applies to the e2e conformance tests.
To ensure that your cluster is running the appropriate Kubernetes version for your Sonobuoy release, see the second column of the table below. Otherwise you may encounter the documented issues.
Sonobuoy Version / Conformance Version |
Required K8s Cluster Version |
Known Issues |
v0.9.0 / 1.8 |
>= 1.7 |
For earlier cluster versions (e.g. 1.6), some issues may exist. |
v0.8.0 / 1.7 |
N/A |
N/A |
Up and running
To easily get a Sonobuoy scan started on your cluster, use the browser-based Sonobuoy Scanner tool. Sonobuoy Scanner also provides a more user-friendly way of viewing your scan results.
Note that Sonobuoy Scanner runs conformance tests only. To learn how to run Sonobuoy with your own YAML files, which allows for further configuration and customization, see the Quickstart section below.
Quickstart
Heptio provides prebuilt Sonobuoy container images in its Google Container Registry (gcr.io/heptio-images). For the sake of faster setup on your cluster, this quickstart pulls from this registry to skip the container build process. You can use this same process to deploy Sonobuoy to production.
This guide executes a Sonobuoy run on your cluster, and records the following results:
- Basic info about your cluster's hosts, Kubernetes resources, and versions.
- (Via plugin)
systemd
logs from each host
- (Via plugin) The results of a single e2e conformance test ("Pods should be submitted and removed"). See the conformance guide for configuration details.
0. Prerequisites
1. Download
Clone or fork the Sonobuoy repo:
git clone git@github.com:heptio/sonobuoy.git
2. Run
Determine if your kube-apiserver
supports RBAC with the following command:
export RBAC_ENABLED=$(kubectl api-versions | grep "rbac.authorization.k8s.io/v1beta1" -c)
The environment variable you set here indicates whether RBAC-related resources should be included in the autogenerated, standalone YAML file. In an cluster running with --authorization-mode=RBAC
, these resources are required to allow Sonobuoy to run properly.
Generate the YAML example:
make generate
This should create examples/quickstart.yaml
.
To actually deploy a Sonobuoy pod to your cluster, run the following command in the Sonobuoy root directory:
kubectl apply -f examples/quickstart.yaml
You can view actively running pods with the following command:
kubectl get pods -l component=sonobuoy --namespace=heptio-sonobuoy
To verify that Sonobuoy has completed successfully, check the logs:
kubectl logs -f sonobuoy --namespace=heptio-sonobuoy
If you see the log line no-exit was specified, sonobuoy is now blocking
, the Sonobuoy pod has completed its data collection.
Notes:
-
The Sonobuoy pod in this example continues to run after it finishes data collection, due to the --no-exit
flag in its YAML manifest. This allows you to easily grab the results tarball.
-
Sonobuoy collects one data report per run---each time you want a new report you need to delete the existing Sonobuoy YAML files and reapply them (see the tear down step).
-
In practice, you should make sure that the Sonobuoy pod writes its results to a Persistent Volume. The quickstart example writes its output to an emptyDir
volume for simplicity.
Troubleshooting errors from kubectl logs
:
- If you are able to debug and resolve the issue on your own, make sure to delete and reapply Sonobuoy's YAML manifests. Otherwise, file an issue.
To view the output, copy the output directory from the main Sonobuoy pod to somewhere local:
kubectl cp heptio-sonobuoy/sonobuoy:/tmp/sonobuoy ./results --namespace=heptio-sonobuoy
This should copy a single .tar.gz
snapshot from the Sonobuoy pod into your local ./results
directory. You can extract its contents into /.results
with:
tar xzf ./results/*.tar.gz
For information on the contents of the snapshot, see the snapshot documentation.
NOTE: At this time, the layout of the contents of the tarball is subject to change.
3. Tear down
To clean up Kubernetes objects created by Sonobuoy, run the following command:
kubectl delete -f examples/quickstart.yaml
Further documentation
To learn how to configure your Sonobuoy runs and integrate plugins, see the /docs
directory.
Troubleshooting
If you encounter any problems that the documentation does not address, file an issue.
Contributing
Thanks for taking the time to join our community and start contributing!
Before you start
Pull requests
- We welcome pull requests. Feel free to dig through the issues and jump in.
Changelog
See the list of releases to find out about feature changes.