doc: document embedded-cluster support-bundle command (#2771)

* doc: document embedded-cluster support-bundle command this is a temporary PR as XXX needs to be replaced with the actual embedded-cluster version yet to be released. * chore: improve wording * chore: improve wording * docs edits * edits * add version and clarify app-level info * edit * Update _ec-support-bundle-intro.mdx --------- Co-authored-by: Paige Calvert <[email protected]> Co-authored-by: Alex Parker <[email protected]>
replicatedhq · Nov 4, 2024 · ae09ed9 · ae09ed9
1 parent ffde934
commit ae09ed9
Show file tree

Hide file tree

Showing 5 changed files with 52 additions and 26 deletions.
diff --git a/docs/partials/support-bundles/_ec-support-bundle-intro.mdx b/docs/partials/support-bundles/_ec-support-bundle-intro.mdx
@@ -0,0 +1,5 @@
+Embedded Cluster includes a default support bundle spec that collects both host- and cluster-level information.
+
+The host-level information is useful for troubleshooting failures related to host configuration like DNS, networking, or storage problems. Cluster-level information includes details 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, then it is excluded from the bundle.
+
+In addition to the host- and cluster-level details provided by the default Embedded Cluster spec, support bundles generated for Embedded Cluster installations also include app-level details provided by any custom support bundle specs that you included in the application release.
diff --git a/docs/partials/support-bundles/_generate-bundle-ec.mdx b/docs/partials/support-bundles/_generate-bundle-ec.mdx
@@ -1,5 +1,35 @@
+There are different steps to generate a support bundle depending on the version of Embedded Cluster installed.
+
+### For Versions 1.17.0 and Later
+
+For Embedded Cluster 1.17.0 and later, you can run the Embedded Cluster `support-bundle` command to generate a support bundle.
+
+The `support-bundle` command uses the default Embedded Cluster support bundle spec to collect both cluster- and host-level information. It also automatically includes any application-specific support bundle specs in the generated bundle. 
+
 To generate a support bundle:
 
+1. SSH onto a controller node.
+
+   :::note
+   You can SSH onto a worker node to generate a support bundle that contains information specific to that node. However, when run on a worker node, the `support-bundle` command does not capture cluster-wide information.
+   :::
+
+1. Run the following command:
+
+   ```bash
+   sudo ./APP_SLUG support-bundle
+   ```
+
+   Where `APP_SLUG` is the unique slug for the application. 
+
+### For Versions Earlier Than 1.17.0
+
+For Embedded Cluster versions earlier than 1.17.0, you can generate a support bundle from the shell using the kubectl support-bundle plugin.
+
+To generate a bundle with the support-bundle plugin, you pass the default Embedded Cluster spec to collect both cluster- and host-level information. You also pass the `--load-cluster-specs` flag, which discovers all support bundle specs that are defined in Secrets or ConfigMaps in the cluster. This ensures that any application-specific specs are also included in the bundle. For more information, see [Discover Cluster Specs](https://troubleshoot.sh/docs/support-bundle/discover-cluster-specs/) in the Troubleshoot documentation.
+
+To generate a bundle:
+
 1. SSH onto a controller node.
 
 1. Use the Embedded Cluster shell command to start a shell with access to the cluster:
@@ -35,4 +65,3 @@ To generate a support bundle:
    ```bash
    kubectl support-bundle  --load-cluster-specs /var/lib/embedded-cluster/support/host-support-bundle.yaml
    ```
-   
diff --git a/docs/vendor/embedded-overview.mdx b/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 SupportBundleIntro from "../partials/support-bundles/_ec-support-bundle-intro.mdx"
 import EmbeddedClusterSupportBundle from "../partials/support-bundles/_generate-bundle-ec.mdx"
 import EcConfig from "../partials/embedded-cluster/_ec-config.mdx"
 import EmbeddedClusterPortRequirements from "../partials/embedded-cluster/_port-reqs.mdx"
@@ -241,20 +242,6 @@ To access the cluster and use other included binaries:
      If you encounter a typical workflow where your customers have to use the Embedded Cluster shell, reach out to Alex Parker at [email protected]. These workflows might be candidates for additional Admin Console functionality.
      :::
 
-### Troubleshoot
-
-From the shell, you can generate a support bundle for Replicated Embedded Cluster installations to help with troubleshooting.
-
-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.
-
-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.
-
-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.
-
-<EmbeddedClusterSupportBundle/>
-
-You can then use the support bundle for troubleshooting or provide it to Replicated for assistance.
-
 ## Manage Nodes
 
 The section describes managing nodes in clusters created with Embedded Cluster, including how to add or reset nodes.
@@ -380,3 +367,9 @@ toolkit:
    - name: CONTAINERD_SOCKET
      value: /run/k0s/containerd.sock
 ```     
+
+## Troubleshoot with Support Bundles
+
+<SupportBundleIntro/>
+
+<EmbeddedClusterSupportBundle/>
diff --git a/docs/vendor/support-bundle-embedded.mdx b/docs/vendor/support-bundle-embedded.mdx
@@ -1,19 +1,16 @@
 import EmbeddedClusterSupportBundle from "../partials/support-bundles/_generate-bundle-ec.mdx"
+import SupportBundleIntro from "../partials/support-bundles/_ec-support-bundle-intro.mdx"
 
-# Generating Host Bundles for Embedded Cluster
+# Generating Support Bundles for Embedded Cluster
 
-This topic describes how to generate a support bundle that includes host-level information for [Replicated Embedded Cluster](/vendor/embedded-overview) installations. For information about generating host support bundles for Replicated kURL installations, see [Generating Host Bundles for kURL](/vendor/support-host-support-bundles).
+This topic describes how to generate a support bundle that includes cluster- and host-level information for [Replicated Embedded Cluster](/vendor/embedded-overview) installations.
 
-## Overview
-
-From the shell, you can generate a support bundle for Replicated Embedded Cluster installations to help with troubleshooting.
+For information about generating host support bundles for Replicated kURL installations, see [Generating Host Bundles for kURL](/vendor/support-host-support-bundles).
 
-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.
-
-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.
+## Overview
 
-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.
+<SupportBundleIntro/>
 
-## Generate a Support Bundle for Embedded Cluster
+## Generate a Support Bundle
 
 <EmbeddedClusterSupportBundle/>
diff --git a/docs/vendor/support-bundle-generating.mdx b/docs/vendor/support-bundle-generating.mdx
@@ -5,6 +5,8 @@ import GenerateBundle from "../partials/support-bundles/_generate-bundle.mdx"
 
 This topic describes how to generate support bundles from the command line using the kubectl support-bundle plugin. For more information about support bundles, see [About Preflights and Support Bundles](/vendor/preflight-support-bundle-about).
 
+The information in this topic applies to generating support bundles in clusters where you have kubectl access. For information about generating support bundles that include cluster- and host-level information for Replicated Embedded Cluster installations, see [Generating Support Bundles for Embedded Cluster](support-bundle-embedded). 
+
 ## Prerequisite: Install the support-bundle Plugin
 
 <InstallPlugin/>
@@ -25,6 +27,6 @@ kubectl support-bundle https://raw.githubusercontent.com/replicatedhq/troublesho
 
 ## Related Topics
 
-* [Generating Host Bundles for Embedded Cluster](/vendor/support-bundle-embedded)
+* [Generating Support Bundles for Embedded Cluster](/vendor/support-bundle-embedded)
 * [Generating Host Bundles for kURL](/vendor/support-host-support-bundles)
 * [Generating Support Bundles for KOTS Installations](/enterprise/troubleshooting-an-app)