Clarify how you need to configure builder for Helm air gap installs #3339
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
|
|
||
| These installing and updating instructions assume that your customer is accessing the Download Portal from a workstation that can access the internet and their internal private registry. Direct access to the target cluster is not required. | ||
| * Configure the HelmChart custom resource `builder` key. This ensures that the Vendor Portal can template the chart to discover the full list of container images required to install the chart in an air-gapped environment. The Vendor Portal uses this list of required images to create the Helm air gap installation instructions for the customer. For more information, see [builder](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. |
There was a problem hiding this comment.
^ added prepreq to fill out the builder key for helm air gap
There was a problem hiding this comment.
It's not need in 100% of charts, only in charts where there are either required values that don't have defaults, or images that are only used when certain values are set. This may be fine to leave as is and they can figure that out from the linked page. You may also want to be more specific here.
There was a problem hiding this comment.
Ah thanks for calling that out.
Part of me was thinking that we could just act like it's always required and tell everyone to do it, rather than getting into explaining the caveats (especially if we can safely assume that most people would have a chart where the default values don't cut it). But, maybe the work to configure the builder key is enough that taking to space to say "if your default values expose all the images needed, then don't worry about it" is worth it.
I'm happy to go either direction; just wanted to throw that out there to see if you had thoughts one way or the other
There was a problem hiding this comment.
I'm on the fence, maybe a simple line like that would be just right.
|
|
||
| For more information about enabling the Enterprise Portal for a customer, see [Manage Enterprise Portal Access](/vendor/enterprise-portal-invite). | ||
|
|
||
| ### Enterprise Portal (Beta) |
There was a problem hiding this comment.
^ added these quick instructions for how to access the helm air gap install instrux in the Enterprise Portal (previously this page just talked about the download portal steps)
this could probably be improved in a follow-up PR, but mostly just didn't want this page to imply that this was a Download Portal-only thing
|
|
||
| ### Manual Updates | ||
|
|
||
| The manual update instructions provided in the Download Portal are similar to the installation instructions. | ||
| The manual update instructions provided in the Enterprise Portal or Download Portal are similar to the installation instructions. |
There was a problem hiding this comment.
minimal update here just to say that the update instructions can appear in either the enterprise or download portal
didn't change the content for the scope of this PR since nothing looked wrong. In another PR this section could be improved to include a step-by-step
| Alternatively, if a release contains charts that must use the same name, convert one or both of the charts into subcharts and use Helm conditions to differentiate them. See [Conditions and Tags](https://helm.sh/docs/chart_best_practices/dependencies/#conditions-and-tags) in the Helm documentation. | ||
|
|
||
| ## Incomplete list of required images in the Helm air gap instructions |
There was a problem hiding this comment.
^ added new section in the helm install troubleshooting page
| @@ -89,24 +89,26 @@ For an example of recursive and non-recursive merging, see [About Recursive Merg | |||
|
|
|||
| ## builder | |||
|
|
|||
| The `builder` key is used to provide Helm values that are used during various stages of processing the Helm chart. | |||
| #### Overview | |||
There was a problem hiding this comment.
Added this new overview to explain how the builder key is used:
|
|
||
| For more information about how to build `.airgap` bundles for installations with a Replicated installer (Embedded Cluster, KOTS, kURL), see [Package Air Gap Bundles for Helm Charts](/vendor/helm-packaging-airgap-bundles). | ||
|
|
||
| For more information about how to install with Helm in air-gapped environments, see [Install and Update with Helm in Air Gap Environments](/vendor/helm-install-airgap). |
There was a problem hiding this comment.
^ Added links to related topics
There was a problem hiding this comment.
I don't know if this is the place to point out that it's run automatically for getting the list of images for Helm and only when configured to run for generating the actual bundles, but that's part of what tripped me up figuring the behavior out.
Update the Helm Air Gap Install page with a prerequisite to configure the
builderkey: https://deploy-preview-3339--replicated-docs.netlify.app/vendor/helm-install-airgapAdded new troubleshooting section about this builder requirement: https://deploy-preview-3339--replicated-docs.netlify.app/vendor/helm-install-troubleshooting#incomplete-list-of-required-images-in-the-helm-air-gap-instructions
Update the description of the
builderkey with info about how it's used to create helm air gap instructions: https://deploy-preview-3339--replicated-docs.netlify.app/reference/custom-resource-helmchart-v2#builder