Skip to content

Commit

Permalink
add screenshots
Browse files Browse the repository at this point in the history
Signed-off-by: Jessica Yao <jessica@heptio.com>
  • Loading branch information
Jessica Yao committed Aug 9, 2017
1 parent 22c16af commit 1456b81
Show file tree
Hide file tree
Showing 7 changed files with 34 additions and 4 deletions.
Binary file added docs/img/snapshot-00-overview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/img/snapshot-10-resources.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/img/snapshot-20-hosts.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/img/snapshot-30-podlogs.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/img/snapshot-40-plugins.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/img/snapshot-50-meta.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
38 changes: 34 additions & 4 deletions docs/snapshot.md
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -23,28 +23,44 @@ 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:

- `/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:

![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.

- `/hosts/<hostname>/configz.json` - Contains the output of querying the `/configz` endpoint for this host, that is the hosts's component configuration.
- `/hosts/<hostname>/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/<namespace>/pods/<podname>/<containername>.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/<namespace>/pods/<podname>/<containername>.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 <namespace> <pod> <container>`.

- `/podlogs/<namespace>/<podname>/<containername>.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.
Expand All @@ -53,17 +69,25 @@ The `/plugins` directory contains output for each plugin selected for this Sonob

- `/plugins/<plugin>/results/<hostname>.<format>` - 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.

Expand All @@ -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

0 comments on commit 1456b81

Please sign in to comment.