sonobuoy

command module
v0.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 19, 2019 License: Apache-2.0 Imports: 2 Imported by: 0

README

Build Status

Overview

Sonobuoy is a diagnostic tool that makes it easier to understand the state of a Kubernetes cluster by running a set of plugins (including 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 3 Kubernetes minor versions: the current release and 2 minor versions before. Sonobuoy is currently versioned to track the Kubernetes minor version to clarify the support matrix. For example, Sonobuoy v0.14.x would support Kubernetes 1.14.x, 1.13.x, and 1.12.x.

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

Prerequisites

Installing

Download one of the releases directly from here.

Alternatively, you can install the CLI by running:

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

Golang version 1.13 or greater is recommended. Golang can be installed via gimme.

Getting Started

To launch conformance tests (ensuring CNCF 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 e2e $results

You can also extract the entire contents of the file to get much more detailed 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 it's 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.

Monitoring Sonobuoy during a run

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

More information

The documentation provides further information about:

Troubleshooting

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

Known Issues

Leaked End-to-end namespaces

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

sonobuoy delete --all
Run on Google Cloud Platform (GCP)

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>

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 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.

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
cmd
pkg
buildinfo
Package buildinfo holds build-time information like the sonobuoy version.
Package buildinfo holds build-time information like the sonobuoy version.
client
Package client provides primitives for interacting with Sonobuoy and the results archive.
Package client provides primitives for interacting with Sonobuoy and the results archive.
client/results
Package results provides a low level API to extract data from a Sonobuoy result archive.
Package results provides a low level API to extract data from a Sonobuoy result archive.
client/results/e2e
package e2e defines files and directories found in the e2e plugin results.
package e2e defines files and directories found in the e2e plugin results.
plugin/aggregation
Package aggregation is responsible for hosting an HTTP server which aggregates results from all of the nodes that are running sonobuoy agent.
Package aggregation is responsible for hosting an HTTP server which aggregates results from all of the nodes that are running sonobuoy agent.
plugin/loader
Package loader is responsible for scanning for Plugin Definitions at runtime, and matching/loading them from a user's configuration.
Package loader is responsible for scanning for Plugin Definitions at runtime, and matching/loading them from a user's configuration.
worker
Package worker is responsible for the logic behind submitting results data back to a Sonobuoy aggregator.
Package worker is responsible for the logic behind submitting results data back to a Sonobuoy aggregator.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL