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. Brought to you by Heptio.
Go Makefile Other
timothysc Fix build goreleaser issues (#523)
Signed-off-by: Timothy St. Clair <timothysc@gmail.com>
Latest commit 62ccae4 Aug 10, 2018
Permalink
Failed to load latest commit information.
.github Fixes the recently merged issue templates to function properly Jul 2, 2018
cmd/sonobuoy/app Support GKE's weird 10+ versions (#506) Jul 24, 2018
docs Update links in plugin overview doc (#503) Jul 23, 2018
examples/plugins.d Update for daemonset plugins taints to land on every node (#509) Jul 26, 2018
pkg Bump to v0.11.6 Jul 31, 2018
scripts Cleanup of worker commands Feb 14, 2018
test/integration Update/Add all copyright headers Mar 6, 2018
vendor Fix build goreleaser issues (#523) Aug 10, 2018
.dockerignore Add .dockerignore Jul 27, 2017
.gitignore Fix Travis releases (#511) Jul 27, 2018
.goreleaser.yml Disable cgo for go relesaer (#430) May 21, 2018
.travis.yml Fix build goreleaser issues (#523) Aug 10, 2018
CODE_OF_CONDUCT.md Initial commit Jul 26, 2017
CONTRIBUTING.md reword authors in contributing.md Oct 11, 2017
Dockerfile add arm support for sonobuoy (#491) Jul 26, 2018
Gopkg.lock Fix build goreleaser issues (#523) Aug 10, 2018
Gopkg.toml Retrieve error handling (#453) Jul 9, 2018
LICENSE Initial commit Jul 26, 2017
Makefile Fix pushing minor version tags (#516) Jul 30, 2018
README.md Updates the readme to remove an old statement (#496) Jul 20, 2018
SUPPORT.md Add a support.md Aug 4, 2017
heptio-images-ee4b0474b93e.json.enc Fix Travis releases (#511) Jul 27, 2018
main.go Return exit code 1 when command not found Mar 7, 2018
travis-deploy.sh Travis CI has suggested a fix for the git pull issue (#513) Jul 30, 2018

README.md

Sonobuoy

Maintainers: Heptio

Build Status

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 Kubernetes versions 1.9 and later.

More information

The documentation provides further information about the conformance tests, plugins, etc.

Prerequisites

  • Access to an up-and-running Kubernetes cluster. If you do not have a cluster, we recommend following the AWS Quickstart for Kubernetes instructions.

Getting Started

The browser-based Sonobuoy Scanner tool is the quickest way to get started with Sonobuoy. Sonobuoy Scanner also provides a user-friendly way of viewing your scan results.

NOTE: Sonobuoy Scanner runs conformance tests only.

tarball overview screenshot

Using the CLI

Sonobuoy also provides a CLI that lets you run Sonobuoy on your cluster. By default, the CLI records the following results:

  • Information about your cluster's hosts, Kubernetes resources, and versions.
  • systemd logs from each host. Requires a plugin.
  • The results of a e2e conformance tests.

CLI Prerequisites

  • Golang installed. We recommend gimme, with golang version 1.9.4.

  • Your $PATH configured:

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

Download and run

Download the CLI by running:

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

Deploy a Sonobuoy pod to your cluster with:

$ sonobuoy run

View actively running pods:

$ 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 copies a single .tar.gz snapshot from the Sonobuoy pod into your local . directory. Extract the contents into ./results with:

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

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

Cleanup

To clean up Kubernetes objects created by Sonobuoy, run:

sonobuoy delete

Run on Google Cloud Platform (GCP)

Note that if you run Sonobuoy on a 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>

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

Changelog

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