Merge pull request #2551 from replicatedhq/110162

Add Embedded Cluster support bundle to support bundle docs

docs/enterprise/troubleshooting-an-app.mdx

@@ -1,45 +1,30 @@
 import InstallPlugin from "../partials/support-bundles/_install-plugin.mdx"
 import GenerateBundle from "../partials/support-bundles/_generate-bundle.mdx"
 import GenerateBundleAdminConsole from "../partials/support-bundles/_generate-bundle-admin-console.mdx"
-import GenerateBundleCliAdminConsole from "../partials/support-bundles/_generate-bundle-cli-admin-console.mdx"
-import GenerateBundleHost from "../partials/support-bundles/_generate-bundle-host.mdx"
-import GenerateBundleDefaultKots from "../partials/support-bundles/_generate-bundle-default-kots.mdx"
 
 
-# Generating Support Bundles
+# Generating Support Bundles for KOTS Installations
 
-The Replicated KOTS Admin Console includes a Troubleshoot page where you can generate an analysis and review remediation suggestions for troubleshooting an application. You can download a support bundle to share with your vendor.
+This topic describes how to generate support bundles for applications installed with Replicated KOTS.
 
-Alternatively, you can generate a support bundle using the support-bundle CLI. For embedded clusters created with Replicated kURL, you can also generate a host support bundle.
-
-## Generate a Support Bundle using the Admin Console
+## Generate a Bundle from the Admin Console
 
 <GenerateBundleAdminConsole/>
 
-## Generating a Support Bundle using the CLI
+## Generate a Bundle Using the CLI
 
-You can generate a support bundle using the support-bundle CLI instead of the Admin Console. For example, the Admin Console might not be available if you are using a Replicated kURL installer and the installation fails. Or perhaps you need to use a more recent version of the support-bundle plugin than what is embedded in the Admin Console.
+You can generate a support bundle using the support-bundle CLI instead of the Admin Console. For example, you might need to generate a bundle from the CLI if the Admin Console is not available. Or perhaps you need to use a more recent version of the support-bundle plugin than what is embedded in the Admin Console.
 
 ### Prerequisite: Install the Plugin {#plugin}
 
 <InstallPlugin/>
 
