This document describes the standard layout of a Sonobuoy results tarball, how it is formatted, and how data is named and laid out.
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.
The top-level directories in the results tarball look like this:
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/configzendpoint 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/healthzfor this host, for example{"status":200}
This looks like the following:
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 aUUIDfield in the root JSON, set to a randomly generated UUID created for that Sonobuoy run.
This looks like the following:
The /plugins directory contains output for each plugin selected for this Sonobuoy run:
-
/plugins/<plugin>/results.<format>- 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, using the format that the plugin expects. See file formats for details. -
/plugins/<plugin>/results/<hostname>.<format>- 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, using the format that the plugin expects. See file formats for details.
Some plugins can include several files as part of their results. The extracted files for these plugins comprise:
-
/plugins/<plugin>/results/<extracted files>- For plugins that collect cluster-wide data into a.tar.gzfile -
/plugins/<plugin>/<node>/<extracted files>- For plugins that collect per-node data into a.tar.gzfile
This looks like the following:
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:
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 lists the Kubernetes APIs that the cluster supports.
/serverversion.json contains the output from querying the server's version, including the major and minor version, git commit, etc.
For each type of result in a Sonobuoy tarball, the file extension indicates how the file should be parsed. This allows any automated system to ingest the contents of the Sonobuoy tarball, without precise knowledge of its directory layout.
.json- The file must be a valid JSON file, with either an array at the root ([...]), or a json object ({...}).txt- The file is treated as opaque text, and there is no reliable way for its contents to be parsed. This format is typically used for data intended to be read by humans..log- The file should be parsed as a series of log entries, one per line..xml- The file must be valid XML.