Sonobuoy Snapshot Layout

• Retrieving results
• Filename
• Contents
  • /hosts
  • /meta
  • /plugins
  • /podlogs
  • /resources
  • /servergroups.json
  • /serverversion.json

This document describes retrieving the Sonobuoy results tarball, its layout, how it is formatted, and how data is named and laid out.

Retrieving results

To view the output, copy the output directory from the aggregator Sonobuoy pod to your local machine (and save the name of the file to a variable for reference):

output=$(sonobuoy retrieve)

The results of plugins can be inspected without being extracted. By default, it will give you a human-readable report about the tests but also has options to list detailed information and even print raw files generated by the plugin. See the results page for more details.

sonobuoy results $output [--plugin <name>] [--mode report|detailed|dump]

You can also extract the output locally so that you can view the other information Sonobuoy gathered as well:

• detailed plugin results
• pod logs
• query results about the contents/state of your cluster

$ sonobuoy retrieve --extract

OR

$ output=$(sonobuoy retrieve --extract)
$ mkdir ./results; tar xzf $output -C ./results

Filename

A Sonobuoy snapshot is a gzipped tarball, named YYYYmmDDHHMM_sonobuoy_<uuid>.tar.gz.

where YYYYmmDDHHMM is a timestamp containing the year, month, day, hour, and minute of the run. The <uuid> string is an RFC4122 UUID, consisting of lowercase hexadecimal characters and dashes (e.g. “dfe30ebc-f635-42f4-9608-8abcd6311916”). This UUID should match the UUID from the snapshot’s meta/config.json, stored at the root of the tarball.

Contents

The top-level directories in the results tarball look like this:

/hosts

The /hosts directory contains the information gathered about each host in the system by directly querying their HTTP endpoints. This is different from what you find in /resources/cluster/Nodes.json – it contains items that aren’t part of the Kubernetes API objects:

• /hosts/<hostname>/configz.json - Contains the output of querying the /configz endpoint for this host – that is, the component configuration for the host.
• /hosts/<hostname>/healthz.json - Contains a json-formatted representation of the result of querying /healthz for this host, for example {"status":200}

This looks like the following:

/meta

The /meta directory contains metadata about this Sonobuoy run, including configuration and query runtime.

• /meta/query-time.json - Contains metadata about how long each query took, example: {"queryobj":"Pods","time":12.345ms"}
• /meta/config.json - A copy of the Sonobuoy configuration that was set up when this run was created, but with unspecified values filled in with explicit defaults, and with a UUID field in the root JSON, set to a randomly generated UUID created for that Sonobuoy run.

This looks like the following:

/plugins

The /plugins directory contains output for each plugin selected for this Sonobuoy run:

• /plugins/<plugin>/results/<files> - For plugins that run on an arbitrary node to collect cluster-wide data, for example using the Job driver. Contains the results for the plugin.

• /plugins/<plugin>/results/<hostname>/<files> - For plugins that run once on every node to collect node-specific data, for example using the DaemonSet driver. Contains the results for the plugin, for each node.

• /plugins/<plugin>/sonobuoy_results.yaml - A file generated by the server by post-processing the plugin results. This is the file that sonobuoy results relies on.

This looks like the following:

/podlogs

The /podlogs directory contains logs for each pod found during the Sonobuoy run, similar to what you get with kubectl logs -n <namespace> <pod> <container>.

• /podlogs/<namespace>/<podname>/<containername>.log - Contains the logs for each container, for each pod in each namespace.

This looks like the following:

/resources

The /resources directory lists JSON-serialized Kubernetes objects, taken from querying the Kubernetes REST API. The directory has the following structure:

• /resources/ns/<namespace>/<type>.json - For all resources that belong to a namespace, where <namespace> is the namespace of that resource (eg. kube-system), and <type> is the type of resource, pluralized (eg. Pods).
• /resources/cluster/<type>.json - For all resources that don’t belong to a namespace, where <type> is the type of resource, pluralized (eg. Nodes).

This looks like the following:

/servergroups.json

/servergroups.json lists the Kubernetes APIs that the cluster supports.

/serverversion.json

/serverversion.json contains the output from querying the server’s version, including the major and minor version, git commit, etc.