Skip to main content

Add and customize support bundles

This topic describes how to add a default support bundle spec to a release for your application. It also describes how to customize the default support bundle spec based on your application's needs. For more information about support bundles, see About Preflight Checks and Support Bundles.

Add the default support bundle spec to a release​

When you add an empty support bundle spec to your Helm chart, the spec automatically includes the clusterInfo and clusterResources collectors by default. You do not need manually include these collectors in the spec.

To add the default support bundle spec to a release for your application:

  1. In your Helm chart templates directory, create a YAML file. Name the file support-bundle.yaml or similar.

    note

    If you deploy your application as multiple Helm charts, Replicated recommends that you create separate support bundle specs for each subchart. This allows you to make specs that are specific to different components of your application. When Replicated generates a support bundle, it combines all the specs into a single bundle.

  2. In the YAML file, add the following to create a Kubernetes Secret with the default support bundle spec:

    # templates/support-bundle.yaml
    apiVersion: v1
    kind: Secret
    metadata:
      # troubleshoot.sh/kind: support-bundle label is required
      labels:
        troubleshoot.sh/kind: support-bundle
      name: example
    # add the spec in a support-bundle-spec key under stringData
    stringData:
      support-bundle-spec: |
        apiVersion: troubleshoot.sh/v1beta2
        kind: SupportBundle
        metadata:
          name: support-bundle
        spec:
          collectors: []
          analyzers: []

  3. (Recommended) Customize the default spec by adding more collectors and analyzers or editing the default collectors. See Customize the default support bundle spec on this page.

  4. If you deploy your application as multiple subcharts, repeat the previous steps to add a support bundle spec to the templates directory of each chart.

  5. Test the support bundle by following the instructions in Generating a Support Bundle.

  6. From the root directory of your Helm chart, package the chart into a .tgz archive:

    helm package --dependency-update .

  7. Add the chart archive to a new release. Promote the release to an internal development channel, and install the release in a development environment to test your changes.

(Recommended) Customize the default support bundle spec​

You can customize the support bundle spec by:

  • Adding collectors and analyzers
  • Editing or excluding the default clusterInfo and clusterResources collectors

Add collectors and analyzers​

For common examples of collectors and analyzers used in support bundle specs, see Examples of support bundle specs.

To add collectors and analyzers:

  1. In your Helm chart's templates directory, open the Kubernetes Secret that contains the support bundle spec.

  2. Update spec.collectors with additional collectors based on your application needs. For a list of all available collectors, see All Collectors in the Troubleshoot documentation.

    The following are some recommended collectors:

  3. Update spec.analyzers with additional analyzers based on your application needs. For the list of all available analyzers, see the Analyze section in the Troubleshoot documentation.

    The following are some recommended analyzers:

    note

    Good analyzers clearly identify failure modes and provide troubleshooting guidance for the user. For example, if you can identify a log message that indicates a problem in your database component, write an analyzer to check for that log. Include a description of the error for the user.

  4. Test the support bundle by following the instructions in Generating a Support Bundle.

  5. From the root directory of your Helm chart, package the chart into a .tgz archive:

    helm package --dependency-update .

  6. Add the chart archive to a new release. Promote the release to an internal development channel, and install the release in a development environment to test your changes.

Customize the default clusterResources collector​

You can edit the default clusterResources using the following properties:

  • namespaces: The list of namespaces from which to collect resources and information. If the namespaces key is not specified, then the clusterResources collector defaults to collecting information from all namespaces. You cannot remove the default namespace, but you can specify additional namespaces.

  • ignoreRBAC: When true, the clusterResources collector does not check for RBAC authorization before collecting resource information from each namespace. This is useful when your cluster uses authorization webhooks that do not support SelfSubjectRuleReviews. Defaults to false.

The following example shows how to specify the namespaces where the clusterResources collector collects information:

spec:
  collectors:
    - clusterResources:
        namespaces:
        - default
        - my-app-namespace
        ignoreRBAC: true

The following example shows how to use Helm template functions to set the namespace:

spec:
  collectors:
    - clusterResources:
        namespaces: {{ .Release.Namespace }}
        ignoreRBAC: true

The following example shows how to use the Replicated Namespace template function to set the namespace:

spec:
  collectors:
    - clusterResources:
        namespaces: '{{repl Namespace }}'
        ignoreRBAC: true

For more information, see Namespace in Static Context.

Exclude the default collectors​

Replicated recommends including the default clusterInfo and clusterResources collectors because they collect a large amount of data for installation and debugging. However, you can exclude them.

The following example shows how to exclude both the clusterInfo and clusterResources collectors from your support bundle spec:

spec:
  collectors:
    - clusterInfo:
        exclude: true
    - clusterResources:
        exclude: true

Add a support bundle spec for non-Helm applications or KOTS v1.94.1 and earlier​

For non-Helm applications or installations with KOTS v1.94.1 and earlier, add the SupportBundle custom resource to a YAML file at the root level of your release:

# support-bundle.yaml

apiVersion: troubleshoot.sh/v1beta2
kind: SupportBundle
metadata:
  name: example
spec:
  collectors: []
  analyzers: []

Customize the collectors and analyzers as desired.

On this page