diff --git a/docs/img/snapshot-00-overview.png b/docs/img/snapshot-00-overview.png new file mode 100644 index 000000000..379331dfb Binary files /dev/null and b/docs/img/snapshot-00-overview.png differ diff --git a/docs/img/snapshot-10-resources.png b/docs/img/snapshot-10-resources.png new file mode 100644 index 000000000..fd556ac6a Binary files /dev/null and b/docs/img/snapshot-10-resources.png differ diff --git a/docs/img/snapshot-20-hosts.png b/docs/img/snapshot-20-hosts.png new file mode 100644 index 000000000..166f2a2a9 Binary files /dev/null and b/docs/img/snapshot-20-hosts.png differ diff --git a/docs/img/snapshot-30-podlogs.png b/docs/img/snapshot-30-podlogs.png new file mode 100644 index 000000000..9de295723 Binary files /dev/null and b/docs/img/snapshot-30-podlogs.png differ diff --git a/docs/img/snapshot-40-plugins.png b/docs/img/snapshot-40-plugins.png new file mode 100644 index 000000000..dd1b59169 Binary files /dev/null and b/docs/img/snapshot-40-plugins.png differ diff --git a/docs/img/snapshot-50-meta.png b/docs/img/snapshot-50-meta.png new file mode 100644 index 000000000..efbb9be92 Binary files /dev/null and b/docs/img/snapshot-50-meta.png differ diff --git a/docs/snapshot.md b/docs/snapshot.md index 8936c7092..06e33f1f5 100644 --- a/docs/snapshot.md +++ b/docs/snapshot.md @@ -1,4 +1,4 @@ -NOTE: This documentation is a draft proposal for the structure of a Sonobuoy tarball and how it should be changed. This documentation does not represent the current state of a Sonobuoy tarball. +> NOTE: This documentation is a draft proposal for the structure of a Sonobuoy tarball and how it should be changed. This documentation does not represent the current state of a Sonobuoy tarball. - [Sonobuoy Snapshot Layout](#sonobuoy-snapshot-layout) - [Filename](#filename) @@ -23,6 +23,10 @@ Where YYYYmmDDHHMM is a timestamp containing the year, month, day, hour, and min ## Contents +The top-level directories in the results tarball look like the following: + +![tarball overview screenshot][3] + ### /resources The `/resources` directory contains JSON-serialized Kubernetes objects, taken from querying the Kubernetes REST API. The directory has the following structure: @@ -30,6 +34,10 @@ The `/resources` directory contains JSON-serialized Kubernetes objects, taken fr - `/resources/ns//.json` - For all resources that belong to a namespace, where `` is the namespace of that resource (eg. `kube-system`), and `` is the type of resource, pluralized (eg. `Pods`). - `/resources/cluster/.json` - For all resources that don't belong to a namespace, where `` is the type of resource, pluralized (eg. `Nodes`). +This looks like the following: + +![tarball resources screenshot][4] + ### /hosts The `/hosts` directory contains information gathered about each host in the system by directly querying their HTTP endpoints. *This is distinct from information you'd find in `/resources/cluster/Nodes.json`*, because it contains things like health and configuration for each host, which aren't part of the Kubernetes API objects. @@ -37,14 +45,22 @@ The `/hosts` directory contains information gathered about each host in the syst - `/hosts//configz.json` - Contains the output of querying the `/configz` endpoint for this host, that is the hosts's component configuration. - `/hosts//healthz.json` - Contains a json-formatted representation of the result of querying `/healthz` for this host, example: `{"status":200}` +This looks like the following: + +![tarball hosts screenshot][5] + ### /podlogs -NOTE: pod logs are currently distributed throughout the tarball in `/resources/ns//pods//.txt`. The proposal is to move them under a different directory so that "types" within a directory are consistent +> NOTE: pod logs are currently distributed throughout the tarball in `/resources/ns//pods//.txt`. The proposal is to move them under a different directory so that "types" within a directory are consistent The `/podlogs` directory contains logs for each pod found during the Sonobuoy run, similarly to what you would get with `kubectl logs -n `. - `/podlogs///.log` - Contains the logs for the each container, for each pod in each namespace. +This looks like the following: + +![tarball podlogs screenshot][6] + ### /plugins The `/plugins` directory contains output for each plugin selected for this Sonobuoy run. The structure is listed below. @@ -53,17 +69,25 @@ The `/plugins` directory contains output for each plugin selected for this Sonob - `/plugins//results/.` - For plugins that run once on every node to collect node-specific data (ones that use the DaemonSet driver, for instance), this will contain the results for this plugin, for each node, using the format that the plugin expects. See [file formats][2] for details. +This looks like the following: + +![tarball plugins screenshot][7] + ### /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"}` - - NOTE: this file is currently distributed throughout the tarball in `/resources/.../results.json`. Proposal is to move it here, and create other `.json` files under `/meta` if we start capturing other things than query time. + > NOTE: this file is currently distributed throughout the tarball in `/resources/.../results.json`. Proposal is to move it here, and create other `.json` files under `/meta` if we start capturing other things than query time. - `/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: + +![tarball meta screenshot][8] + ### /serverversion.json -NOTE: this is currently `/serverversion/serverversion.json`, proposal here is to just make it `/serverversion.json` +> NOTE: this is currently `/serverversion/serverversion.json`, proposal here is to just make it `/serverversion.json` `/serverversion.json` contains the output from querying the server's version, including the major and minor version, git commit, etc. @@ -78,3 +102,9 @@ For each type of result in a Sonobuoy tarball, the file extension should denote [1]: #meta [2]: #file-formats +[3]: img/snapshot-00-overview.png +[4]: img/snapshot-10-resources.png +[5]: img/snapshot-20-hosts.png +[6]: img/snapshot-30-podlogs.png +[7]: img/snapshot-40-plugins.png +[8]: img/snapshot-50-meta.png