Update docs #145
Merged
Update docs #145
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jesscodez
reviewed
Nov 14, 2017
docs/configuration.md
Outdated
| @@ -21,7 +21,7 @@ Once the configs are loaded (in either case), Sonobuoy parses them and gathers d | |||
| | | Overview|Path on Cluster Node|[STANDALONE]<br>JSON example(s)|[CONTAINERIZED]<br>YAML manifest example(s) | |||
| |---|---|---|---|---| | |||
| |*Data configuration*| What Sonobuoy records, how, and where. |*ANY of the following*:<br>(1) `config.json` in the directory where `sonobuoy` is executed<br>(2) `/etc/sonobuoy/config.json`<br>(3) `$SONOBUOY_CONFIG`<br><br>|[`config.json`][10]|<br> [`examples/ksonnet/components/10-configmaps.jsonnet`][11]<br><br>*The jsonnet file is basically a wrapper for the `config.json` file, which allows it to be properly mounted onto the cluster's Sonobuoy pod.* <br><br> | |||
| |*Plugin configuration*|Settings for each plugin integration.|*ANY of the following*:<br>(1) `/etc/sonobuoy/plugins.d`<br>(2) `$HOME/.sonobuoy/plugins.d`<br>(3) `./plugins.d`<br>(4) `PluginSearchPath` (override from the data configuration) <br><br>| There is a YAML config for each plugin:<br>(1) [`plugins.d/e2e.yaml`][16]<br>(2)[`plugins.d/systemdlogs.yaml`][17]|<br>[`examples/ksonnet/components/10-configmaps.jsonnet`][11]<br><br>*Same comment about the jsonnet file as above.* | |||
| |*Plugin configuration*|Settings for each plugin integration.|*ANY of the following*:<br>(1) `/etc/sonobuoy/plugins.d`<br>(2) `$HOME/.sonobuoy/plugins.d`<br>(3) `./plugins.d`<br>(4) `PluginSearchPath` (override from the data configuration) <br><br>| There is a YAML config for each plugin:<br>(1) [`plugins.d/e2e.tmpl`][16]<br>(2) [`plugins.d/systemd_logs.tmpl`][17]<br>(3) [`plugins.d/heptio-e2e.tmpl`][20]|<br>[`examples/ksonnet/components/10-configmaps.jsonnet`][11]<br><br>*Same comment about the jsonnet file as above.* | |||
There was a problem hiding this comment.
s/There is a YAML config/There is a templatized YAML config
docs/plugins.md
Outdated
|
|
||
| *This YAML is defined by the plugin **developer**, and can be taken as a given by the end user.* | ||
|
|
||
| The remainder of this document focuses on **Plugin Definition**. | ||
|
|
||
| ## Plugin Definition | ||
|
|
||
| The *plugin definition* is a YAML file (raw or wrapped in a ConfigMap) that describes the core parts of your custom plugin. It should contain the following fields: | ||
| The *plugin definition* is a YAML file (raw or wrapped in a ConfigMap) that describes the core parts of your custom plugin. Some of the values in this YAML file are template variables that will be filled in by sonobuoy. The template will have access to several variables: |
There was a problem hiding this comment.
Nit: s/several/the following
There was a problem hiding this comment.
additional nit: can you make the 2nd sentence a new paragraph for visibility?
There was a problem hiding this comment.
Following up on a previous comment, rephrase as follow:
The plugin definition is a YAML file (raw or wrapped in a ConfigMap) that describes the core parts of your custom plugin. This YAML defines a Kubernetes API resource like a Pod.
Some of the values in this YAML file are template variables that will be filled in by Sonobuoy. The template will have access to several variables:
docs/plugins.md
Outdated
| | `spec` | The Pod specification (e.g. network settings, container settings, volume definitions, etc.) | See [the parameter spec][4] below for reference. | | ||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `{{.SessionID}}` | SessionID is a generated token used to be able to uniquely identify all pieces of a single sonobuoy run. | |
There was a problem hiding this comment.
Nit: remove the <noun> is portion of each description
docs/plugins.md
Outdated
| | `driver` | Sonobuoy implements *plugin drivers* that define different modes of operation.<br><br>(1) **"Job" driver**: The plugin will run on a single node (e.g. master).<br>(2) **"DaemonSet" driver**: The plugin runs on each cluster node.<br><br>You can find the implementations [here][7]. | "Job|DaemonSet" | | ||
| | `resultType` | The name of the subdirectory that this plugin's results are saved in. With a `resultType` of "e2e", results are written into `plugins/e2e/...` (within the tarball output).<br><br>This value is typically the same as the plugin `name`. | "e2e" | | ||
| | `spec` | The Pod specification (e.g. network settings, container settings, volume definitions, etc.) | See [the parameter spec][4] below for reference. | | ||
| | Variable | Description | |
There was a problem hiding this comment.
To make it clearer which template variables are autofilled, could you add an additional column ("Source")?
And have the values be ("Autogenerated by Sonobuoy", "Populated from the PluginNamespace value in config.json", "Autogenerated by Sonobuoy")
docs/plugins.md
Outdated
|
|
||
| | Annotation | Description | Example Values | | ||
| | --- | --- | --- | | ||
| | `sonobuoy-driver` | Sonobuoy implements *plugin drivers* that define different modes of operation.<br><br>(1) **"Job" driver**: The plugin will run on a single node (e.g. master).<br>(2) **"DaemonSet" driver**: The plugin runs on each cluster node.<br><br>You can find the implementations [here][7]. | "Job|DaemonSet" | |
There was a problem hiding this comment.
Nit: s/The plugin will run on a single/The plugin runs on a single
docs/plugins.md
Outdated
| | Annotation | Description | Example Values | | ||
| | --- | --- | --- | | ||
| | `sonobuoy-driver` | Sonobuoy implements *plugin drivers* that define different modes of operation.<br><br>(1) **"Job" driver**: The plugin will run on a single node (e.g. master).<br>(2) **"DaemonSet" driver**: The plugin runs on each cluster node.<br><br>You can find the implementations [here][7]. | "Job|DaemonSet" | | ||
| | `sonobuoy-plugin` | A name that is used to identify the plugin (e.g. in the Plugin Selection described above). | "e2e", "systemd_logs" | |
There was a problem hiding this comment.
can you make "Plugin Selection" a link to "/docs/configuration.md#plugin-configuration"?
docs/plugins.md
Outdated
| | --- | --- | --- | | ||
| | `sonobuoy-driver` | Sonobuoy implements *plugin drivers* that define different modes of operation.<br><br>(1) **"Job" driver**: The plugin will run on a single node (e.g. master).<br>(2) **"DaemonSet" driver**: The plugin runs on each cluster node.<br><br>You can find the implementations [here][7]. | "Job|DaemonSet" | | ||
| | `sonobuoy-plugin` | A name that is used to identify the plugin (e.g. in the Plugin Selection described above). | "e2e", "systemd_logs" | | ||
| | `sonobuoy-result-type` | The name of the subdirectory that this plugin's results are saved in. With a `resultType` of "e2e", results are written into `plugins/e2e/...` (within the tarball output).<br><br>This value is typically the same as the plugin `name`. | "e2e" | |
There was a problem hiding this comment.
s/the plugin name/ the sonobuoy-plugin annotation
timothysc
added
area/documentation
jesscodez
reviewed
Nov 14, 2017
docs/plugins.md
Outdated
| @@ -19,22 +19,29 @@ There are two main components that specify plugin behavior: | |||
|
|
|||
| *These configs are defined by the **end user**.* | |||
|
|
|||
| 1. **Plugin Definition**: A structured YAML definition that describes a plugin's features, method of launch, and other configurations. | |||
| 1. **Plugin Definition**: A templatized YAML definition that describes a plugin's features, method of launch, and other configurations. | |||
There was a problem hiding this comment.
btw, for clarity, can you reword this:
Templatized YAML that defines a Kubernetes API resource like a Pod. Plugin metadata--such as a plugin's features, method of launch, and other configurations--are specified with annotations.
Signed-off-by: Chuck Ha <chuck@heptio.com>
jhamilton1
pushed a commit
to jhamilton1/sonobuoy
that referenced
this pull request
Jun 27, 2018
Update docs Signed-off-by: Jesse Hamilton jesse.hamilton@heptio.com
jhamilton1
pushed a commit
to jhamilton1/sonobuoy
that referenced
this pull request
Jun 27, 2018
Update docs Signed-off-by: Jesse Hamilton jesse.hamilton@heptio.com Signed-off-by: Jesse Hamilton jesse.hamilton@heptio.com
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Signed-off-by: Chuck Ha chuck@heptio.com