Skip to main content

Generating Support Bundles

This topic describes how to use the support-bundle kubectl CLI plugin to generate support bundles.

For KOTS installations, users can also generate support bundles from the Replicated admin console. For more information, see Generating Support Bundles in the KOTS documentation.

Prerequisite​

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.

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.

Install or Upgrade using krew​

To install the support-bundle plugin using krew, do one of the following:

  • If krew is not installed already, run the following command to install krew and the support-bundle plugin at the same time:

    curl https://krew.sh/support-bundle | bash

  • If krew is installed already, run the following command to install the plug-in:

    kubectl krew install support-bundle

  • To upgrade your existing support-bundle plugin using krew:

    kubectl krew upgrade support-bundle

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.

To install the support-bundle plugin manually:

  1. Run the following command to download and unarchive the latest release, and move the plugin to your $PATH:

    curl -L https://github.com/replicatedhq/troubleshoot/releases/latest/download/support-bundle_linux_amd64.tar.gz | tar xzvf -
    sudo mv ./support-bundle /usr/local/bin/kubectl-support-bundle
    note

    If you do not have root access, or choose not to add the support-bundle plugin to your path, you can run the binary directly from where you unzipped it by executing ./support-bundle. If you choose not to put the plugin into your $PATH, then replace all instances of kubectl support-bundle in these instructions with ./support-bundle or with the absolute path to the binary.

  2. (Optional) Run the following command to test that the installation is working:

    kubectl support-bundle --help

Generate a Bundle from the CLI​

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 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 and 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:

    kubectl support-bundle --load-cluster-specs

  • Discover all specifications defined in Secrets or ConfigMaps in the cluster that match a custom label:

    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:

    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:

    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

Generate a Bundle when a Helm Installation Fails​

If a Helm installation fails and you want to collect a support bundle to assist with diagnostics, you can use a Replicated default specification to generate the support bundle.

Run the following command:

kubectl support-bundle https://raw.githubusercontent.com/replicatedhq/troubleshoot-specs/main/in-cluster/default.yaml