document the recommended 'inside secret' method for supportbundle res…#4004
Merged
paigecalvert merged 3 commits intoMay 6, 2026
Merged
Conversation
✅ Deploy Preview for replicated-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for replicated-docs-upgrade ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
replicated-ci
added
type::docs
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| </tr> | ||
| </table> | ||
|
|
||
| ### troubleshoot-spec-in-chart-without-crd |
Contributor
There was a problem hiding this comment.
[Replicated.Headings] 'troubleshoot-spec-in-chart-without-crd' should use sentence case.
| <tr> | ||
| <th>Description</th> | ||
| <td> | ||
| <p>Notifies if a Helm chart contains a top-level <code>kind: Preflight</code> or <code>kind: SupportBundle</code> custom resource without also including the corresponding CRD (<code>preflights.troubleshoot.sh</code> or <code>supportbundles.troubleshoot.sh</code>) in the chart's <code>crds/</code> directory or templates.</p> |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Acronyms] Spell out 'CRD' on first use, if it's unfamiliar to the audience.
| <th>Description</th> | ||
| <td> | ||
| <p>Notifies if a Helm chart contains a top-level <code>kind: Preflight</code> or <code>kind: SupportBundle</code> custom resource without also including the corresponding CRD (<code>preflights.troubleshoot.sh</code> or <code>supportbundles.troubleshoot.sh</code>) in the chart's <code>crds/</code> directory or templates.</p> | ||
| <p>Bare Preflight or SupportBundle custom resources inside a Helm chart require the matching CRD to be installed in the cluster before the chart is applied. In most shared clusters, that CRD is not present and installing it requires cluster-admin permissions. Embed the spec in a Kubernetes Secret with the <code>troubleshoot.sh/kind</code> label instead. See <a href="/vendor/preflight-defining">Define preflight checks</a> and <a href="/vendor/support-bundle-customizing">Add and customize support bundles</a>.</p> |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Acronyms] Spell out 'CRD' on first use, if it's unfamiliar to the audience.
| <th>Description</th> | ||
| <td> | ||
| <p>Notifies if a Helm chart contains a top-level <code>kind: Preflight</code> or <code>kind: SupportBundle</code> custom resource without also including the corresponding CRD (<code>preflights.troubleshoot.sh</code> or <code>supportbundles.troubleshoot.sh</code>) in the chart's <code>crds/</code> directory or templates.</p> | ||
| <p>Bare Preflight or SupportBundle custom resources inside a Helm chart require the matching CRD to be installed in the cluster before the chart is applied. In most shared clusters, that CRD is not present and installing it requires cluster-admin permissions. Embed the spec in a Kubernetes Secret with the <code>troubleshoot.sh/kind</code> label instead. See <a href="/vendor/preflight-defining">Define preflight checks</a> and <a href="/vendor/support-bundle-customizing">Add and customize support bundles</a>.</p> |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('be installed').
| <th>Description</th> | ||
| <td> | ||
| <p>Notifies if a Helm chart contains a top-level <code>kind: Preflight</code> or <code>kind: SupportBundle</code> custom resource without also including the corresponding CRD (<code>preflights.troubleshoot.sh</code> or <code>supportbundles.troubleshoot.sh</code>) in the chart's <code>crds/</code> directory or templates.</p> | ||
| <p>Bare Preflight or SupportBundle custom resources inside a Helm chart require the matching CRD to be installed in the cluster before the chart is applied. In most shared clusters, that CRD is not present and installing it requires cluster-admin permissions. Embed the spec in a Kubernetes Secret with the <code>troubleshoot.sh/kind</code> label instead. See <a href="/vendor/preflight-defining">Define preflight checks</a> and <a href="/vendor/support-bundle-customizing">Add and customize support bundles</a>.</p> |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is applied').
| * Helm applications installed with KOTS v1.94.2 and later | ||
|
|
||
| :::note | ||
| Support bundle specs must be defined in a Kubernetes Secret (or ConfigMap) when included inside a Helm chart's `templates` directory. A bare `kind: SupportBundle` custom resource in a chart requires the `supportbundles.troubleshoot.sh` CRD to be installed in the cluster, which is not available in most shared clusters and requires cluster-admin permissions. The Secret-based approach works in any cluster without additional setup. For more information, see [Discover Cluster Specs](https://troubleshoot.sh/docs/support-bundle/discover-cluster-specs/) in the Troubleshoot documentation. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Acronyms] Spell out 'CRD' on first use, if it's unfamiliar to the audience.
| * Helm applications installed with KOTS v1.94.2 and later | ||
|
|
||
| :::note | ||
| Support bundle specs must be defined in a Kubernetes Secret (or ConfigMap) when included inside a Helm chart's `templates` directory. A bare `kind: SupportBundle` custom resource in a chart requires the `supportbundles.troubleshoot.sh` CRD to be installed in the cluster, which is not available in most shared clusters and requires cluster-admin permissions. The Secret-based approach works in any cluster without additional setup. For more information, see [Discover Cluster Specs](https://troubleshoot.sh/docs/support-bundle/discover-cluster-specs/) in the Troubleshoot documentation. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('be installed').
|
|
||
| In a release for your application, add the following YAML to a new `support-bundle.yaml` manifest file: | ||
| :::note | ||
| A bare `kind: SupportBundle` custom resource is only appropriate at the root of a release. If you place this manifest inside a Helm chart's `templates` directory, the `supportbundles.troubleshoot.sh` CRD must be installed in the cluster before the chart is deployed. For Helm charts, use the Secret-based approach in [Kubernetes secret](#secret) instead. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Acronyms] Spell out 'CRD' on first use, if it's unfamiliar to the audience.
|
|
||
| In a release for your application, add the following YAML to a new `support-bundle.yaml` manifest file: | ||
| :::note | ||
| A bare `kind: SupportBundle` custom resource is only appropriate at the root of a release. If you place this manifest inside a Helm chart's `templates` directory, the `supportbundles.troubleshoot.sh` CRD must be installed in the cluster before the chart is deployed. For Helm charts, use the Secret-based approach in [Kubernetes secret](#secret) instead. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('be installed').
|
|
||
| In a release for your application, add the following YAML to a new `support-bundle.yaml` manifest file: | ||
| :::note | ||
| A bare `kind: SupportBundle` custom resource is only appropriate at the root of a release. If you place this manifest inside a Helm chart's `templates` directory, the `supportbundles.troubleshoot.sh` CRD must be installed in the cluster before the chart is deployed. For Helm charts, use the Secret-based approach in [Kubernetes secret](#secret) instead. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is deployed').
banjoh
reviewed
Apr 29, 2026
Member
banjoh
left a comment
banjoh
left a comment
There was a problem hiding this comment.
I suggest we avoid mentioning troubleshoot CRDs (even if technically they can be installed to have installs succeed) so as not to direct/encourage users to attempting to install them as a solution.
| <th>Description</th> | ||
| <td> | ||
| <p>Notifies if a Helm chart contains a top-level <code>kind: Preflight</code> or <code>kind: SupportBundle</code> custom resource.</p> | ||
| <p>Preflight and SupportBundle custom resources cannot be applied directly from a Helm chart — they require cluster-side CRDs that are not available in most shared clusters and that need cluster-admin permissions to install. Embed the spec in a Kubernetes Secret with the <code>troubleshoot.sh/kind</code> label instead. See <a href="/vendor/preflight-defining">Define preflight checks</a> and <a href="/vendor/support-bundle-customizing">Add and customize support bundles</a>.</p> |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.SentenceLength] Try to keep your sentence length to 26 words or fewer.
| <th>Description</th> | ||
| <td> | ||
| <p>Notifies if a Helm chart contains a top-level <code>kind: Preflight</code> or <code>kind: SupportBundle</code> custom resource.</p> | ||
| <p>Preflight and SupportBundle custom resources cannot be applied directly from a Helm chart — they require cluster-side CRDs that are not available in most shared clusters and that need cluster-admin permissions to install. Embed the spec in a Kubernetes Secret with the <code>troubleshoot.sh/kind</code> label instead. See <a href="/vendor/preflight-defining">Define preflight checks</a> and <a href="/vendor/support-bundle-customizing">Add and customize support bundles</a>.</p> |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('be applied').
| <th>Description</th> | ||
| <td> | ||
| <p>Notifies if a Helm chart contains a top-level <code>kind: Preflight</code> or <code>kind: SupportBundle</code> custom resource.</p> | ||
| <p>Preflight and SupportBundle custom resources cannot be applied directly from a Helm chart — they require cluster-side CRDs that are not available in most shared clusters and that need cluster-admin permissions to install. Embed the spec in a Kubernetes Secret with the <code>troubleshoot.sh/kind</code> label instead. See <a href="/vendor/preflight-defining">Define preflight checks</a> and <a href="/vendor/support-bundle-customizing">Add and customize support bundles</a>.</p> |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'CRDs'?
| For Helm applications installed with Helm or KOTS v1.101.0 or later, define preflight checks in a Kubernetes Secret in your Helm chart `templates`. This allows you to define the preflights spec only one time to support running preflight checks in both Helm and KOTS installations. | ||
|
|
||
| :::note | ||
| Preflight checks must be defined in a Kubernetes Secret (or ConfigMap) when included inside a Helm chart's `templates` directory. Do not place a bare `kind: Preflight` custom resource inside a Helm chart — that pattern is not supported in most shared clusters. The Secret-based approach works in any cluster without additional setup. For more information, see [Discover Cluster Specs](https://troubleshoot.sh/docs/support-bundle/discover-cluster-specs/) in the Troubleshoot documentation. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('be defined').
| * Helm applications installed with KOTS v1.100.3 and earlier | ||
| :::note | ||
| For Helm charts installed with KOTS v1.101.0 and later, Replicated recommends that you define preflight checks in a Secret in the Helm chart `templates` instead of using the Preflight custom resource. See [Create a Secret](#secret) above. | ||
| For Helm charts installed with KOTS v1.101.0 and later, Replicated recommends that you define preflight checks in a Secret in the Helm chart `templates` instead of using the Preflight custom resource. See [Create a Secret](#secret) above. Do not place a bare `kind: Preflight` resource inside a Helm chart. |
Contributor
There was a problem hiding this comment.
[Replicated.PositionalLanguage] Avoid spacial and directional language like 'above'. Instead, use 'on this page', 'the following', or link to the section.
| * Helm applications installed with KOTS v1.94.2 and later | ||
|
|
||
| :::note | ||
| Support bundle specs must be defined in a Kubernetes Secret (or ConfigMap) when included inside a Helm chart's `templates` directory. Do not place a bare `kind: SupportBundle` custom resource inside a Helm chart — that pattern is not supported in most shared clusters. The Secret-based approach works in any cluster without additional setup. For more information, see [Discover Cluster Specs](https://troubleshoot.sh/docs/support-bundle/discover-cluster-specs/) in the Troubleshoot documentation. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('be defined').
banjoh
approved these changes
Apr 30, 2026
banjoh
previously approved these changes
May 5, 2026
paigecalvert
approved these changes
May 6, 2026
Contributor
paigecalvert
left a comment
paigecalvert
left a comment
There was a problem hiding this comment.
Reverted the preflight and support bundle how-to changes in favor of #4027
Linter changes lgtm
paigecalvert
deleted the
laverya/sc-136963/troubleshoot-crds-don-t-exist-on-helm-cli
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
https://deploy-preview-4004--replicated-docs.netlify.app/reference/linter#troubleshoot-spec-in-chart-without-crd
https://deploy-preview-4004--replicated-docs.netlify.app/vendor/preflight-defining
https://deploy-preview-4004--replicated-docs.netlify.app/vendor/support-bundle-customizing