From 83d59f25b6f89da7fdc83c08c9c9e0d72e90346e Mon Sep 17 00:00:00 2001 From: Bridget McErlean Date: Thu, 21 May 2020 16:23:23 -0400 Subject: [PATCH] Fix formatting on docs pages This fixes some of the formatting on the Sonobuoy config and Release docs pages. Signed-off-by: Bridget McErlean --- site/docs/master/release.md | 19 ++++- site/docs/master/sonobuoy-config.md | 112 +++++++++++++--------------- 2 files changed, 66 insertions(+), 65 deletions(-) diff --git a/site/docs/master/release.md b/site/docs/master/release.md index 19ba66df2..0e4fb7a84 100644 --- a/site/docs/master/release.md +++ b/site/docs/master/release.md @@ -18,6 +18,7 @@ working appropriately: For an example of the outcome of this process, see the [change corresponding to the Kubernetes v1.14 release](https://github.com/vmware-tanzu/sonobuoy/commit/68f15a260e60a288f91bc40347c817b382a3d45c). 1. Within `pkg/image/`, copy the latest `v1.x.go` file to a file which corresponds to the new Kubernetes release number. For example, if the new Sonobuoy release corresponds to Kubernetes `v1.15`, copy the `v1.14.go` file to `v1.15.go`. + ``` cp pkg/image/v1.{14,15}.go ``` @@ -46,6 +47,7 @@ working appropriately: For example, for the Kubernetes 1.15.0 release, the `MinimumKubeVersion` would become `1.13.0` and the `MaximumKubeVersion` would become `1.15.99`. 1. Commit and open/merge a pull request with these changes. 1. Create an annotated tag for the commit once the changes are merged: + ``` git tag -a v0.x.y -m "Release v0.x.y" ``` @@ -54,11 +56,13 @@ working appropriately: 1. Push the tag to the [`github.com/vmware-tanzu/sonobuoy`](https://github.com/vmware-tanzu/sonobuoy/) repository. * To ensure that the tag is pushed to the correct repository, check which remote corresponds to that repository using the following command: + ``` git remote -v ``` The output of this command should include at least two configured remotes, typically `origin`, which refers to your personal fork, and `upstream` which refers to the upstream Sonobuoy repository. For example: + ``` origin git@github.com:/sonobuoy.git (fetch) origin git@github.com:/sonobuoy.git (push) @@ -74,10 +78,12 @@ working appropriately: git push upstream --tags ``` To push just one tag, use the following command format (replacing `v0.x.y` with the tag created in the previous step): + ``` git push upstream refs/tags/v0.x.y ``` If there is a problem and you need to remove the tag, run the following commands: + ``` git tag -d v0.x.y git push upstream :refs/tags/v0.x.y @@ -92,6 +98,7 @@ working appropriately: 1. Open a browser tab and go to: https://circleci.com/gh/vmware-tanzu/sonobuoy and verify go releaser for tag v0.x.y completes successfully. 1. Upon successful completion of build job above, check the [releases tab of Sonobuoy](https://github.com/vmware-tanzu/sonobuoy/releases) and verify the artifacts and changelog were published correctly. 1. Run the following command to make sure the image was pushed correctly to [Docker Hub][dockerhub]: + ``` docker run -it sonobuoy/sonobuoy:v0.x.y /sonobuoy version ``` @@ -99,21 +106,27 @@ working appropriately: 1. Go to the [GitHub release page](https://github.com/vmware-tanzu/sonobuoy/releases) and download the release binaries and make sure the version matches the expected values. 2. Run a [Kind](https://github.com/kubernetes-sigs/kind) cluster locally and ensure that you can run `sonobuoy run --mode quick`. If this release corresponds to a new Kubernetes release as well, ensure: - - you're using the correct Kubernetes context by checking the output from: + + * you're using the correct Kubernetes context by checking the output from: + ``` kubectl config current-context ``` + and verifying that it is set to the context for the Kind cluster just created (`kind-kind` or `kind-`) - - you're testing with the new Kind images by checking the output from: + * you're testing with the new Kind images by checking the output from: + ``` kubectl version --short ``` + and verifying that the server version matches the intended Kubernetes version. - - you can run `sonobuoy images` and get a list of test images as expected + * you can run `sonobuoy images` and get a list of test images as expected 2. Update the release notes if desired on GitHub by editing the newly created release. ### Generating a new set of versioned docs The changes for this can almost all be completed by running the command: + ``` ./scripts/update_docs.sh v0.x.y ``` diff --git a/site/docs/master/sonobuoy-config.md b/site/docs/master/sonobuoy-config.md index a955d89e9..dc4d2d1c7 100644 --- a/site/docs/master/sonobuoy-config.md +++ b/site/docs/master/sonobuoy-config.md @@ -12,87 +12,75 @@ and you will see the default configuration. Below is a description of each of th ## General options -Description - - A string which provides consumers a way to add extra context to a configuration that may be in memory or saved to disk. Unused by Sonobuoy itself. +`Description`: A string which provides consumers a way to add extra context to a configuration that may be in memory or saved to disk. Unused by Sonobuoy itself. -UUID - - A unique identifier used to identify the run of this configuration. Used in a few places including the name of the results file. +`UUID`: A unique identifier used to identify the run of this configuration. Used in a few places including the name of the results file. -Namespace - - The namespace in which to run Sonobuoy. +`Namespace`: The namespace in which to run Sonobuoy. -WorkerImage - - The image for the Sonobuoy worker container which runs as a sidecar along the plugins. Responsible for reporting results back to the Sonobuoy aggregator. +`WorkerImage`: The image for the Sonobuoy worker container which runs as a sidecar along the plugins. Responsible for reporting results back to the Sonobuoy aggregator. -ImagePullPolicy - - The image pull policy to set on the Sonobuoy worker sidecars as well as each of the plugins. +`ImagePullPolicy`: The image pull policy to set on the Sonobuoy worker sidecars as well as each of the plugins. -ResultsDir - - The location on the Sonobuoy aggregator where the results are placed. +`ResultsDir`: The location on the Sonobuoy aggregator where the results are placed. -Version - - The version of Sonobuoy which created the configuration file. +`Version`: The version of Sonobuoy which created the configuration file. ## Plugin options -Plugins - - An array of plugin selection objects of the plugins you want to run. When running custom plugins (or avoiding running a particular plugin) this value needs modified. +`Plugins`: An array of plugin selection objects of the plugins you want to run. When running custom plugins (or avoiding running a particular plugin) this value needs modified. -PluginSearchPath - - The aggregator pod looks for plugin configurations in these locations. You shouldn't need to edit this unless you are doing development work on the aggregator itself. +`PluginSearchPath`: The aggregator pod looks for plugin configurations in these locations. You shouldn't need to edit this unless you are doing development work on the aggregator itself. ## Query options -Resources - - A list of resources which Sonobuoy will query for in every namespace in which it runs queries. In the namespace in which Sonobuoy is running, PodLogs, Events, and HorizontalPodAutoscalers are also added. - -Filters - - Namespace - - A regexp which specifies which namespaces to run queries against. - - LabelSelector - - A Kubernetes [label selector][labelselector] which will be added to every query run. - -Limits - - Options for limiting the scope of response. - - **Limits.PodLogs** limits the scope when getting logs from pods. The supported parameters are: - - **Namespaces**: string - - A regular expression for the targeted namespaces. - - Default is empty string - - To get logs from all namespaces use ".*" - - **SonobuoyNamespace**: bool - - If set to true, get pod logs from the namespace Sonobuoy is running in. Can be set along with a `Namespaces` field or on its own. - - Default value is true - - **FieldSelectors**: []string - - A list of field selectors, with OR logic. - - For example, to get logs from two specified namespaces - `FieldSelectors = ["metadata.namespace=default","metadata.namespace=heptio-sonobuoy"]` - - Each field selector contains one or more chained operators, with AND logic - - For example, to get logs from a specified pod - `FieldSelectors = ["metadata.namespace=default,metadata.name=pod1"]` - - Each field selector follows the same format as - `k8s.io/apimachinery/pkg/apis/meta/v1/types/ListOptions/FieldSelector` - - Can be set along with a Namespaces/SonobuoyNamespace field or on its own. - - **LabelSelector**: string - - Filtering candidate pods by their labels - - Using the same format as - `k8s.io/apimachinery/pkg/apis/meta/v1/types/ListOptions/LabelSelector` - - For example: - `LabelSelector = "app=nginx,layer in (frontend, backend)"` - - When set together with other fields, the scope of pods is defined by: +`Resources`: A list of resources which Sonobuoy will query for in every namespace in which it runs queries. In the namespace in which Sonobuoy is running, `PodLogs`, `Events`, and `HorizontalPodAutoscalers` are also added. + +`Filters`: Options for filtering which resources queries should be run against. + + * `Namespace`: A regexp which specifies which namespaces to run queries against. + * `LabelSelector`: A Kubernetes [label selector][labelselector] which will be added to every query run. + +`Limits`: Options for limiting the scope of response. + + * `PodLogs`: limits the scope when getting logs from pods. The supported parameters are: + + * `Namespaces`: string + + * A regular expression for the targeted namespaces. + * Default is empty string + * To get logs from all namespaces use ".*" + * `SonobuoyNamespace`: bool + + * If set to true, get pod logs from the namespace Sonobuoy is running in. Can be set along with a `Namespaces` field or on its own. + * Default value is true + * `FieldSelectors`: []string + + * A list of field selectors, with OR logic. + For example, to get logs from two specified namespaces `FieldSelectors = ["metadata.namespace=default","metadata.namespace=heptio-sonobuoy"]` + * Each field selector contains one or more chained operators, with AND logic + For example, to get logs from a specified pod `FieldSelectors = ["metadata.namespace=default,metadata.name=pod1"]` + * Each field selector follows the same format as a [Kubernetes Field Selector][fieldselector]. + * Can be set along with the `Namespaces` or `SonobuoyNamespace` field or on its own. + * `LabelSelector`: string + + * Filters candidate pods by their labels, using the same format as a [Kubernetes Label Selector][labelselector]. + For example: `LabelSelector = "app=nginx,layer in (frontend, backend)"` + * When set together with other fields, the scope of pods is defined by: ``` (Namespaces OR SonobuoyNamespace OR FieldSelectors) AND LabelSelector ``` - - - For each candidate pod, the format and size of logs is defined by other fields. These will be passed onto Kubernetes [PodLogOptions][podlogopts] - - Previous: bool - - SinceSeconds: int - - SinceTime: string. RFC3339 format. - - Timestamps: bool - - TailLines: int - - LimitBytes: int + * For each candidate pod, the format and size of logs are defined by other fields. These will be passed onto Kubernetes [PodLogOptions][podlogopts]: + * `Previous`: bool + * `SinceSeconds`: int + * `SinceTime`: string. RFC3339 format. + * `Timestamps`: bool + * `TailLines`: int + * `LimitBytes`: int +[fieldselector]: https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/ [labelselector]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ [podlogopts]: https://godoc.org/k8s.io/api/core/v1#PodLogOptions