sonobuoy

command module
v0.11.5-prerelease.5 Latest Latest
Warning

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

Go to latest
Published: Jul 26, 2018 License: Apache-2.0 Imports: 2 Imported by: 0

README

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.

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 master.
Package worker is responsible for the logic behind submitting results data back to a sonobuoy master.

Jump to

Keyboard shortcuts

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