sonobuoy

README

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.

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 all upstream supported versions of Kubernetes (1.7.x-v1.9.y).

Prerequisites

• You should have access to an up-and-running Kubernetes cluster. If you do not have a cluster, follow the AWS Quickstart Kubernetes Tutorial to set one up with a single command.

• You should have kubectl installed. If not, follow the instructions for installing via Homebrew (MacOS) or building the binary (Linux).

• You should have an admin kubeconfig file installed, and KUBECONFIG environment variable set.

Getting Started

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.

Using the CLI

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

Prior to building the CLI, you will need to have golang properly installed on your machine. We recommend using gimme, with golang version 1.9.4.

Also, make certain that you update your $PATH settings appropriately:

$ export PATH=$GOROOT/bin:$GOPATH/bin:$PATH 

1. Download

Sonobuoy is written in golang and can easily be obtained by running:

$ go get -u -v github.com/heptio/sonobuoy

2. Run

Now you're ready to deploy a Sonobuoy pod to your cluster! Run the following command:

$ sonobuoy run

You can view actively running pods with the following command:

$ sonobuoy status 

To inspect the logs:

$ sonobuoy logs

To view the output, copy the output directory from the main Sonobuoy pod to somewhere local:

$ sonobuoy retrieve .

This should copy a single .tar.gz snapshot from the Sonobuoy pod into your local . directory. You can extract its contents into ./results with:

mkdir ./results; tar xzf *.tar.gz -C ./results

For information on the contents of the snapshot, see the documentation.

3. Cleanup

To clean up Kubernetes objects created by Sonobuoy, run the following command:

sonobuoy delete

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! 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 mailing list and 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.