From b65502ffe57f7eca9fd0110bca3de16ed1e35f14 Mon Sep 17 00:00:00 2001 From: divolgin Date: Mon, 28 Sep 2020 17:51:58 -0700 Subject: [PATCH] Fix collectors and analyzer examples and commands --- .../kubernetes/analysis/cluster-version.md | 4 +- .../troubleshoot/kubernetes/analysis/crd.md | 4 +- .../kubernetes/analysis/defining-analyzers.md | 97 ++++++++++--------- .../kubernetes/analysis/image-pull-secrets.md | 4 +- .../kubernetes/analysis/ingress.md | 4 +- .../kubernetes/analysis/secrets.md | 4 +- .../kubernetes/analysis/storage-class.md | 4 +- .../kubernetes/collectors/cluster-info.md | 7 +- .../collectors/cluster-resources.md | 8 +- .../kubernetes/collectors/copy.md | 19 ++-- .../collectors/defining-collectors.md | 54 ++++++----- .../kubernetes/collectors/exec.md | 21 ++-- .../kubernetes/collectors/http.md | 34 ++++--- .../kubernetes/collectors/pod-logs.md | 21 ++-- .../troubleshoot/kubernetes/collectors/run.md | 24 +++-- .../kubernetes/getting-started/how-to-run.md | 2 +- .../kubernetes/support-bundle/collecting.md | 7 +- .../kubernetes/support-bundle/overview.md | 10 +- 18 files changed, 165 insertions(+), 163 deletions(-) diff --git a/content/docs/troubleshoot/kubernetes/analysis/cluster-version.md b/content/docs/troubleshoot/kubernetes/analysis/cluster-version.md index e703d63d3..5eeea1557 100644 --- a/content/docs/troubleshoot/kubernetes/analysis/cluster-version.md +++ b/content/docs/troubleshoot/kubernetes/analysis/cluster-version.md @@ -10,8 +10,8 @@ gradient: "blueToBlue" --- ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Preflight +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: check-kubernetes-version spec: diff --git a/content/docs/troubleshoot/kubernetes/analysis/crd.md b/content/docs/troubleshoot/kubernetes/analysis/crd.md index 007c31d5f..0694ebe7b 100644 --- a/content/docs/troubleshoot/kubernetes/analysis/crd.md +++ b/content/docs/troubleshoot/kubernetes/analysis/crd.md @@ -10,8 +10,8 @@ gradient: "blueToBlue" --- ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Preflight +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: preflight-sample spec: diff --git a/content/docs/troubleshoot/kubernetes/analysis/defining-analyzers.md b/content/docs/troubleshoot/kubernetes/analysis/defining-analyzers.md index fc6e4c90f..12df7597a 100644 --- a/content/docs/troubleshoot/kubernetes/analysis/defining-analyzers.md +++ b/content/docs/troubleshoot/kubernetes/analysis/defining-analyzers.md @@ -14,8 +14,8 @@ gradient: "blueToBlue" All analyzers are specified in a single YAML file. To build a set of analyzers, start with a Kubernetes YAML file: ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Analyzer +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: my-application-name spec: [] @@ -28,53 +28,54 @@ To add additional analyzers, read the docs in this section to understand each on For example, a complete spec might be: ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Analyzer +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: my-application-name spec: - - imagePullSecret: - checkName: Has Access to Quay.io - registryName: quay.io - outcomes: - - fail: - message: Cannot pull from quay.io - - pass: - message: Found credentials to pull from quay.io - - clusterVersion: - outcomes: - - fail: - when: "< 1.13.0" - message: Sorry, my-application-name requires at least Kubernetes 1.14.0. Please update your Kubernetes cluster before installing. - uri: https://enterprise.my-application.com/install/requirements/kubernetes - - warn: - when: "< 1.15.0" - message: The version of Kubernetes you are running meets the minimum requirements to run my-application-name. It's recommended to run Kubernetes 1.15.0 or later. - uri: https://enterprise.my-application.com/install/requirements/kubernetes - - pass: - message: The version of Kubernetes you have installed meets the required and recommended versions. - - storageClass: - checkName: Required storage classes - storageClassName: "microk8s-hostpath" - outcomes: - - fail: - message: The required storage class was not found in the cluster. - - pass: - message: The required storage class was found in the cluster. - - ingress: - namespace: default - ingressName: my-app-ingress - outcomes: - - fail: - message: Expected to find an ingress named "my-app-ingress". - - pass: - message: Expected ingress was found. - - customResourceDefinition: - customResourceDefinitionName: rook - outcomes: - - fail: - message: Rook is required for my-application. Rook was not found in the cluster. - - pass: - message: Found a supported version of Rook installed and running in the cluster. + analyzers: + - imagePullSecret: + checkName: Has Access to Quay.io + registryName: quay.io + outcomes: + - fail: + message: Cannot pull from quay.io + - pass: + message: Found credentials to pull from quay.io + - clusterVersion: + outcomes: + - fail: + when: "< 1.13.0" + message: Sorry, my-application-name requires at least Kubernetes 1.14.0. Please update your Kubernetes cluster before installing. + uri: https://enterprise.my-application.com/install/requirements/kubernetes + - warn: + when: "< 1.15.0" + message: The version of Kubernetes you are running meets the minimum requirements to run my-application-name. It's recommended to run Kubernetes 1.15.0 or later. + uri: https://enterprise.my-application.com/install/requirements/kubernetes + - pass: + message: The version of Kubernetes you have installed meets the required and recommended versions. + - storageClass: + checkName: Required storage classes + storageClassName: "microk8s-hostpath" + outcomes: + - fail: + message: The required storage class was not found in the cluster. + - pass: + message: The required storage class was found in the cluster. + - ingress: + namespace: default + ingressName: my-app-ingress + outcomes: + - fail: + message: Expected to find an ingress named "my-app-ingress". + - pass: + message: Expected ingress was found. + - customResourceDefinition: + customResourceDefinitionName: rook + outcomes: + - fail: + message: Rook is required for my-application. Rook was not found in the cluster. + - pass: + message: Found a supported version of Rook installed and running in the cluster. -``` + ``` diff --git a/content/docs/troubleshoot/kubernetes/analysis/image-pull-secrets.md b/content/docs/troubleshoot/kubernetes/analysis/image-pull-secrets.md index 283ffbbdc..8fc7ac301 100644 --- a/content/docs/troubleshoot/kubernetes/analysis/image-pull-secrets.md +++ b/content/docs/troubleshoot/kubernetes/analysis/image-pull-secrets.md @@ -10,8 +10,8 @@ gradient: "blueToBlue" --- ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Preflight +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: preflight-sample spec: diff --git a/content/docs/troubleshoot/kubernetes/analysis/ingress.md b/content/docs/troubleshoot/kubernetes/analysis/ingress.md index d8566bc2b..5343d8aeb 100644 --- a/content/docs/troubleshoot/kubernetes/analysis/ingress.md +++ b/content/docs/troubleshoot/kubernetes/analysis/ingress.md @@ -10,8 +10,8 @@ gradient: "blueToBlue" --- ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Preflight +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: preflight-sample spec: diff --git a/content/docs/troubleshoot/kubernetes/analysis/secrets.md b/content/docs/troubleshoot/kubernetes/analysis/secrets.md index 668444baa..0773593d0 100644 --- a/content/docs/troubleshoot/kubernetes/analysis/secrets.md +++ b/content/docs/troubleshoot/kubernetes/analysis/secrets.md @@ -13,8 +13,8 @@ By default, the collectors don't include secrets. This means that a preflight ch ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Preflight +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: preflight-sample spec: diff --git a/content/docs/troubleshoot/kubernetes/analysis/storage-class.md b/content/docs/troubleshoot/kubernetes/analysis/storage-class.md index 380bad001..369a7e276 100644 --- a/content/docs/troubleshoot/kubernetes/analysis/storage-class.md +++ b/content/docs/troubleshoot/kubernetes/analysis/storage-class.md @@ -10,8 +10,8 @@ gradient: "blueToBlue" --- ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Preflight +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: preflight-sample spec: diff --git a/content/docs/troubleshoot/kubernetes/collectors/cluster-info.md b/content/docs/troubleshoot/kubernetes/collectors/cluster-info.md index eb8ea7f50..a12503d3b 100644 --- a/content/docs/troubleshoot/kubernetes/collectors/cluster-info.md +++ b/content/docs/troubleshoot/kubernetes/collectors/cluster-info.md @@ -13,12 +13,13 @@ The cluster info collector is a default collector-- it will be automatically inc This collector does not accept any parameters. ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Collector +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: sample spec: - - clusterInfo: {} + collectors: + - clusterInfo: {} ``` ## Included resources diff --git a/content/docs/troubleshoot/kubernetes/collectors/cluster-resources.md b/content/docs/troubleshoot/kubernetes/collectors/cluster-resources.md index badbe7f67..7b49d92c9 100644 --- a/content/docs/troubleshoot/kubernetes/collectors/cluster-resources.md +++ b/content/docs/troubleshoot/kubernetes/collectors/cluster-resources.md @@ -13,12 +13,13 @@ The cluster resources colector is a default collector-- it will be automatically This collector does not accept any parameters. ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Collector +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: sample spec: - - clusterResources: {} + collectors: + - clusterResources: {} ``` ## Included resources @@ -226,4 +227,3 @@ This file contains information about all pods, separated by namespace. ### /cluster-resources/ingress/\/\.json This file contains information about all ingresses, separated by namespace. - diff --git a/content/docs/troubleshoot/kubernetes/collectors/copy.md b/content/docs/troubleshoot/kubernetes/collectors/copy.md index 8254d0332..f8c937951 100644 --- a/content/docs/troubleshoot/kubernetes/collectors/copy.md +++ b/content/docs/troubleshoot/kubernetes/collectors/copy.md @@ -12,17 +12,18 @@ The copy file collector is not automatically included. You need to specify it in ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Collector +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: sample spec: - - copy: - selector: - - app=api - namespace: default - containerPath: /etc/hosts - containerName: sidecar + collectors: + - copy: + selector: + - app=api + namespace: default + containerPath: /etc/hosts + containerName: sidecar ``` If containerName is not specified, the first container in the pod will be used. @@ -35,5 +36,3 @@ When this collector is executed, it will include the following files in a suppor ### /copy/\/\/\ This will contain the pod output (up to 10000 lines). - - diff --git a/content/docs/troubleshoot/kubernetes/collectors/defining-collectors.md b/content/docs/troubleshoot/kubernetes/collectors/defining-collectors.md index 8e10dae96..dd7e5e830 100644 --- a/content/docs/troubleshoot/kubernetes/collectors/defining-collectors.md +++ b/content/docs/troubleshoot/kubernetes/collectors/defining-collectors.md @@ -14,11 +14,12 @@ gradient: "blueToBlue" All collectors are specified in a single YAML file. To build a set of collectors, start with a Kubernetes YAML file: ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Collector +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: my-application-name -spec: [] +spec: + collectors: [] ``` The above file is a simple but valid support bundle spec. It will collect only the default data. @@ -28,30 +29,31 @@ To add additional collectors, read the docs in this section to understand each o For example, a complete spec might be: ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Collector +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: my-application-name spec: - - clusterInfo: {} - - clusterResources: {} - - logs: - selector: - - app=api - namespace: default - limits: - maxAge: 30d - maxLines: 1000 - - http: - name: healthz - get: - url: http://api:3000/healthz - - exec: - name: mysql-version - selector: - - app=mysql - namespace: default - command: ["mysql"] - args: ["-V"] - timeout: 5s + collectors: + - clusterInfo: {} + - clusterResources: {} + - logs: + selector: + - app=api + namespace: default + limits: + maxAge: 30d + maxLines: 1000 + - http: + name: healthz + get: + url: http://api:3000/healthz + - exec: + name: mysql-version + selector: + - app=mysql + namespace: default + command: ["mysql"] + args: ["-V"] + timeout: 5s ``` diff --git a/content/docs/troubleshoot/kubernetes/collectors/exec.md b/content/docs/troubleshoot/kubernetes/collectors/exec.md index 914abf0a6..9ddae84b5 100644 --- a/content/docs/troubleshoot/kubernetes/collectors/exec.md +++ b/content/docs/troubleshoot/kubernetes/collectors/exec.md @@ -13,19 +13,20 @@ Optional `exec` collectors can be defined to collect output from commands execut For example: ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Collector +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: sample spec: - - exec: - name: mysql-version - selector: - - app=mysql - namespace: default - command: ["mysql"] - args: ["-V"] - timeout: 5s + colectors: + - exec: + name: mysql-version + selector: + - app=mysql + namespace: default + command: ["mysql"] + args: ["-V"] + timeout: 5s ``` ## Response diff --git a/content/docs/troubleshoot/kubernetes/collectors/http.md b/content/docs/troubleshoot/kubernetes/collectors/http.md index 003e6b346..1f565d179 100644 --- a/content/docs/troubleshoot/kubernetes/collectors/http.md +++ b/content/docs/troubleshoot/kubernetes/collectors/http.md @@ -15,15 +15,16 @@ Optional `http` collectors can be defined to collect output from HTTP requests. The `GET` collector will issue an HTTP or HTTPS request to the specified URL. For example: ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Collector +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: sample spec: - - http: - name: healthz - get: - url: http://api:3000/healthz + colectors: + - http: + name: healthz + get: + url: http://api:3000/healthz ``` Fields supported in `GET` requests: @@ -36,19 +37,20 @@ Fields supported in `GET` requests: ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Collector +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: sample spec: - - http: - name: service-control - post: - url: https://api:3000/service-control - insecureSkipVerify: true - body: '{"disable-service": true}' - headers: - Content-Type: "application/json" + collectors: + - http: + name: service-control + post: + url: https://api:3000/service-control + insecureSkipVerify: true + body: '{"disable-service": true}' + headers: + Content-Type: "application/json" ``` - url diff --git a/content/docs/troubleshoot/kubernetes/collectors/pod-logs.md b/content/docs/troubleshoot/kubernetes/collectors/pod-logs.md index ddf088eef..6001f8dd9 100644 --- a/content/docs/troubleshoot/kubernetes/collectors/pod-logs.md +++ b/content/docs/troubleshoot/kubernetes/collectors/pod-logs.md @@ -12,19 +12,19 @@ The pod logs collector is not automatically included. You need to specify it in ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Collector +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: sample spec: - - logs: - selector: - - app=api - namespace: default - limits: - maxAge: 30d - maxLines: 1000 - + collectors: + - logs: + selector: + - app=api + namespace: default + limits: + maxAge: 30d + maxLines: 1000 ``` The selector attribute is a standard Kubernetes selector. It can match any labels. @@ -37,4 +37,3 @@ When this collector is executed, it will include the following files in a suppor ### /logs/\/\.txt This will be created for each pod that matches the selector. - diff --git a/content/docs/troubleshoot/kubernetes/collectors/run.md b/content/docs/troubleshoot/kubernetes/collectors/run.md index 2d5580516..e03baca9f 100644 --- a/content/docs/troubleshoot/kubernetes/collectors/run.md +++ b/content/docs/troubleshoot/kubernetes/collectors/run.md @@ -12,20 +12,20 @@ The run pod collector is not automatically included. You need to specify it in y ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Collector +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: sample spec: - - run: - name: ping-google - namespace: default - image: flungo/netutils - command: ["ping"] - args: ["www.google.com"] - timeout: 5s - imagePullPolicy: IfNotPresent - + collectors: + - run: + name: ping-google + namespace: default + image: flungo/netutils + command: ["ping"] + args: ["www.google.com"] + timeout: 5s + imagePullPolicy: IfNotPresent ``` The timeout will be 20 seconds or the timeout specified, whichever is shorter. @@ -38,5 +38,3 @@ When this collector is executed, it will include the following files in a suppor ### /run/\.txt This will contain the pod output (up to 10000 lines). - - diff --git a/content/docs/troubleshoot/kubernetes/getting-started/how-to-run.md b/content/docs/troubleshoot/kubernetes/getting-started/how-to-run.md index 4c8c867ce..f5ba7e65e 100644 --- a/content/docs/troubleshoot/kubernetes/getting-started/how-to-run.md +++ b/content/docs/troubleshoot/kubernetes/getting-started/how-to-run.md @@ -28,5 +28,5 @@ Support Bundles are designed to be run when something is wrong with an applicati Once the plugin is installed, you can generate a sample Support Bundle with: ```shell -kubectl troubleshoot https://troubleshoot.replicated.com +kubectl support-bundle https://support-bundle.replicated.com ``` diff --git a/content/docs/troubleshoot/kubernetes/support-bundle/collecting.md b/content/docs/troubleshoot/kubernetes/support-bundle/collecting.md index ecd30acbd..523f35591 100644 --- a/content/docs/troubleshoot/kubernetes/support-bundle/collecting.md +++ b/content/docs/troubleshoot/kubernetes/support-bundle/collecting.md @@ -14,15 +14,14 @@ Before you can collect a support bundle, you need to have a client-only componen If you have krew installed, the next step is to install the Troubleshoot plugin: ```shell -kubectl krew install troubleshoot -kubectl troubleshoot +kubectl krew install support-bundle +kubectl support-bundle ``` Once it's installed, you can test it by generating and downloading a sample support bundle: ```shell -kubectl troubleshoot https://troubleshoot.replicated.com +kubectl support-bundle https://support-bundle.replicated.com ``` This will connect to the cluster defined in your local kubecontext, and collect some basic information about the cluster. After it's finished, it will write a file named "support-bundle.tar.gz" to the current working directory. - diff --git a/content/docs/troubleshoot/kubernetes/support-bundle/overview.md b/content/docs/troubleshoot/kubernetes/support-bundle/overview.md index e7e76b65d..8f325a3da 100644 --- a/content/docs/troubleshoot/kubernetes/support-bundle/overview.md +++ b/content/docs/troubleshoot/kubernetes/support-bundle/overview.md @@ -24,14 +24,14 @@ An application vendor can write a set of collectors, which is a YAML file that d The basic format of a collector definition is a Kubernetes YAML that can be distributed with the application. The YAML will look like: ```yaml -apiVersion: troubleshoot.replicated.com/v1beta1 -kind: Collector +apiVersion: troubleshoot.sh/v1beta2 +kind: SupportBundle metadata: name: application-name spec: - - cluster-info: {} - - cluster-resources: {} + collectors: + - cluster-info: {} + - cluster-resources: {} ``` For a full list of options that can be included in a Kubernetes support bundle, visit the [Collectors](/docs/troubleshoot/kubernetes/collectors/collector-phase/) section. -