Project: Sonobuoy (Provisioning / Security & Compliance)
File: snapshot.md

- - - - This document describes retrieving the Sonobuoy results tarball, its layout, how it is formatted, and how data is named and laid out. 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 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 ``` A Sonobuoy snapshot is a gzipped tarball, named `YYYYmmDDHHMMsonobuoy<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 , 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 `/configz` endpoint for this host -- that is, the component configuration for the host.

- Contains a json-formatted representation of the result of querying `/healthz` for 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 a `UUID` field 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/<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: ! 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.