From a6420d5d93b3b4b9703ec32181234df772dbd6da Mon Sep 17 00:00:00 2001 From: Craig O'Donnell Date: Fri, 3 Nov 2023 09:30:20 -0400 Subject: [PATCH 1/7] note about KOTS support bundle spec discovery --- docs/vendor/support-bundle-helm-customizing.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/vendor/support-bundle-helm-customizing.mdx b/docs/vendor/support-bundle-helm-customizing.mdx index cef97e693a..905fbe278c 100644 --- a/docs/vendor/support-bundle-helm-customizing.mdx +++ b/docs/vendor/support-bundle-helm-customizing.mdx @@ -67,6 +67,8 @@ To create a Secret for the support bundle specification: 1. Add the Secret to your Helm chart `templates/` directory. +KOTS versions v1.104.0 and later will discover support bundle specs from Secrets and ConfigMaps deployed to the cluster that have the `troubleshoot.sh/kind: support-bundle` label. + Next, define the support bundle specification by adding collectors and analyzers. For more information, see [Define the Support Bundle Specification](#spec). ### Create a SupportBundle Custom Resource From c91f545a7a5dd8cba4e07e9209a0dfe289d17349 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Fri, 3 Nov 2023 14:55:25 -0600 Subject: [PATCH 2/7] docs edits and additions --- .../support-bundles/_generate-bundle.mdx | 31 ++++++++++++------- ...efining.mdx => preflight-helm-defining.md} | 15 ++++----- docs/vendor/preflight-kots-defining.md | 8 ++--- docs/vendor/support-bundle-generating.mdx | 10 ++---- ...mdx => support-bundle-helm-customizing.md} | 20 ++++++------ ...mdx => support-bundle-kots-customizing.md} | 1 - 6 files changed, 41 insertions(+), 44 deletions(-) rename docs/vendor/{preflight-helm-defining.mdx => preflight-helm-defining.md} (89%) rename docs/vendor/{support-bundle-helm-customizing.mdx => support-bundle-helm-customizing.md} (86%) rename docs/vendor/{support-bundle-kots-customizing.mdx => support-bundle-kots-customizing.md} (99%) diff --git a/docs/partials/support-bundles/_generate-bundle.mdx b/docs/partials/support-bundles/_generate-bundle.mdx index 36b3cba7a5..68854030f9 100644 --- a/docs/partials/support-bundles/_generate-bundle.mdx +++ b/docs/partials/support-bundles/_generate-bundle.mdx @@ -1,36 +1,45 @@ -Support bundles are generated from one or more support bundle specifications. Specification locations include YAML manifest files in the cluster, URLs, and Secrets or ConfigMap objects embedded in a Kubernetes cluster. For more information, see [Collecting a Support Bundle](https://troubleshoot.sh/docs/support-bundle/collecting/) and [Discover Cluster Specs](https://troubleshoot.sh/docs/support-bundle/discover-cluster-specs/) in the Troubleshoot documentation. +Support bundles are generated by providing one or more support bundle specifications with the `kubectl support-bundle` command. -The following examples show some possible CLI commands to generate a support bundle for one or more specifications and locations: +For installations with the Helm CLI or with KOTS v1.104.0 and later, specifications can be automatically discovered in Secrets or ConfigMap objects in the cluster using the `--load-cluster-specs` flag with the `kubectl support-bundle`. Alternatively, for installations with the Helm CLI or with KOTS versions earlier than 1.104.0, specifications can be provided from YAML files in the local directory or from a URL. -- Automatically discover specifications in the cluster that are contained in Secrets or ConfigMaps: +For a complete list of options with the `kubectl support-bundle` command, run `kubectl support-bundle --help`. For more information, see [Collecting a Support Bundle](https://troubleshoot.sh/docs/support-bundle/collecting/) and [Discover Cluster Specs](https://troubleshoot.sh/docs/support-bundle/discover-cluster-specs/) in the Troubleshoot documentation. + +The following lists some possible uses of the `kubectl support-bundle` CLI command to generate a support bundle from one or more specifications: + +- Discover all specifications defined in Secrets or ConfigMaps in the cluster: ```bash kubectl support-bundle --load-cluster-specs ``` -- Automatically discover specifications found in the cluster that match a custom label: + + :::note + The `--load-cluster-specs` flag is supported for Helm CLI installations and KOTS v1.104.0 or later. + ::: + +- Discover all specifications defined in Secrets or ConfigMaps in the cluster that match a custom label: ```bash kubectl support-bundle --load-cluster-specs -l LABEL ``` - Replace `LABEL` with the label name. + Where `LABEL` is the name of the custom label. -- Using one or more files: +- Provide one or more files that contain support bundle specifications: ```bash kubectl support-bundle ./PATH_TO_FILE1 ./PATH_TO_FILE2 ./PATH_TO_FILE3 ``` - Replace `PATH_TO_FILE` with the path and YAML file name for each file. + Where `PATH_TO_FILE` is the path and YAML file name for each file. -- Using a URL and a specification in the cluster: +- Provide one specification that is located at a URL and another specification located in the local directory: ```bash kubectl support-bundle URL \ ./PATH_TO_FILE ``` - Replace: + Where: - - `URL` with the online specification location provided by your vendor - - `PATH_TO_FILE` with the path and YAML file name \ No newline at end of file + - `URL` is the URL where the specification is located + - `PATH_TO_FILE` is the path and YAML file name \ No newline at end of file diff --git a/docs/vendor/preflight-helm-defining.mdx b/docs/vendor/preflight-helm-defining.md similarity index 89% rename from docs/vendor/preflight-helm-defining.mdx rename to docs/vendor/preflight-helm-defining.md index 9e5d4a3287..ad5fa5e7a9 100644 --- a/docs/vendor/preflight-helm-defining.mdx +++ b/docs/vendor/preflight-helm-defining.md @@ -23,23 +23,20 @@ A KOTS entitlement is required to create KOTS releases. Preflight checks are not included by default, so you must enable them. -For Helm installations, preflight checks run using a `helm template` command before running the installation to confirm the target cluster has the resources required for a successful installation. For more information about running the `helm install` command, see [Running Preflight Checks for Helm Installations](preflight-running). - -For KOTS installations with Helm charts, preflight checks run automatically. +For KOTS installations, preflight checks run automatically during installation. For Helm CLI installations, preflight checks run when the user runs a `helm template` command before they install the application. For more information, see [Running Preflight Checks for Helm Installations](preflight-running). ## Choose an Input Kind You run preflight checks with the open source preflight kubectl plugin. For information about the preflight plugin, see [Getting Started](https://troubleshoot.sh/docs/) in the open source Troubleshoot documentation. -The plugin requires a preflight check specification as input. For Helm installations, you provide this specification by running `helm template` to produce a stream of stdout and pipe the result to `preflight -`. The preflight plugin automatically finds and runs preflight specifications by filtering the stream of stdout for the following input kinds: +The plugin requires a preflight check specification as input. For Helm installations, this specification is provided by running `helm template` to produce a stream of stdout and piping the result to `preflight -`. The preflight plugin automatically finds and runs preflight specifications by filtering the stream of stdout. For KOTS installations, KOTS v1.101.0 and later automatically looks for preflights specified in the Helm chart archive. -- Secret (`kind: Secret`) -- ConfigMap (`kind: ConfigMap`) -- Preflight custom resource (`kind: Preflight`) +You can define preflight check specifications in the following input kinds: -All of these input options allow customization of preflight checks based on values unique to the customer, using Helm templates with conditional statements. +- Kubernetes Secret or ConfigMap +- Troubleshoot Preflight custom resource (`apiVersion: troubleshoot.sh/v1beta2` and `kind: Preflight`) -In KOTS v1.101.0 and later, a KOTS installation looks for the preflights specified in the Helm chart archive. +All of these input options allow customization of preflight checks based on values unique to the customer using Helm templates and conditional statements. ### Create a Secret (Recommended) diff --git a/docs/vendor/preflight-kots-defining.md b/docs/vendor/preflight-kots-defining.md index 4326be86a1..1f0c6663fe 100644 --- a/docs/vendor/preflight-kots-defining.md +++ b/docs/vendor/preflight-kots-defining.md @@ -15,13 +15,9 @@ For information about defining host preflight checks for Replicated kURL, see [C ## Define the Preflight Checks Specification -Preflight checks are not included by default, so you must enable them. For releases that use standard Kubernetes manifests or Kubernetes Operators, you add a Preflight custom resource to your release to define a specification for preflight checks. +Preflight checks are not included by default. For releases that use standard Kubernetes manifests or Kubernetes Operators, you can add a Preflight custom resource to your release to define preflight checks. -In the `spec:` of the Preflight custom resource, you define collectors and analyzers for the preflight checks that you want to add. - - - -The following is a template manifest file for the Preflight custom resource (`apiVersion: troubleshoot.sh/v1beta2` and `kind: Preflight`): +The following is an empty template for the Preflight custom resource (`apiVersion: troubleshoot.sh/v1beta2` and `kind: Preflight`): ```yaml apiVersion: troubleshoot.sh/v1beta2 diff --git a/docs/vendor/support-bundle-generating.mdx b/docs/vendor/support-bundle-generating.mdx index 3342b30cc9..1ad4fb8368 100644 --- a/docs/vendor/support-bundle-generating.mdx +++ b/docs/vendor/support-bundle-generating.mdx @@ -4,20 +4,16 @@ import GenerateBundle from "../partials/support-bundles/_generate-bundle.mdx" # Generating Support Bundles -For Helm and KOTS installations, support bundles can be generated using these CLI commands. +This topic describes how to use the support-bundle kubectl CLI plugin to generate support bundles. -:::note -For KOTS, using the admin console and additional CLI options are available. For more information, see [Generating Support Bundles](https://docs.replicated.com/enterprise/troubleshooting-an-app) in the KOTS documentation. -::: +For KOTS installations, users can also generate support bundles from the Replicated admin console. For more information, see [Generating Support Bundles](https://docs.replicated.com/enterprise/troubleshooting-an-app) in the KOTS documentation. ## Prerequisite +## Generate a Bundle from the CLI -## Generate a Bundle - -The following methods are supported for Helm installations and for KOTS version 1.94.2 and later. ## Generate a Bundle when a Helm Installation Fails diff --git a/docs/vendor/support-bundle-helm-customizing.mdx b/docs/vendor/support-bundle-helm-customizing.md similarity index 86% rename from docs/vendor/support-bundle-helm-customizing.mdx rename to docs/vendor/support-bundle-helm-customizing.md index 905fbe278c..d78ca311fe 100644 --- a/docs/vendor/support-bundle-helm-customizing.mdx +++ b/docs/vendor/support-bundle-helm-customizing.md @@ -9,9 +9,9 @@ import RedactorsAbout from "../partials/redactors/_redactors-about.mdx" import PreflightSbHelmTemplates from "../partials/preflights/_preflight-sb-helm-templates.mdx" -# Customize Support Bundles for Helm Installations +# Customize Support Bundles for Helm Charts -This topic provides a basic understanding and some key considerations about support bundle specifications for Helm installations to help guide you in defining them for your application. +This topic provides a basic understanding and some key considerations about support bundle specifications for Helm charts to help guide you in defining them for your application. The content in this topic applies to Helm chart-based applications installed with the Helm CLI or with Replicated KOTS v1.104.0 and later. ## About Support Bundles @@ -23,14 +23,16 @@ Customizing a support bundle is unique to your application and depends on what k ## Choose an Input Kind -You can create support bundle specifications using the following kinds: +Support bundles are generated with the open source support-bundle kubectl plugin by running `kubectl support-bundle`. For more information about the support-bundle plugin, see [Getting Started](https://troubleshoot.sh/docs/) in the open source Troubleshoot documentation. -- Secret (`kind: Secret`) -- SupportBundle custom resource (`kind: SupportBundle`) +The support-bundle plugin requires a support bundle specification as input. You can define support bundle specifications in using the following kinds of resources: + +- Kubernetes Secret or ConfigMap with `label.troubleshoot.sh/kind: support-bundle` +- SupportBundle custom resource (`apiVersion: troubleshoot.sh/v1beta2` and `kind: SupportBundle`) ### Create a Secret (Recommended) -Replicated recommends using Secrets to contain a support bundle specifications in your Helm chart. This method allows customers to automatically discover and generate a support bundle without specifying a long URL. Using Secrets also allows specifications to be templated using information in the `values.yaml` file. +Replicated recommends defining support bundle specifications in Secrets in your Helm chart templates. For installations with the Helm CLI or with KOTS v1.104.0 and later, defining specifications in Secrets allows your users to automatically discover and generate a support bundle without needing to provide multiple files or specify a long URL with the `kubectl support-bundle` command. Using Secrets also allows specifications to be templated using information in the `values.yaml` file. @@ -65,15 +67,13 @@ To create a Secret for the support bundle specification: analyzers: [] ``` -1. Add the Secret to your Helm chart `templates/` directory. - -KOTS versions v1.104.0 and later will discover support bundle specs from Secrets and ConfigMaps deployed to the cluster that have the `troubleshoot.sh/kind: support-bundle` label. +1. Add the Secret to your Helm chart `templates/` directory. Next, define the support bundle specification by adding collectors and analyzers. For more information, see [Define the Support Bundle Specification](#spec). ### Create a SupportBundle Custom Resource -If you do not want to use Secrets, you can create a SupportBundle custom resource instead. Helm templates are supported when the specification is distributed using an OCI registry. +If you do not want to use Secrets or ConfigMaps, you can create a SupportBundle custom resource instead. Create a SupportBundle custom resource (`kind: SupportBundle`) using the following basic support bundle template. For more information about this custom resource, see [Preflight and Support Bundle](/reference/custom-resource-preflight). diff --git a/docs/vendor/support-bundle-kots-customizing.mdx b/docs/vendor/support-bundle-kots-customizing.md similarity index 99% rename from docs/vendor/support-bundle-kots-customizing.mdx rename to docs/vendor/support-bundle-kots-customizing.md index 5f634fcee6..8db3a397ee 100644 --- a/docs/vendor/support-bundle-kots-customizing.mdx +++ b/docs/vendor/support-bundle-kots-customizing.md @@ -18,7 +18,6 @@ You can customize the default support bundle specification by adding, editing, o - ## Customize the Support Bundle Resource From 0ffb3a2ca002e15cf848705e5ab97f35d1ffafe4 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Fri, 3 Nov 2023 14:58:14 -0600 Subject: [PATCH 3/7] remove redundant note --- docs/partials/support-bundles/_generate-bundle.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/partials/support-bundles/_generate-bundle.mdx b/docs/partials/support-bundles/_generate-bundle.mdx index 68854030f9..368f924f33 100644 --- a/docs/partials/support-bundles/_generate-bundle.mdx +++ b/docs/partials/support-bundles/_generate-bundle.mdx @@ -12,10 +12,6 @@ The following lists some possible uses of the `kubectl support-bundle` CLI comma kubectl support-bundle --load-cluster-specs ``` - :::note - The `--load-cluster-specs` flag is supported for Helm CLI installations and KOTS v1.104.0 or later. - ::: - - Discover all specifications defined in Secrets or ConfigMaps in the cluster that match a custom label: ```bash From d0c350dc4451156ecfe2fb1561aa17e3ae3db56d Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Fri, 3 Nov 2023 15:03:32 -0600 Subject: [PATCH 4/7] revert changes to preflight topic for this pr --- docs/vendor/preflight-helm-defining.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/vendor/preflight-helm-defining.md b/docs/vendor/preflight-helm-defining.md index ad5fa5e7a9..9e5d4a3287 100644 --- a/docs/vendor/preflight-helm-defining.md +++ b/docs/vendor/preflight-helm-defining.md @@ -23,20 +23,23 @@ A KOTS entitlement is required to create KOTS releases. Preflight checks are not included by default, so you must enable them. -For KOTS installations, preflight checks run automatically during installation. For Helm CLI installations, preflight checks run when the user runs a `helm template` command before they install the application. For more information, see [Running Preflight Checks for Helm Installations](preflight-running). +For Helm installations, preflight checks run using a `helm template` command before running the installation to confirm the target cluster has the resources required for a successful installation. For more information about running the `helm install` command, see [Running Preflight Checks for Helm Installations](preflight-running). + +For KOTS installations with Helm charts, preflight checks run automatically. ## Choose an Input Kind You run preflight checks with the open source preflight kubectl plugin. For information about the preflight plugin, see [Getting Started](https://troubleshoot.sh/docs/) in the open source Troubleshoot documentation. -The plugin requires a preflight check specification as input. For Helm installations, this specification is provided by running `helm template` to produce a stream of stdout and piping the result to `preflight -`. The preflight plugin automatically finds and runs preflight specifications by filtering the stream of stdout. For KOTS installations, KOTS v1.101.0 and later automatically looks for preflights specified in the Helm chart archive. +The plugin requires a preflight check specification as input. For Helm installations, you provide this specification by running `helm template` to produce a stream of stdout and pipe the result to `preflight -`. The preflight plugin automatically finds and runs preflight specifications by filtering the stream of stdout for the following input kinds: -You can define preflight check specifications in the following input kinds: +- Secret (`kind: Secret`) +- ConfigMap (`kind: ConfigMap`) +- Preflight custom resource (`kind: Preflight`) -- Kubernetes Secret or ConfigMap -- Troubleshoot Preflight custom resource (`apiVersion: troubleshoot.sh/v1beta2` and `kind: Preflight`) +All of these input options allow customization of preflight checks based on values unique to the customer, using Helm templates with conditional statements. -All of these input options allow customization of preflight checks based on values unique to the customer using Helm templates and conditional statements. +In KOTS v1.101.0 and later, a KOTS installation looks for the preflights specified in the Helm chart archive. ### Create a Secret (Recommended) From 38dd21aad5962da4c1dfd20b55f847a39f661ed2 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 6 Nov 2023 14:12:35 -0700 Subject: [PATCH 5/7] edit wording --- docs/partials/support-bundles/_generate-bundle.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/partials/support-bundles/_generate-bundle.mdx b/docs/partials/support-bundles/_generate-bundle.mdx index 368f924f33..3a0f45f63f 100644 --- a/docs/partials/support-bundles/_generate-bundle.mdx +++ b/docs/partials/support-bundles/_generate-bundle.mdx @@ -1,6 +1,6 @@ Support bundles are generated by providing one or more support bundle specifications with the `kubectl support-bundle` command. -For installations with the Helm CLI or with KOTS v1.104.0 and later, specifications can be automatically discovered in Secrets or ConfigMap objects in the cluster using the `--load-cluster-specs` flag with the `kubectl support-bundle`. Alternatively, for installations with the Helm CLI or with KOTS versions earlier than 1.104.0, specifications can be provided from YAML files in the local directory or from a URL. +For installations with the Helm CLI or with KOTS, specifications can be provided from YAML files in the local directory or from a URL. Additionally, for installations with the Helm CLI or with KOTS v1.104.0 and later, specifications can be automatically discovered in Secrets or ConfigMap objects in the cluster using the `--load-cluster-specs` flag with the `kubectl support-bundle`. For a complete list of options with the `kubectl support-bundle` command, run `kubectl support-bundle --help`. For more information, see [Collecting a Support Bundle](https://troubleshoot.sh/docs/support-bundle/collecting/) and [Discover Cluster Specs](https://troubleshoot.sh/docs/support-bundle/discover-cluster-specs/) in the Troubleshoot documentation. From 904ba2f88302a7a6c4ffb9d9feee6f1aa88ec4ce Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 6 Nov 2023 14:53:13 -0700 Subject: [PATCH 6/7] add back in info about oci registry --- docs/vendor/support-bundle-helm-customizing.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/vendor/support-bundle-helm-customizing.md b/docs/vendor/support-bundle-helm-customizing.md index d78ca311fe..4b9577baf1 100644 --- a/docs/vendor/support-bundle-helm-customizing.md +++ b/docs/vendor/support-bundle-helm-customizing.md @@ -75,6 +75,10 @@ Next, define the support bundle specification by adding collectors and analyzers If you do not want to use Secrets or ConfigMaps, you can create a SupportBundle custom resource instead. +:::note +For specifications created in a SupportBundle custom resource, Helm templates are supported only when the support bundle is generated from a link to the specification at an OCI registry. For example, `kubectl support-bundle oci://my.oci.registry/image`. +::: + Create a SupportBundle custom resource (`kind: SupportBundle`) using the following basic support bundle template. For more information about this custom resource, see [Preflight and Support Bundle](/reference/custom-resource-preflight). ```yaml From 440f8958c6957cd1ca0f23fed9adf078fa13069a Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 7 Nov 2023 08:42:38 -0700 Subject: [PATCH 7/7] Update docs/partials/support-bundles/_generate-bundle.mdx Co-authored-by: Alex Parker <7272359+ajp-io@users.noreply.github.com> --- docs/partials/support-bundles/_generate-bundle.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/partials/support-bundles/_generate-bundle.mdx b/docs/partials/support-bundles/_generate-bundle.mdx index 3a0f45f63f..bf32ac627a 100644 --- a/docs/partials/support-bundles/_generate-bundle.mdx +++ b/docs/partials/support-bundles/_generate-bundle.mdx @@ -1,6 +1,6 @@ Support bundles are generated by providing one or more support bundle specifications with the `kubectl support-bundle` command. -For installations with the Helm CLI or with KOTS, specifications can be provided from YAML files in the local directory or from a URL. Additionally, for installations with the Helm CLI or with KOTS v1.104.0 and later, specifications can be automatically discovered in Secrets or ConfigMap objects in the cluster using the `--load-cluster-specs` flag with the `kubectl support-bundle`. +For installations with the Helm CLI or with KOTS, specifications can be provided from YAML files in the local directory or from a URL. Additionally, for installations with the Helm CLI or with KOTS v1.104.0 and later, specifications can be automatically discovered in Secret or ConfigMap objects in the cluster using the `--load-cluster-specs` flag with the `kubectl support-bundle`. For a complete list of options with the `kubectl support-bundle` command, run `kubectl support-bundle --help`. For more information, see [Collecting a Support Bundle](https://troubleshoot.sh/docs/support-bundle/collecting/) and [Discover Cluster Specs](https://troubleshoot.sh/docs/support-bundle/discover-cluster-specs/) in the Troubleshoot documentation.