diff --git a/Makefile b/Makefile index c876e539b..3ec827a68 100644 --- a/Makefile +++ b/Makefile @@ -187,4 +187,4 @@ deploy_kind: ./kind load docker-image $(REGISTRY)/$(TARGET):$(IMAGE_VERSION) || true native: - $(GO_BUILD) + $(GO_BUILD) \ No newline at end of file diff --git a/README.md b/README.md index 403d90a92..94ea16f37 100644 --- a/README.md +++ b/README.md @@ -135,26 +135,26 @@ welcome pull requests. Feel free to dig through the [issues][issue] and jump in. See [the list of releases][releases] to find out about feature changes. -[airgap]: docs/airgap.md +[airgap]: site/docs/master/airgap.md [brew]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-with-homebrew-on-macos [cncf]: https://github.com/cncf/k8s-conformance#certified-kubernetes [coc]: https://github.com/heptio/sonobuoy/blob/master/CODE_OF_CONDUCT.md [contrib]: https://github.com/heptio/sonobuoy/blob/master/CONTRIBUTING.md -[conformance]: docs/conformance-testing.md +[conformance]: site/docs/master/conformance-testing.md [docs]: https://github.com/heptio/sonobuoy/tree/master/docs -[e2e]: /docs/conformance-testing.md -[gen]: docs/gen.md +[e2e]: site/docs/master/conformance-testing.md +[gen]: site/docs/master/gen.md [gimme]: https://github.com/travis-ci/gimme [issue]: https://github.com/heptio/sonobuoy/issues [k8s]: https://github.com/kubernetes/kubernetes [linux]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#tabset-1 [oview]: https://youtu.be/k-P4hXdruRs?t=9m27s -[plugins]: docs/plugins.md +[plugins]: site/docs/master/plugins.md [quickstart]: https://aws.amazon.com/quickstart/architecture/vmware-kubernetes/ [releases]: https://github.com/heptio/sonobuoy/releases [slack]: https://kubernetes.slack.com/messages/sonobuoy -[snapshot]: docs/snapshot.md -[sonobuoyconfig]: docs/sonobuoy-config.md +[snapshot]: site/docs/master/snapshot.md +[sonobuoyconfig]: site/docs/master/sonobuoy-config.md [status]: https://travis-ci.org/heptio/sonobuoy.svg?branch=master [travis]: https://travis-ci.org/heptio/sonobuoy/# -[wait]: docs/wait.md \ No newline at end of file +[wait]: site/docs/master/wait.md \ No newline at end of file diff --git a/docs/enhancements/e2e-command-line.md b/docs/enhancements/e2e-command-line.md deleted file mode 100644 index 0179ea94c..000000000 --- a/docs/enhancements/e2e-command-line.md +++ /dev/null @@ -1,81 +0,0 @@ -# Sub Command for E2E Results Viewing - -## Table of Contents - -* [Summary](#summary) -* [Objectives](#objectives) - * [Goals](#goals) - * [Non-Goals](#non-goals) -* [Proposal](#proposal) - * [User Stories](#user-stories) -* [Unresolved Questions](#unresolved-questions) - -## Summary - -End to end (e2e) tests in the Kubernetes ecosystem are built on top of ginkgo -and output junit XML. XML is not designed for human readability and thus it is -very hard to grok. Users can use scanner but if they have results there is no -way for a user to upload those results to scanner to get the nice output. - -## Objectives - -Make the sonobuoy e2e output be more useful to users. - -### Goals - -- Output a list of e2e tests (filterable by passed/failed). -- Generate YAML that can rerun failed tests. - -### Non-Goals - -- Replace scanner.heptio.com -- Updating scanner features -- Re-implement gen -- Make a CLI per plugin. This is a special case that generates a lot of - questions and we think this will improve the user experience by a lot. - -## Proposal - -Add a subcommand to `sonobuoy` that has arguments/subcommands that satisfies the -goals above: - -`sonobuoy e2e ` will show a list of failed tests from -the sonobuoy archive file. - -`sonobuoy e2e --show=passed` will only display passed tests. - -`sonobuoy e2e --rerun-failed ` will figure out the failed -tests, build a dumb regex and pass that into Gen and pass that into run. - -## Prerequisite work - -* Gen will have to be able to generate the specific type of YAML we'd need for a - rerun. -* Run will have to be able to take a generic manifest and execute it. The - generation step will move into the cmd/run.go file. - -### User Stories - -#### Operator - -- An operator is playing with their cluster. Sonobuoy is telling them they have - failed some tests so they tweak some settings and want to try to run the - failed tests to see if they pass. - -Currently they would have to build their own YAML with a custom FOCUS variable. -This command line tool aims to simplify this workflow by producing the YAML they -need to rerun failed tests. - -#### Firewalled user - -- A user wants to have a nice experience looking at e2e test results but their - cluster cannot talk to an external network (scanner). Today they would have to - run sonobuoy and collect the xml and use a tool like xunit-viewer. - -This proposal aims to simplify their workflow by allowing them to use the -sonobuoy CLI to explore their results. - -## Unresolved Questions - - - diff --git a/docs/enhancements/sep-results-client.md b/docs/enhancements/sep-results-client.md deleted file mode 100644 index 5204010e0..000000000 --- a/docs/enhancements/sep-results-client.md +++ /dev/null @@ -1,78 +0,0 @@ -# Sonobuoy Results Client - -## Table of Contents - -* [Summary](#summary) -* [Objectives](#objectives) - * [Goals](#goals) - * [Non-Goals](#non-goals) -* [Proposal](#proposal) - * [User Stories](#user-stories) -* [Unresolved Questions](#unresolved-questions) - -## Summary - -Sonobuoy delivers results in a gzipped tar archive. The structure of the tar is -[documented here][tar structure] but programmatic access is up to every consumer -to implement. The structure of the results can change between versions and -consumer implementations become fragile. - -This proposal aims to describe a client library to help automate the analysis of -a Sonobuoy result artifact. - -## Objectives - -Provide a client library for easy access to data found in Sonobuoy results -across sonobuoy and Kubernetes versions. - -### Goals - - - Support all result files versions starting at v0.9.0. - - Provide basic access to kubernetes resources and plugin-generated files. - - Provide good access to Sonobuoy-generated data. - -### Non-Goals - -- Manage Kubernetes resource versioning. -- Customize the client library for every plugin written. -- There will be no support for tarballs before Sonobuoy version 0.9.0. - -## Proposal - -Define a set of functions that gives the consumer access to the underlying data -without exploding memory. See [the struct method definitions][struct] for a full -picture. - -### User Stories - -#### https://scanner.heptio.com - -- Scanner provides a user interface to Sonobuoy Results. It has to read through - tarballs generated by Sonobuoy and extract files and support multiple tarball - versions. It should not have to implement this custom logic and should be able - to leverage this client library. - -#### Custom plugin user - -- A user has developed a custom plugin and wants an easy way to get the data out - of the files their plugin has written. - -#### Results from various Sonobuy versions - -- A user has a collection of results across multiple versions of Sonobuoy and - wants to read the data without having to worry about the implementation of the - tarball schema directly. - -#### Resource Analysis - -- A user wants to analyze what's actually running on their cluster. They will - need a way to get at the resources that sonobuoy has found. - -## Unresolved Questions - -* None at this time. - -[tar structure]: https://github.com/heptio/sonobuoy/blob/master/docs/snapshot.md -[queries]: -https://github.com/heptio/sonobuoy/blob/master/pkg/discovery/queries.go -[struct]: https://github.com/chuckha/sonobuoy/blob/sep-1/client/ diff --git a/docs/enhancements/status-reporting.md b/docs/enhancements/status-reporting.md deleted file mode 100644 index 595a08aa6..000000000 --- a/docs/enhancements/status-reporting.md +++ /dev/null @@ -1,117 +0,0 @@ -# Status Reporting - - -**Table of Contents** - -- [Status Reporting](#status-reporting) - - [Summary](#summary) - - [Objective](#objective) - - [Goals](#goals) - - [Non-goals](#non-goals) - - [Proposal](#proposal) - - [For Sonobuoy Aggregator](#for-sonobuoy-aggregator) - - [For `sonobuoy status`](#for-sonobuoy-status) - - [Heartbeats (optional/future)](#heartbeats-optionalfuture) - - [User Stories](#user-stories) - - [Unresolved Questions](#unresolved-questions) - - - -## Summary - -Sonobuoy -- both `sonobuoy run` and through Scanner -- has really lackluster UX. -At present the tests will be kicked off and no information will be reported -until the run either succeeds or times out. This is not ideal. We would like to -have a concept of test status that can be reported, in near-real time, back to -the user running the service. Both the CLI and Scanner should be able to display -this progress in a way that makes sense for their individual UX. - -## Objective - -`sonobuoy run` and Scanner should report the status of an ongoing Sonobuoy test suite. -This status should be secure so only the intended audience can see it. - -### Goals - -* Create a command `sonobuoy status` that shows the results of an ongoing run. -* (optional) Workers can report their status to the aggregator - -### Non-goals - -* Actually updating Scanner is outside of our scope, though we should make sure - the API is useful to that team -* Complex metrics and monitoring. The first pass should be simple. -* Scanner support - -## Proposal - -### For Sonobuoy Aggregator - -An annotation will be attached to the sonobuoy pod, periodically updated by the -aggregation server. - -The annotation will be `sonobuoy.heptio.com/status`. - -```json -{ - "status": "running", - "plugins": [ - { - "name":"systemd", - "node": "node1", - "status": "complete" - }, - { - "name":"e2e", - "node": "", - "status": "running" - } - ] -} - -``` - -### For `sonobuoy status` - -`sonobuoy status` will use the kubeconfig acquisition logic from `sonobuoy run`, -then lookup the `sonobuoy` pod in the provided namespace. The status annotation can -then be decoded and displayed to the user. - -### Heartbeats (optional/future) - -The workers will set their own status annotations similar to the aggregators. -They will use the key `sonobuoy.heptio.com/status/worker` - -The aggregator will keep regularly collect and collate this information and use -it when reporting status to clients. - - -```json -{ - "status": "failed", - "plugins": [ - { - "name":"systemd", - "node": "node1", - "status": "running", - "last-heartbeat" "2008-09-15T15:53:00+05:00", - }, - { - "name":"e2e", - "node": "", - "status": "timed_out", - "last-heartbeat" "2008-09-15T15:53:00+05:00", - } - ] -} -``` - -### User Stories - -1. As a user running Sonobuoy, I want feedback on my ongoing runs -2. As a cluster admin, I want my cluster to fail early in the case of DNS or - Network misconfiguration - -## Unresolved Questions - -How useful will this status information actually be? Will it make it easier to diagnose failures? diff --git a/docs/enhancements/streamlined-templates.md b/docs/enhancements/streamlined-templates.md deleted file mode 100644 index 21e5b27a1..000000000 --- a/docs/enhancements/streamlined-templates.md +++ /dev/null @@ -1,225 +0,0 @@ -# Streamlined Templates - -## How it works now - -Currently, Sonobuoy plugins are large, sprawling YAML files. This works, but it -makes the boundary between Sonobuoy and the plugin very messy. - -By way of illustration, here is the current `heptio-e2e` plugin file. Every part -of user configuration is in green, all boilerplate required by Sonobuoy is in -red. - -```diff -- --- -- apiVersion: v1 -- kind: Pod -- metadata: -- annotations: -+ sonobuoy-driver: Job -+ sonobuoy-plugin: heptio-e2e -+ sonobuoy-result-type: heptio-e2e -- labels: -- component: sonobuoy -- sonobuoy-run: '{{.SessionID}}' -- tier: analysis -- name: sonobuoy-heptio-e2e-job-{{.SessionID}} -- namespace: '{{.Namespace}}' -- spec: -- containers: -+ - image: gcr.io/heptio-images/heptio-e2e:master -+ imagePullPolicy: Always -+ name: heptio-e2e -- volumeMounts: -- - mountPath: /tmp/results -- name: results -- readOnly: false -- - command: -- - sh -- - -c -- - /sonobuoy worker global -v 5 --logtostderr -- env: -- - name: NODE_NAME -- valueFrom: -- fieldRef: -- fieldPath: spec.nodeName -- - name: RESULTS_DIR -- value: /tmp/results -- - name: MASTER_URL -- value: '{{.MasterAddress}}' -- - name: RESULT_TYPE -- value: heptio-e2e -- image: gcr.io/heptio-images/sonobuoy:master -- imagePullPolicy: Always -- name: sonobuoy-worker -- volumeMounts: -- - mountPath: /tmp/results -- name: results -- readOnly: false -- restartPolicy: Never -- serviceAccountName: sonobuoy-serviceaccount -- tolerations: -- - effect: NoSchedule -- key: node-role.kubernetes.io/master -- operator: Exists -- - key: CriticalAddonsOnly -- operator: Exists -- volumes: -- - emptyDir: {} -- name: results -``` - -## Summary - -Removing this boiler plate will not just greatly simplify the process of making -a plugin. It will also allow us to make changes behind the scenes to the -Sonobuoy execution model without requiring updates to template files. - -All this boiler plate isn't just annoying. It paralyses changes to the Sonobuoy -execution model. Adding any new environment variables or metadata requires -changing all existing plugin definitions. - -## Objectives - -Replace the existing templates with a greatly streamlined one. - -### Goals -* Conceal the execution mechanics from users -* Allow seamless upgrading of Sonobuoy without user intervention - -### Non-goals -* Do not modify the done contract betweens producer and consumer container - -## Proposals - -### Proposal 1 - -An entirely new YAML-based file will be used for plugins. This will consist of -two sections: Metadata and container spec. - -```yaml -sonobuoy-config: - driver: Job - plugin-name: heptio-e2e - result-type: heptio-e2e -spec: - image: gcr.io/heptio-images/heptio-e2e:master - imagePullPolicy: Always - name: heptio-e2e - volumeMounts: - - mountPath: /tmp/results - name: results - readOnly: false -``` - -This will be merged into a larger Pod document provided by the Sonobuoy YAML -driver - -```yaml ---- -apiVersion: v1 -kind: Pod -metadata: - labels: - component: sonobuoy - sonobuoy-run: '{{.SessionID}}' - tier: analysis - name: sonobuoy-heptio-e2e-job-{{.SessionID}} - namespace: '{{.Namespace}}' -spec: - containers: - - {{.PluginContainerSpec}} - volumeMounts: - - mountPath: /tmp/results - name: results - readOnly: false - - command: - - sh - - -c - - /sonobuoy worker global -v 5 --logtostderr - env: - - name: NODE_NAME - valueFrom: - fieldRef: - fieldPath: spec.nodeName - - name: RESULTS_DIR - value: /tmp/results - - name: MASTER_URL - value: '{{.MasterAddress}}' - - name: RESULT_TYPE - value: heptio-e2e - image: gcr.io/heptio-images/sonobuoy:master - imagePullPolicy: Always - name: sonobuoy-worker - volumeMounts: - - mountPath: /tmp/results - name: results - readOnly: false - restartPolicy: Never - serviceAccountName: sonobuoy-serviceaccount - tolerations: - - effect: NoSchedule - key: node-role.kubernetes.io/master - operator: Exists - - key: CriticalAddonsOnly - operator: Exists - volumes: - - emptyDir: {} - name: results -``` - -#### Advantages: -* Simple substitution -* Can add additional fields later - -#### Disadvantages -* Not a Kubernetes API object -* Not as clear how it'll be executed - -### Proposal 2 - -In this scenario, the user provides a (templated) valid Kubernetes API Document. - -```yaml -apiVersion: v1 -kind: Pod -metadata: - annotations: - sonobuoy-driver: Job - sonobuoy-plugin: heptio-e2e - sonobuoy-result-type: heptio-e2e - labels: {{.SonobuoyLabels}} - name: sonobuoy-heptio-e2e-job-{{.SessionID}} - namespace: '{{.Namespace}}' -spec: - containers: - - image: gcr.io/heptio-images/heptio-e2e:master - imagePullPolicy: Always - name: heptio-e2e - {{.SonobuoyMount}} - - {{.SonobuoyConsumer}} - {{.SonobuySpecExtras}} -``` - -Then, at runtime, the template would be filled with values by the plugin driver. -These could be based on several templates themselves, or created at runtime out -of Go structs. - -#### Advantages -* Easier to see how the completed template will be finished -* Native (therefore familiar) Kubernetes object - -#### Disadvantages -* More boilerplate for plugin authors -* Template for plugin drivers is harder write/understand -* Extension points are fixed: No new Pod attributes could be added outsite of - `spec` or Labels. - -# Results - -Proposal 1 accepted. - -## User stories: - -1. As a power user, I would like to see the generated YAML for a plugin.yml file. -2. As a plugin author, I can write a simplified plugin.yml file -3. As an end user, I should see no changes as a result of this plugin work diff --git a/docs/enhancements/v2-worker-master.md b/docs/enhancements/v2-worker-master.md deleted file mode 100644 index 5faeab66a..000000000 --- a/docs/enhancements/v2-worker-master.md +++ /dev/null @@ -1,105 +0,0 @@ -# v2 Worker-Master communications - - -**Table of Contents** - -- [v2 Worker-Master communications](#v2-worker-master-communications) - - [How it works now](#how-it-works-now) - - [Summary](#summary) - - [Objectives](#objectives) - - [Goals](#goals) - - [Non-goals](#non-goals) - - [Proposal](#proposal) - - [User Stories](#user-stories) - - [Unresolved Questions](#unresolved-questions) - - - -## How it works now - -Sonobuoy uses a worker-master model, where a master delegates tasks to worker -pods. When those pods have finished, they need to report the results of their -work back to the master. Presently this is done over an ill-defined, ad hoc -REST-ish client/server model embedded in the server. - -The data passed back to the master is pretty much completely opaque. PUT -receives a path like /results/node1/systemd, and a blob of data as the body. -That data is written out, unexamined, to a file like node1/systemd in the -finished tarball. - -The worker is given JSON config blob which tells it where and how to report its -results. This contains, amongst other things, the URL of the master where those -results will be sent. - -The plugins themselves use a two-container model. One container, that created by -the plugin author, outputs its results in a shared directory. It touches a -`done` file with the name of the file it created. The other container is -responsible for submitting these results back to the master. It watches for the -`done` file, then uses the config JSON to `PUT` those results back to the -master. - -## Summary - -The interaction between the master and worker is ad hoc and poorly documented. -All data is also transmitted plain text over HTTP with no authentication or -verification. - -## Objectives - -Replace the existing, organically grown architecture with a mature, secure -solution that doesn't compromise the existing project's extensibility or -existing users. - -### Goals - -* Secure and authenticate the channel between the consumer and the producer -* Formalise and document the communication channel between the worker container - and the master -* Extract and clean up the worker client so other projects can vendor it - directly -* (Ancillary) Prevent simultaneous or poorly-cleaned up Sonobuoy runs from - interfering with each other -* Transition should be seamless for existing plugin authors - -### Non-goals - -* The `done` interface between the Producer and Consumer containers is not part -of this proposal. This contract is already used by public consumers outside the -control of Heptio. - -## Proposal - -My original proposal was to use GRPC, but given that we are submitting wholly -unstructured data this is likely overkill. - -Instead, the current URL (`/api/v1/results/by_node/:node_name/:plugin_name`, -`/api/v1/resutlts/global/:plugin_name`) will be kept. Instead of HTTP, though, -the results will communicate over mutual authentication TLS. The client will -authenticate the server by a vendored CA certificate, and the server will -authenticate the client through an individually assigned client certificates. - -The CA certificate and client certificate will be added to the JSON config blob -all nodes are defined, not baked into the images themselves. The node private -key will be transmitted as a Kubernetes secret. Every master run should create a -brand-new certificate authority and credentials. This ensures duplicate or -overlapping runs cannot interfere with each other. - -The code for communicating this information back will be isolated to a specific -package that other projects can use to write their own workers that don't use -our containers. - -### User Stories - -* As a Sonobuoy user, I want my tests to continue to work as they did before - this change was made -* As an existing Sonobuoy plugin author, it should take little to no work to - update my plugin -* As a new plugin author, it should be clear how I author a new plugin -* As an author of a new Go-based plugin, I should be able to directly use the - client library if I need to - -## Unresolved Questions - -* No Metadata other than node name and plug-in name is currently collected. If - at some point we wish to do this, there will not be any out-of-band way to - collect this other than URL parameters or headers. diff --git a/scripts/update_docs.sh b/scripts/update_docs.sh new file mode 100755 index 000000000..08b0058c4 --- /dev/null +++ b/scripts/update_docs.sh @@ -0,0 +1,76 @@ +#!/bin/bash + +set -x + +SCRIPTS_DIR="$( cd "$( dirname "$0" )" >/dev/null 2>&1 && pwd )" +DIR=$(cd $SCRIPTS_DIR; cd ..; pwd) +VERSION=$1 +TOC_NAME=$(echo ${VERSION}toc|sed s/\\./-/g) + +read -r -d '' CONFIG_VERSION_BLOCK << EOM +latest: v.* +versions: +- master +EOM + +read -r -d '' NEW_VERSION_BLOCK << EOM +latest: ${VERSION} +versions: +- master +- ${VERSION} +EOM + +read -r -d '' OLD_SCOPE_BLOCK << EOM + - scope: + path: docs\/master + values: + version: master + gh: https:\/\/github.com\/heptio\/sonobuoy\/tree\/master + layout: \"docs\" +EOM + +read -r -d '' NEW_SCOPE_BLOCK << EOM + - scope: + path: docs\/master + values: + version: master + gh: https:\/\/github.com\/heptio\/sonobuoy\/tree\/master + layout: \"docs\" + - scope: + path: docs\/${VERSION} + values: + version: ${VERSION} + gh: https:\/\/github.com\/heptio\/sonobuoy\/tree\/${VERSION} + layout: \"docs\" +EOM + +OLD_TOC_BLOCK="master: master-toc" +read -r -d '' NEW_TOC_BLOCK << EOM +master: master-toc +${VERSION}: ${TOC_NAME} +EOM + +OLD_FOOTER_BLOCK="cta_url: \/docs\/v.*" +NEW_FOOTER_BLOCK="cta_url: \/docs\/${VERSION}" + +if [ -z "${VERSION}" ] +then + echo "Should be called with version as first argument. No argument given, not creating docs." +else + docker run --rm \ + -v ${DIR}:/root \ + debian:stretch-slim \ + /bin/sh -c \ + "rm -rf /root/site/docs/${VERSION} && \ + cp -r /root/site/docs/master /root/site/docs/${VERSION} && \ + cp /root/README.md /root/site/docs/${VERSION}/README.md && \ + sed -i 's/site\/docs\/master\///g' /root/site/docs/${VERSION}/README.md && \ + sed -i 's/docs\/img/img/g' /root/site/docs/${VERSION}/README.md && \ + sed -i 's/sonobuoy\/tree\/master/sonobuoy\/tree\/${VERSION}/g' /root/site/docs/${VERSION}/README.md && \ + cp /root/site/_data/master-toc.yml /root/site/_data/${TOC_NAME}.yml && \ + perl -i -0pe 's/${CONFIG_VERSION_BLOCK}/${NEW_VERSION_BLOCK}/' /root/site/_config.yml && \ + perl -i -0pe 's/${OLD_SCOPE_BLOCK}/${NEW_SCOPE_BLOCK}/' /root/site/_config.yml && \ + perl -i -0pe 's/${OLD_TOC_BLOCK}/${NEW_TOC_BLOCK}/' /root/site/_data/toc-mapping.yml && \ + sed -i 's/\/docs\/v.*\"/\/docs\/${VERSION}\"/' /root/site/_includes/site-header.html && \ + sed -i 's/${OLD_FOOTER_BLOCK}/${NEW_FOOTER_BLOCK}/' /root/site/_config.yml" +fi \ No newline at end of file diff --git a/site/_config.yml b/site/_config.yml index a24e439c1..69e01dc70 100644 --- a/site/_config.yml +++ b/site/_config.yml @@ -14,7 +14,7 @@ footer: title: Getting Started content: To help you get started, see the documentation. cta_title: - cta_url: /docs/v0.14.3 + cta_url: /docs/v0.15.0 cta_text: Documentation vm-link: http://vmware.github.io/ @@ -49,6 +49,12 @@ defaults: version: master gh: https://github.com/heptio/sonobuoy/tree/master layout: "docs" + - scope: + path: docs/v0.15.0 + values: + version: v0.15.0 + gh: https://github.com/heptio/sonobuoy/tree/v0.15.0 + layout: "docs" - scope: path: docs/v0.14.3 values: @@ -85,9 +91,10 @@ collections: - casestudies versioning: true -latest: v0.14.3 +latest: v0.15.0 versions: - master +- v0.15.0 - v0.14.3 - v0.14.2 - v0.14.1 diff --git a/site/_data/toc-mapping.yml b/site/_data/toc-mapping.yml index 9590dd001..2cc9d9090 100644 --- a/site/_data/toc-mapping.yml +++ b/site/_data/toc-mapping.yml @@ -5,6 +5,7 @@ # Below is a commented out example of what this may look like: master: master-toc +v0.15.0: v0-15-0toc v0.14.3: v0-14-3toc v0.14.2: v0-14-2toc v0.14.1: v0-14-0toc diff --git a/site/_data/v0-15-0toc.yml b/site/_data/v0-15-0toc.yml new file mode 100644 index 000000000..066817976 --- /dev/null +++ b/site/_data/v0-15-0toc.yml @@ -0,0 +1,28 @@ +toc: + - title: Setting up + subfolderitems: + - page: Getting started + url: /index.html + - page: Config + url: /sonobuoy-config + - page: Snapshot layout + url: /snapshot + - page: ImagePullSecrects + url: /pullsecrets + - title: Use cases + subfolderitems: + - page: Conformance testing + url: /conformance-testing + - page: Custom Registries & Airgap Testing + url: /airgap + - page: Plugins + url: /plugins + - title: Next steps + subfolderitems: + - page: Customization + url: /gen + - page: Make your own plugins + url: /examples + github: true + - page: Cut a Release + url: /release \ No newline at end of file diff --git a/site/_includes/site-header.html b/site/_includes/site-header.html index 48a095c6a..d9254f819 100644 --- a/site/_includes/site-header.html +++ b/site/_includes/site-header.html @@ -7,7 +7,7 @@
  • Home
  • Blog
  • Community
    • -
  • Documentation
    • +
  • Documentation
  • Resources
    • diff --git a/site/docs/master/release.md b/site/docs/master/release.md index 4f73a5011..2dd0920c8 100644 --- a/site/docs/master/release.md +++ b/site/docs/master/release.md @@ -1,31 +1,106 @@ # Release -## Steps to cut a release - -1. Bump the version defined in the code. As of the time of writing it is in - `pkg/buildinfo/version.go`. -1. Commit and open/merge a pull request. -1. Create an annotated tag: `git tag -a v0.x.y -m "Release tag"`. -1. Push the tag with `git push --tags` (note this will push all tags). To push - just one tag do something like: `git push refs/tags/v0.13.0` where - `` refers to github.com/heptio/sonobuoy (this might be something like - `upstream` or `origin`). If you are unsure, use the first option. - - if there is a problem and you need to remove the tag use `git tag -d v0.x.y` and `git push origin refs/tags/v0.x.y` (assuming origin refers to github.com/heptio/sonobuoy) -1. Open a browser tab and go to: https://travis-ci.org/heptio/sonobuoy/builds - and verify go releaser for tag v0.x.y completes successfully -1. Upon successful completion of build job above, check the releases tab of - https://github.com/heptio/sonobuoy and verify the artifacts and changelog were published correctly. -1. Run the Jenkins job for pushing release images and manually run for the tag `v0.x.y` and confirm images get pushed correctly. -2. Update the release notes as desired on github. +## Preparing a new release + +1. Update the version defined in the code to the new version number. + As of the time of writing, the version is defined in `pkg/buildinfo/version.go`. +1. If the new release corresponds to a new Kubernetes release, the following steps must be performed: + * Add the new list of E2E test images. + For an example of the outcome of this process, see the [change corresponding to the Kubernetes v1.14 release](https://github.com/heptio/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 + ``` + This file will contain a function to return the list of test images for this new release. + 1. Update the name of the function in the newly created file. + For example, if the file is for the v1.15 release, ensure the function name is `v1_15`. + 1. Replace the map of images within the previously mentioned function with the map of images for the new release. + To do this, copy the equivalent map entries for the release from the Kubernetes repository. + For an example, see the entries [from the v1.15.0 release](https://github.com/kubernetes/kubernetes/blob/v1.15.0/test/utils/image/manifest.go#L202-L252). + Within the new function, remove any entries in the `config` map and replace with those copied from the Kubernetes repository. + The entries from the Kubernetes repository use an `int` as the key in the map however in the Sonobuoy repository the keys are strings. + Convert the new key names to strings. + 1. To make use of these new images, update the `GetImageConfigs` function within `pkg/image/manifest.go`. + Add a new case to the minor version check which will be the minor version of the new Kubernetes release. + In this new case, call the newly created function (e.g. `r.v1_15()`). + * Update the minimum and maximum Kubernetes API versions that Sonobuoy supports. + Edit `pkg/buildinfo/version.go` and update the `MinimumKubeVersion` to be 2 minor version below the new Kubernetes release version and update the `MaximumKubeVersion` to support future point releases. + 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" + ``` +1. Push the tag to the [`github.com/heptio/sonobuoy`](https://github.com/heptio/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) + upstream https://github.com/heptio/sonobuoy (fetch) + upstream https://github.com/heptio/sonobuoy (push) + ``` + For the following steps, use the remote configured for the `heptio/sonobuoy` repository. + The following instructions will use `upstream`. + * Push the tag with the following command. + > NOTE: This will push all tags. + + ``` + 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 + ``` + > NOTE: The `:` preceding the tag ref is necessary to delete the tag from the remote repository. + > Git refspecs have the format `<+>:`. + > By pushing an empty `src` to the remote `dst`, it makes the destination ref empty, effectively deleting it. + > For more details, see the [`git push` documentation](https://git-scm.com/docs/git-push) or [this concise explanation on Stack Overflow](https://stackoverflow.com/a/7303710). + +1. Open a browser tab and go to: https://travis-ci.org/heptio/sonobuoy/builds 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/heptio/sonobuoy/releases) and verify the artifacts and changelog were published correctly. +1. Run the [Jenkins job](https://jenkins.hepti.center/job/build-image-heptio-sonobuoy-release/build?delay=0sec) for pushing release images, specifying the release tag `v0.x.y` and confirm that the images get pushed correctly. +2. Update the release notes if desired on GitHub by editing the newly created release. ## Validation -1. Run the following command to make sure the image was pushed - correctly: `docker run -it gcr.io/heptio-images/sonobuoy:v0.x.y /sonobuoy version`. The output should - match the release tag above. -1. Go the the github release page (https://github.com/heptio/sonobuoy/releases) and download the release binaries and make sure the version matches the expected values. -2. Run a 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 testing with the new Kind images +1. Run the following command to make sure the image was pushed correctly: + ``` + docker run -it gcr.io/heptio-images/sonobuoy:v0.x.y /sonobuoy version + ``` + The `Sonobuoy Version` in the output should match the release tag above. +1. Go to the [GitHub release page](https://github.com/heptio/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 testing with the new Kind images by checking the output from: + ``` + export KUBECONFIG="$(kind get kubeconfig-path --name="kind")" + kubectl version --short + ``` + and verify that the server version matches the intended Kubernetes version. - you can run `sonobuoy images` and get a list of test images as expected +### Follow up +Following the release when the new tag is made, the documentation will need to be updated to include the new version. + +The changes for this can almost all be completed by running the command: +``` +./scripts/update_docs.sh v0.15.0 +``` + +This will copy the current master docs into the version given and update +a few of the links in the README to be correct. It will also update +the website config to add the new version and consider it the newest +version of the docs. + ### Notes -1. Before releasing, ensure all parties are available to resolve any issues that come up. If not, just bump the release. \ No newline at end of file +1. Before releasing, ensure all parties are available to resolve any issues that come up. If not, just bump the release. diff --git a/site/docs/v0.15.0/README.md b/site/docs/v0.15.0/README.md new file mode 100644 index 000000000..4b0cc6d55 --- /dev/null +++ b/site/docs/v0.15.0/README.md @@ -0,0 +1,160 @@ +# [![Build Status][status]][travis] + +## [Overview][oview] + +Sonobuoy is a diagnostic tool that makes it easier to understand the +state of a Kubernetes cluster by running a set of plugins (including [Kubernetes][k8s] conformance +tests) in an accessible and non-destructive manner. It is a customizable, +extendable, and cluster-agnostic way to generate clear, informative reports +about your cluster. + +Its selective data dumps of Kubernetes resource objects and cluster nodes allow +for the following use cases: + +* Integrated end-to-end (e2e) [conformance-testing][e2e] +* Workload debugging +* Custom data collection via extensible plugins + +Sonobuoy supports 3 Kubernetes minor versions: the current release and 2 minor versions before. Sonobuoy is currently versioned to track the Kubernetes minor version to clarify the support matrix. For example, Sonobuoy v0.14.x would support Kubernetes 1.14.x, 1.13.x, and 1.12.x. + +> Note: You can skip this version enforcement by running Sonobuoy with the `--skip-preflight` flag. + +## Prerequisites + +* Access to an up-and-running Kubernetes cluster. If you do not have a cluster, + we recommend following the [AWS Quickstart for Kubernetes][quickstart] instructions. + +* An admin `kubeconfig` file, and the KUBECONFIG environment variable set. + +* For some advanced workflows it may be required to have `kubectl` installed. See [installing via Homebrew (MacOS)][brew] or [building + the binary (Linux)][linux]. + +## Installing + +Download one of the releases directly from [here][releases]. + +Alternatively, you can install the CLI by running: + +``` +go get -u -v github.com/heptio/sonobuoy +``` + +Golang version 1.12 or greater is recommended. Golang can be installed via +[gimme][gimme]. + +## Getting Started +To launch conformance tests (ensuring [CNCF][cncf] conformance) and wait until they are finished run: +``` +sonobuoy run --wait +``` + +> Note: Using `--mode quick` will significantly shorten the runtime of Sonobuoy. It runs just a single test, helping to quickly validate your Sonobuoy and Kubernetes configuration. + +Get the results from the plugins (e.g. e2e test results): +``` +results=$(sonobuoy retrieve) +``` + +Inspect results for test failures. This will list the number of tests failed and their names: +``` +sonobuoy e2e $results +``` + +You can also extract the entire contents of the file to get much more [detailed data][snapshot] about your cluster. + +Sonobuoy creates a few resources in order to run and expects to run within its +own namespace. + +Deleting Sonobuoy entails removing it's namespace as well as a few cluster +scoped resources. + +``` +sonobuoy delete --wait +``` + +> Note: The --wait option ensures the Kubernetes namespace is deleted, avoiding conflicts if another Sonobuoy run is started quickly. + +### Monitoring Sonobuoy during a run +You can check on the status of each of the plugins running with: +``` +sonobuoy status +``` + +You can also inspect the logs of all Sonobuoy containers: +``` +sonobuoy logs +``` + +## More information + +[The documentation][docs] provides further information about: + * [conformance tests][conformance] + * [plugins][plugins] + * Testing of [air gapped clusters][airgap]. + * [Customization][gen] of YAML prior to running. + * The [Sonobuoy config file][sonobuoyconfig] file and how to edit it. + +## Troubleshooting + +If you encounter any problems that the documentation does not address, [file an +issue][issue]. + +## Known Issues + +### Leaked End-to-end namespaces + +There are some Kubernetes e2e tests that may leak resources. Sonobuoy can +help clean those up as well by deleting all namespaces prefixed with `e2e`: +``` +sonobuoy delete --all +``` + +### Run on Google Cloud Platform (GCP) + +Sonobuoy requires admin permissions which won't be automatic if you are running via Google Kubernetes Engine (GKE) cluster. You must first create an admin role for the user under which you run Sonobuoy: + +``` +kubectl create clusterrolebinding --clusterrole=cluster-admin --user= +``` + +## Contributing + +Thanks for taking the time to join our community and start contributing! We +welcome pull requests. Feel free to dig through the [issues][issue] and jump in. + +### Before you start + +* Please familiarize yourself with the [Code of Conduct][coc] before + contributing. +* See [CONTRIBUTING.md][contrib] for instructions on the developer certificate + of origin that we require. +* There is a [Slack channel][slack] if you want to + interact with other members of the community + +## Changelog + +See [the list of releases][releases] to find out about feature changes. + +[airgap]: airgap.md +[brew]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-with-homebrew-on-macos +[cncf]: https://github.com/cncf/k8s-conformance#certified-kubernetes +[coc]: https://github.com/heptio/sonobuoy/blob/master/CODE_OF_CONDUCT.md +[contrib]: https://github.com/heptio/sonobuoy/blob/master/CONTRIBUTING.md +[conformance]: conformance-testing.md +[docs]: https://github.com/heptio/sonobuoy/tree/v0.15.0/docs +[e2e]: conformance-testing.md +[gen]: gen.md +[gimme]: https://github.com/travis-ci/gimme +[issue]: https://github.com/heptio/sonobuoy/issues +[k8s]: https://github.com/kubernetes/kubernetes +[linux]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#tabset-1 +[oview]: https://youtu.be/k-P4hXdruRs?t=9m27s +[plugins]: plugins.md +[quickstart]: https://aws.amazon.com/quickstart/architecture/vmware-kubernetes/ +[releases]: https://github.com/heptio/sonobuoy/releases +[slack]: https://kubernetes.slack.com/messages/sonobuoy +[snapshot]: snapshot.md +[sonobuoyconfig]: sonobuoy-config.md +[status]: https://travis-ci.org/heptio/sonobuoy.svg?branch=master +[travis]: https://travis-ci.org/heptio/sonobuoy/# +[wait]: wait.md \ No newline at end of file diff --git a/docs/airgap.md b/site/docs/v0.15.0/airgap.md similarity index 100% rename from docs/airgap.md rename to site/docs/v0.15.0/airgap.md diff --git a/docs/conformance-testing.md b/site/docs/v0.15.0/conformance-testing.md similarity index 100% rename from docs/conformance-testing.md rename to site/docs/v0.15.0/conformance-testing.md diff --git a/docs/gen.md b/site/docs/v0.15.0/gen.md similarity index 99% rename from docs/gen.md rename to site/docs/v0.15.0/gen.md index 3df8a02d8..f89089cfb 100644 --- a/docs/gen.md +++ b/site/docs/v0.15.0/gen.md @@ -5,6 +5,7 @@ Sonobuoy provides many flags to customize your run but sometimes you have a spec The command `sonobuoy gen` will print the YAML for your run to stdout instead of actually creating it. It accepts all of the relevant flags for customizing the run just like `sonobuoy run` would. You can then edit it yourself and apply it as if Sonobuoy had run it. Output the YAML Sonobuoy would create to a file: + ``` sonobuoy gen --e2e-focus="sig-networking" --e2e-skip="Alpha" > sonobuoy.yaml ``` @@ -12,6 +13,7 @@ sonobuoy gen --e2e-focus="sig-networking" --e2e-skip="Alpha" > sonobuoy.yaml Then manually modify it as necessary. Maybe you need special options for plugins or want your own sidecar to be running with the images. Finally, create the resources yourself via kubectl. + ``` kubectl apply -f sonobuoy.yaml ``` diff --git a/docs/img/README.md b/site/docs/v0.15.0/img/README.md similarity index 100% rename from docs/img/README.md rename to site/docs/v0.15.0/img/README.md diff --git a/site/docs/v0.15.0/img/scanner.png b/site/docs/v0.15.0/img/scanner.png new file mode 100644 index 000000000..e3c5ebd6d Binary files /dev/null and b/site/docs/v0.15.0/img/scanner.png differ diff --git a/docs/img/snapshot-00-overview.png b/site/docs/v0.15.0/img/snapshot-00-overview.png similarity index 100% rename from docs/img/snapshot-00-overview.png rename to site/docs/v0.15.0/img/snapshot-00-overview.png diff --git a/docs/img/snapshot-10-resources.png b/site/docs/v0.15.0/img/snapshot-10-resources.png similarity index 100% rename from docs/img/snapshot-10-resources.png rename to site/docs/v0.15.0/img/snapshot-10-resources.png diff --git a/docs/img/snapshot-20-hosts.png b/site/docs/v0.15.0/img/snapshot-20-hosts.png similarity index 100% rename from docs/img/snapshot-20-hosts.png rename to site/docs/v0.15.0/img/snapshot-20-hosts.png diff --git a/docs/img/snapshot-30-podlogs.png b/site/docs/v0.15.0/img/snapshot-30-podlogs.png similarity index 100% rename from docs/img/snapshot-30-podlogs.png rename to site/docs/v0.15.0/img/snapshot-30-podlogs.png diff --git a/docs/img/snapshot-40-plugins.png b/site/docs/v0.15.0/img/snapshot-40-plugins.png similarity index 100% rename from docs/img/snapshot-40-plugins.png rename to site/docs/v0.15.0/img/snapshot-40-plugins.png diff --git a/docs/img/snapshot-50-meta.png b/site/docs/v0.15.0/img/snapshot-50-meta.png similarity index 100% rename from docs/img/snapshot-50-meta.png rename to site/docs/v0.15.0/img/snapshot-50-meta.png diff --git a/docs/img/sonobuoy-logo.png b/site/docs/v0.15.0/img/sonobuoy-logo.png similarity index 100% rename from docs/img/sonobuoy-logo.png rename to site/docs/v0.15.0/img/sonobuoy-logo.png diff --git a/docs/img/sonobuoy-plugins.png b/site/docs/v0.15.0/img/sonobuoy-plugins.png similarity index 100% rename from docs/img/sonobuoy-plugins.png rename to site/docs/v0.15.0/img/sonobuoy-plugins.png diff --git a/docs/plugins.md b/site/docs/v0.15.0/plugins.md similarity index 100% rename from docs/plugins.md rename to site/docs/v0.15.0/plugins.md diff --git a/docs/pullsecrets.md b/site/docs/v0.15.0/pullsecrets.md similarity index 97% rename from docs/pullsecrets.md rename to site/docs/v0.15.0/pullsecrets.md index f3f83e715..40b4b64da 100644 --- a/docs/pullsecrets.md +++ b/site/docs/v0.15.0/pullsecrets.md @@ -25,6 +25,7 @@ Sonobuoy does not have built in support for this, but it can be manually achieve As an example of how to create the secret you can follow the instructions [here][dockersecret] in order to create a secret in the default namespace. Then use copy most of its YAML via: + ``` kubectl get secret -o yaml > secret.json ``` @@ -38,4 +39,4 @@ Manually edit the file and remove/adjust the metadata as appropriate. The namesp Then just insert that YAML into the output from `sonobuoy gen` and run with `kubectl apply -f ...` -[dockersecret]: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ \ No newline at end of file +[dockersecret]: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ diff --git a/docs/release.md b/site/docs/v0.15.0/release.md similarity index 94% rename from docs/release.md rename to site/docs/v0.15.0/release.md index 8fe3d283e..2dd0920c8 100644 --- a/docs/release.md +++ b/site/docs/v0.15.0/release.md @@ -92,5 +92,15 @@ ### Follow up Following the release when the new tag is made, the documentation will need to be updated to include the new version. +The changes for this can almost all be completed by running the command: +``` +./scripts/update_docs.sh v0.15.0 +``` + +This will copy the current master docs into the version given and update +a few of the links in the README to be correct. It will also update +the website config to add the new version and consider it the newest +version of the docs. + ### Notes 1. Before releasing, ensure all parties are available to resolve any issues that come up. If not, just bump the release. diff --git a/docs/snapshot.md b/site/docs/v0.15.0/snapshot.md similarity index 99% rename from docs/snapshot.md rename to site/docs/v0.15.0/snapshot.md index 185b47bf6..a7e3459df 100644 --- a/docs/snapshot.md +++ b/site/docs/v0.15.0/snapshot.md @@ -18,11 +18,13 @@ This document describes retrieving the Sonobuoy results tarball, its layout, how 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 can be inspected without being extracted. It will list the number of tests failed and their names: + ``` sonobuoy e2e $output ``` diff --git a/docs/sonobuoy-config.md b/site/docs/v0.15.0/sonobuoy-config.md similarity index 100% rename from docs/sonobuoy-config.md rename to site/docs/v0.15.0/sonobuoy-config.md