[HOLD FOR 1.104.0 RELEASE] note about KOTS support bundle spec discovery #1582
Conversation
✅ Deploy Preview for replicated-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
✅ Deploy Preview for replicated-docs-upgrade ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
replicated-ci
added
type::docs
|
@replicatedhq/replicated-docs We want to mention that KOTS will also consume support bundles stored as part of Helm charts. I see that the Helm preflight docs already mention that KOTS will do this, so Craig is adding something to the support bundle docs. But it's in a different place. Would you mind just looking through these two pages and making sure they both consistently communicate that KOTS can use preflights and support bundles in Helm charts? |
|
|
||
| The following examples show some possible CLI commands to generate a support bundle for one or more specifications and locations: | ||
| For installations with the Helm CLI or with KOTS v1.104.0 and later, specifications can be automatically discovered in Secrets or ConfigMap objects in the cluster using the `--load-cluster-specs` flag with the `kubectl support-bundle`. Alternatively, for installations with the Helm CLI or with KOTS versions earlier than 1.104.0, specifications can be provided from YAML files in the local directory or from a URL. |
There was a problem hiding this comment.
Clarify that --load-cluster-specs flag applies to Helm CLI installs and to KOTS v1.104.0 or later.
Also made some edits to this description overall because I found it a little difficult to follow before
There was a problem hiding this comment.
This could be read to say that 1.104.0 and later can't use YAML files or a URL, which isn't true.
|
|
||
| Next, define the support bundle specification by adding collectors and analyzers. For more information, see [Define the Support Bundle Specification](#spec). | ||
|
|
||
| ### Create a SupportBundle Custom Resource | ||
|
|
||
| If you do not want to use Secrets, you can create a SupportBundle custom resource instead. Helm templates are supported when the specification is distributed using an OCI registry. |
There was a problem hiding this comment.
Helm templates are supported when the specification is distributed using an OCI registry.
I didn't see anything in the output of kubectl support-bundle --help or in the troubleshoot docs that indicated you could provide a link to the OCI registry. I think this might have been accidentally conflated with the kubectl preflight option to point to an OCI registry
There was a problem hiding this comment.
An engineer would know better than I do. You could be right. I know you can point to an HTTP endpoint, but maybe we modified this to include an OCI registry too (like back when we were first working on Helm CLI support).
There was a problem hiding this comment.
Diamon's looking into it: https://replicated.slack.com/archives/C016DU6CXNE/p1699304942774859
There was a problem hiding this comment.
Diamon says "Looks like the answer is yes". so I'll add this statement back in and then take the same approach to investigate further as part of a follow up story
There was a problem hiding this comment.
Okay, added this info back in with an example of what this is talking about:
:::note
For specifications created in a SupportBundle custom resource, Helm templates are supported only when the support bundle is generated from a link to the specification at an OCI registry. For example, `kubectl support-bundle oci://my.oci.registry/image`.
:::
Figured this could be a placeholder, but still needs to be revisited to fully document generating a SB from a spec at an OCI registry URL
|
|
||
| Next, define the support bundle specification by adding collectors and analyzers. For more information, see [Define the Support Bundle Specification](#spec). | ||
|
|
||
| ### Create a SupportBundle Custom Resource | ||
|
|
||
| If you do not want to use Secrets, you can create a SupportBundle custom resource instead. Helm templates are supported when the specification is distributed using an OCI registry. | ||
| If you do not want to use Secrets or ConfigMaps, you can create a SupportBundle custom resource instead. | ||
|
|
||
| Create a SupportBundle custom resource (`kind: SupportBundle`) using the following basic support bundle template. For more information about this custom resource, see [Preflight and Support Bundle](/reference/custom-resource-preflight). |
There was a problem hiding this comment.
^ Is there any requirement that this spec is wrapped in a template so that it's deployed to the cluster? or does that only matter for the preflight specs? It's not really clear to me, if I'm trying to distribute with the Helm CLI, what I would do with this SupportBundle custom resource. Add it to my templates? Just save it in a YAML file and email it to my customer as needed?
here's the corresponding info about defining a Preflight custom resource for Helm charts for reference: https://docs.replicated.com/vendor/preflight-helm-defining#create-a-preflight-custom-resource
There was a problem hiding this comment.
I think we should clarify that renderpreflights thing. The name itself is ambiguous—I assume it's a name we chose and not a hardcoded string, but the name isn't obvious to me. Maybe this lets you skip preflights. My guess is that it lets you skip preflights somehow, so we don't need it for support bundles, but we should confirm and clarify in that doc too.
There was a problem hiding this comment.
The renderpreflights thing is indeed just an example string. The purpose of it is: "If you use this input kind, you must use conditional statements because the custom resource definition is not installed in the cluster." As in, if you want to create a preflight definition in a Preflight custom resource manifest and add it to your templates (instead of creating a preflight spec in a Secret or ConfigMap), then you need to wrap it in a conditional statement that evaluates to true so that the preflight custom resource is installed in the cluster. (I think you can always skip preflights for Helm CLI installs since it requires running a separate command anyway, right?)
What I wasn't understanding was why that same thing doesn't seem to apply to this support bundle spec. Like, is the spec supposed to get installed to the cluster?
There was a problem hiding this comment.
Still trying to get my head fully around that. If the CRD isn't installed, what does the value do? I don't quite see how it's any different.
But I get your point about why would that not also be needed for support bundles.
There was a problem hiding this comment.
Yeah good point. Maybe this option can just be removed from the docs all together if it's not recommended and added to a community article instead...I'll add this to a new story to investigate more fully.
There was a problem hiding this comment.
Story to investigate and update the docs for both preflight and SB specs: https://app.shortcut.com/replicated/story/92865/update-docs-about-support-bundle-preflight-spec-discovery-to-clarify-custom-resource-option
Co-authored-by: Alex Parker <[email protected]>
Clarifying note based on questions in Slack https://replicated.slack.com/archives/C02TQTV9G2V/p1698956150308879.
Support was added to KOTS for the
troubleshoot.sh/kindlabel in replicatedhq/kots#4113