-### Generate a Bundle (KOTS v1.94.2 and Later)
-
-:::note
-To generate support bundles on earlier versions of Replicated KOTS, see [Generate a Bundle (KOTS v1.94.1 and Earlier)](#earlier-versions).
-:::
+### Generate a Bundle
 
 <GenerateBundle/>
 
-### Generate a Bundle (KOTS v1.94.1 and Earlier){#earlier-versions}
-
-<GenerateBundleCliAdminConsole/>
-
-### Generate a Host Support Bundle
-
-<GenerateBundleHost/>
-
-### Generate a Bundle with a Default kots.io File
+## Related Topics
 
-<GenerateBundleDefaultKots/>
+* [Generating Host Bundles for Embedded Cluster](/vendor/support-bundle-embedded)
+* [Generating Host Bundles for kURL](/vendor/support-host-support-bundles)
+* [Generating Support Bundles](/vendor/support-bundle-generating)

docs/partials/support-bundles/_generate-bundle-admin-console.mdx

@@ -1,21 +1,19 @@
+The Replicated KOTS Admin Console includes a **Troubleshoot** page where you can generate a support bundle and review remediation suggestions for troubleshooting. You can also download the support bundle from the Admin Console.
+
 To generate a support bundle in the KOTS Admin Console:
 
 1. Log in to the Admin Console and go to the **Troubleshoot** tab.
 
-   ![Troubleshoot](/images/troubleshoot.png)
-
-1. Click **Analyze** to start analyzing the application.
+1. Click **Analyze** to start analyzing the application. Or, copy the command provided to generate a bundle from the CLI.
 
-   The analysis executes the support bundle plugin. After the analysis completes, the bundle is available on the Troubleshoot tab in the Admin Console. If any known issues are detected, they are highlighted with possible remediation suggestions.
+   The analysis executes the support bundle plugin. After the analysis completes, the bundle is available on the **Troubleshoot** tab in the Admin Console. If any known issues are detected, they are highlighted with possible remediation suggestions.
 
    :::note
    No data leaves the cluster. Data is never sent across the internet or to anyone else.
    :::
 
-   ![Analysis](/images/analysis.png)
-
-1. (Optional) If your vendor has enabled it for your online installation, you may also see a **Send bundle to vendor** button available. Clicking this button will send the support bundle directly to your vendor. We recommended following up with your vendor to let them know the bundle has been provided.
-    <img alt="Send bundle to vendor screen" src="/images/send-bundle-to-vendor.png" width="600px"/>
+1. (Optional) If enabled for your online installation, you might also see a **Send bundle to vendor** button available. Clicking this button will send the support bundle directly to your vendor. Replicated recommendeds following up with your vendor to let them know the bundle has been provided.
+    <img alt="Send bundle to vendor screen" src="/images/send-bundle-to-vendor.png" width="800px"/>
 
     [View a larger version of this image](/images/send-bundle-to-vendor.png)
 

docs/partials/support-bundles/_generate-bundle-default-kots.mdx

@@ -1,24 +1,24 @@
-You can generate a support bundle using the default kots.io manifest file if the application does not have a support bundle manifest included.
+For KOTS installations, you can generate a support bundle using the default KOTS spec. This is useful if the application does not have a support bundle spec included.
 
-#### In an Online Environment
+#### Online Environments
 
-In an online environment, run the following command to generate a support bundle using the default kots.io manifest file:
+In an online environment, run the following command to generate a support bundle using the default KOTS spec:
 
-  ```
-  kubectl support-bundle https://kots.io
-  ```
+```
+kubectl support-bundle https://kots.io
+```
 
-#### On an Air Gap Server
+#### Air Gap Environments
 
-If you are on an air gapped server, perform the following steps to create a support bundle using the default kots.io manifest file:
+For air gap environments, perform the following steps to generate a support bundle using the default KOTS spec:
 
-1. Run the following command from a computer with internet access to download the default kots.io manifest:
+1. Run the following command from a computer with internet access to download the default KOTS spec:
+
+   ```
+   curl -o spec.yaml https://kots.io -H 'User-agent:Replicated_Troubleshoot/v1beta1'
+   ```
 
-    ```
-    curl -o spec.yaml https://kots.io -H 'User-agent:Replicated_Troubleshoot/v1beta1'
-    ```
-
-1. Upload the `spec.yaml` file to the air gapped server.
+1. Upload the `spec.yaml` file to your air gap server.
 
 1. Run the following command to create a support bundle using the uploaded `spec.yaml` file:
 

docs/partials/support-bundles/_generate-bundle-ec.mdx

@@ -0,0 +1,38 @@
+To generate a support bundle:
+
+1. SSH onto a controller node.
+
+1. Use the Embedded Cluster shell command to start a shell with access to the cluster:
+
+     ```bash
+     sudo ./APP_SLUG shell
+     ```
+     Where `APP_SLUG` is the unique slug for the application.
+
+     The output looks similar to the following:
+
+    ```bash
+        __4___
+    _  \ \ \ \   Welcome to APP_SLUG debug shell.
+    <'\ /_/_/_/   This terminal is now configured to access your cluster.
+    ((____!___/) Type 'exit' (or CTRL+d) to exit.
+    \0\0\0\0\/  Happy hacking.
+    ~~~~~~~~~~~
+    root@alex-ec-2:/home/alex# export KUBECONFIG="/var/lib/k0s/pki/admin.conf"
+    root@alex-ec-2:/home/alex# export PATH="$PATH:/var/lib/embedded-cluster/bin"
+    root@alex-ec-2:/home/alex# source <(kubectl completion bash)
+    root@alex-ec-2:/home/alex# source /etc/bash_completion
+    ```
+
+     The appropriate kubeconfig is exported, and the location of useful binaries like kubectl and the preflight and support-bundle plugins is added to PATH.
+
+     :::note
+     The shell command cannot be run on non-controller nodes.
+     :::
+
+2. Generate the support bundle using the default Embedded Cluster spec and the `--load-cluster-specs` flag:
+
+   ```bash
+   kubectl support-bundle  --load-cluster-specs /var/lib/embedded-cluster/support/host-support-bundle.yaml
+   ```
+   

docs/partials/support-bundles/_generate-bundle-host.mdx

@@ -1,23 +1,10 @@
-For embedded clusters created with kURL, you can generate a host support bundle. Use this method when:
-
-- A cluster is down
-- The application is not installed
-- The Replicated Admin Console is not working
-- To debug a host-specific performance and configuration problems even when the cluster is running
-
-Your vendor typically provides a host support bundle YAML file that you run with a command to generate the host support bundle. You can also create a your own host support bundle YAML file. For more information about creating a YAML file, see [All Host Collectors and Analyzers](https://troubleshoot.sh/docs/host-collect-analyze/all/) in the Troubleshoot documentation.
-
-If you want to use a default YAML file from the Troubleshoot.sh repository for troubleshooting a degraded cluster, follow the command in the steps below.
-
-Root access is typically not required to run the host collectors and analyzers. However, depending on what is being collected, you might need to run the support-bundle binary with elevated permissions. For example, if you run the `filesystemPerformance` host collector against `/var/lib/etcd` and the user running the binary does not have permissions on this directory, the collection process fails.
-
-To generate a host support bundle:
+To generate a kURL host support bundle:
 
 1. Do one of the following:
 
-    - Save the host support bundle YAML file on the host.
+    - Save the host support bundle YAML file on the host. For more information about creating a YAML spec for a host support bundle, see [Create a Host Support Bundle Spec](/vendor/support-host-support-bundles#create-a-host-support-bundle-spec).
 
-    - Run the following command to download a host support bundle YAML file from the Troubleshoot repository that can help troubleshoot a degraded embedded kURL cluster:
+    - Run the following command to download the default kURL host support bundle YAML file from the Troubleshoot repository:
 
       ```
       kubectl support-bundle https://raw.githubusercontent.com/replicatedhq/troubleshoot-specs/main/host/default.yaml
@@ -27,7 +14,7 @@ To generate a host support bundle:
    For air gap environments, download the YAML file and copy it to the air gap machine.
    :::
 
-1. Run the following command on the host to generate a host support bundle:
+1. Run the following command on the host to generate a support bundle:
 
    ```
    ./support-bundle --interactive=false PATH/FILE.yaml
@@ -37,6 +24,10 @@ To generate a host support bundle:
      - `PATH` with the path to the host support bundle YAML file.
      - `FILE` with the name of the host support bundle YAML file from your vendor.
 
+   :::note
+   Root access is typically not required to run the host collectors and analyzers. However, depending on what is being collected, you might need to run the support-bundle binary with elevated permissions. For example, if you run the `filesystemPerformance` host collector against `/var/lib/etcd` and the user running the binary does not have permissions on this directory, the collection process fails.
+   :::  
+
 1. Share the host support bundle with your vendor's support team, if needed.
 
-1. Repeat these steps for each node because there is no method to generate host support bundles on remote hosts. If you have a multi-node embedded kURL cluster, you must run the support-bundle binary on each node and generate a host support bundle for each node.
+1. Repeat these steps for each node because there is no method to generate host support bundles on remote hosts. If you have a multi-node kURL cluster, you must run the support-bundle binary on each node to generate a host support bundle for each node.

docs/partials/support-bundles/_generate-bundle.mdx

@@ -1,41 +1,9 @@
-Support bundles are generated by providing one or more support bundle specifications with the `kubectl support-bundle` command.
+Run the following command to generate a 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`.
+```bash
+kubectl support-bundle --load-cluster-specs
+```
 
-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 `--load-cluster-specs` flag automatically discovers all support bundle specs that are defined in Secrets or ConfigMaps in the cluster. For more information, see [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
-  ```
-
-- 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
-  ```
-
-  Where `LABEL` is the name of the custom label.
-
-- Provide one or more files that contain support bundle specifications:
-
-  ```bash
-  kubectl support-bundle ./PATH_TO_FILE1 ./PATH_TO_FILE2 ./PATH_TO_FILE3
-  ```
-
-  Where `PATH_TO_FILE` is the path and YAML file name for each file.
-
-- 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 
-  ```
-
-  Where:
-
-  - `URL` is the URL where the specification is located
-  - `PATH_TO_FILE` is the path and YAML file name
+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/) in the Troubleshoot documentation.

docs/partials/support-bundles/_install-plugin.mdx

@@ -1,9 +1,9 @@
-For existing clusters, do a first-time installation or upgrade the support-bundle plugin (a kubectl plugin) before you generate a support bundle using the CLI. The plugin is required to generate a support bundle.
+The support-bundle plugin (a kubectl plugin) is required to generate support bundles from the command line.
 
 You can install the support-bundle plugin using krew or install it manually from the release archives.
 
 :::note
-If your application was installed using a Replicated kURL script, then `kubectl` and the `support-bundle` plugin is already present on all of the control plane nodes. You can skip this prerequisite.
+For Replicated Embedded Cluster and Replicated kURL installations, the support-bundle plugin is automatically installed on all of the control plane nodes. You can skip this prerequisite.
 :::
 
 #### Install or Upgrade using krew
@@ -30,7 +30,7 @@ To install the support-bundle plugin using krew, do one of the following:
 
 #### Install Manually
 
-If you do not want to install the plugin using krew or want an easier way to install the plugin in an air gapped environment, you can install the plugin manually from the release archives.
+If you do not want to install the plugin using krew or want an easier way to install the plugin in an air gap environment, you can install the plugin manually from the release archives.
 
 To install the support-bundle plugin manually:
 

docs/vendor/embedded-overview.mdx

@@ -2,6 +2,7 @@ import EmbeddedCluster from "../partials/embedded-cluster/_definition.mdx"
 import KurlComparison from "../partials/embedded-cluster/_kurl-comparison.mdx"
 import Requirements from "../partials/embedded-cluster/_requirements.mdx"
 import UpdateOverview from "../partials/embedded-cluster/_update-overview.mdx"
+import EmbeddedClusterSupportBundle from "../partials/support-bundles/_generate-bundle-ec.mdx"
 
 # Using Embedded Cluster (Beta)
 
@@ -414,23 +415,15 @@ To access the cluster and use other included binaries:
 
 ### Troubleshoot
 
-From the shell, you can generate a support bundle for the Embedded Cluster to help with troubleshooting.
+From the shell, you can generate a support bundle for Replicated Embedded Cluster installations to help with troubleshooting.
 
-The support bundle collects host-level information to troubleshoot failures related to host configuration like DNS, networking, or storage problems. It also collects cluster-level information about the components provided by Replicated, such as the Admin Console and Embedded Cluster operator that manage install and upgrade operations.
+The default support bundle spec for Embedded Cluster collects host-level information to troubleshoot failures related to host configuration like DNS, networking, or storage problems.
 
-If the cluster hasn't installed successfully and cluster-level information is not available, it will be excluded from the bundle.
+It also collects cluster-level information about the components provided by Replicated, such as the Admin Console and Embedded Cluster operator that manage install and upgrade operations. If the cluster has not installed successfully and cluster-level information is not available, it will be excluded from the bundle.
 
-To generate a support bundle:
+When generating the default host bundle for Embedded Cluster installations, you can also use the `--load-cluster-specs` flag to automatically discover all support bundle specs that are defined in Secrets or ConfigMaps in the cluster. This ensures that any application-specific specs are included in the bundle. For more information, see [Discover Cluster Specs](https://troubleshoot.sh/docs/support-bundle/discover-cluster-specs/) in the Troubleshoot documentation.
 
-1. Access the Embedded Cluster shell:
-     ```
-     sudo ./APP_SLUG shell
-     ```
-
-2. Generate the support bundle:
-     ```
-     kubectl support-bundle /var/lib/embedded-cluster/support/host-support-bundle.yaml --load-cluster-specs
-     ```
+<EmbeddedClusterSupportBundle/>
 
 You can then use the support bundle for troubleshooting or provide it to Replicated for assistance.
 

docs/vendor/preflight-defining.mdx

@@ -130,7 +130,7 @@ The Troubleshoot open source project includes several analyzers that you can inc
 
 To view all the available analyzers, see the [Analyze](https://troubleshoot.sh/docs/analyze/) section of the Troubleshoot documentation.
 
-### (KOTS Only) Block Installation with Required Preflights {#strict}
+### Block Installation with Required (Strict) Preflights {#strict}
 
 For applications installed with KOTS, you can set any preflight analyzer to `strict: true`. When `strict: true` is set, any `fail` outcomes for the analyzer block the deployment of the release.