Merge pull request #3339 from replicatedhq/125539

Clarify how you need to configure builder for Helm air gap installs

Author: paigecalvert

docs/reference/custom-resource-helmchart-v2.mdx

@@ -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
 
-The `builder` key is required for the following use cases:
+The `builder` key contains the minimum Helm values required so that the output of `helm template` exposes all container images needed to install the chart in an air-gapped environment.
 
-* To create an `.airgap` bundle for installations into air gap environments.
+The Replicated Vendor Portal uses the Helm values that you provide in the `builder` key to run `helm template` on the chart, then parses the output to discover the list of required images for the chart. 
 
-  <BuilderAirgapIntro/>
+The Vendor Portal uses this list of images to create the Helm air gap installation instructions that are automatically made available to customers in the Replicated Enterprise Portal or Download Portal. For more information about installing with Helm in air-gapped environments, see [Install and Update with Helm in Air Gap Environments](/vendor/helm-install-airgap). 
 
-  For more information, see [Package Air Gap Bundles for Helm Charts](/vendor/helm-packaging-airgap-bundles).
+The list of images is also used when you build the `.airgap` bundle for a release to support air gap installations with a Replicated installer (Embedded Cluster, KOTS, kURL). For more information about how to build `.airgap` bundles, see [Package Air Gap Bundles for Helm Charts](/vendor/helm-packaging-airgap-bundles).
 
-* To support online installations that use a local private registry, the `builder` field renders the Helm chart with all of the necessary images so that KOTS knows where to pull the images.
+The `builder` key is required to support the following installation types:
 
-  You cannot prevent customers from configuring a local private registry in the Admin Console. If you think any of your customers will use a local private registry, you should use the `builder` key. For more information, see [Configuring Local Image Registries](/enterprise/image-registry-settings).
+* Air gap installations with a Replicated installer (Embedded Cluster, KOTS, kURL)
+* Air gap installations with Helm
+* Online installations with a Replicated installer where the user configured a local image registry in the Admin Console
 
-<HelmBuilderRequirements/>
+#### Requirements
 
-* Use the same `builder` configuration to support the use of local registries in both online and air gap installations. If you already configured the `builder` key to support air gap installations, then no additional configuration is required.
+<HelmBuilderRequirements/>
 
-**Example:**
+#### Example
 
-<BuilderExample/>
+<BuilderExample/>

docs/vendor/helm-install-airgap.mdx

@@ -1,40 +1,76 @@
-import Prerequisites from "../partials/helm/_helm-install-prereqs.mdx"
-
 # Install and Update with Helm in Air Gap Environments
 
-This topic describes how to use Helm to install releases that contain one or more Helm charts in air-gapped environments.
+This topic describes how to install and update releases with Helm in air-gapped environments.
 
 ## Overview
 
-Replicated supports installing and updating Helm charts in air-gapped environments with no outbound internet access. In air gap Helm installations, customers are guided through the process with instructions provided in the [Replicated Download Portal](/vendor/releases-share-download-portal).
+Replicated supports installing and updating with Helm in _air-gapped_ environments with little or no outbound internet access. In air gap installations with Helm, customers are guided through the installation process with instructions provided in either the [Replicated Enterprise Portal](/vendor/enterprise-portal-about) or the [Replicated Download Portal](/vendor/releases-share-download-portal), depending on which is enabled for the customer.
+
+These instructions assume that the customer is logged in to the portal on a workstation that can access both the internet and their internal private image registry. Direct access to the target installation cluster is not required. The instructions also assume that the customer is familiar with `curl`, `docker`, `helm`, and `kubernetes`, and that they have some familiarity with `bash`, particularly for automating updates.
 
-When air gap Helm installations are enabled, an **Existing cluster with Helm** option is displayed in the Download Portal on the left nav. When selected, **Existing cluster with Helm** displays three tabs (**Install**, **Manual Update**, **Automate Updates**), as shown in the screenshot below:
+## Prerequisites
 
-![download helm option](/images/download-helm.png)
+Before you install, complete the following prerequisites:
 
-[View a larger version of this image](/images/download-helm.png)
+* Declare the SDK as a dependency in your Helm chart. For more information, see [Install the SDK as a Subchart](replicated-sdk-installing#install-the-sdk-as-a-subchart) in _Installing the Replicated SDK_.
 
-Each tab provides instructions for how to install, perform a manual update, or configure automatic updates, respectively.
+* If your Helm chart's default values do not expose all the required and optional images that might be needed to install in air-gapped environments, add the Replicated HelmChart custom resource to your release and configure `builder` key. For more information, see [builder](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. If your default values expose all images needed for air gap installations, you do not need to configure the `builder` key. 
 
-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.
+     <details>
+       <summary>What is the purpose of the `builder` key?</summary>
 
-Each method assumes that your customer is familiar with `curl`, `docker`, `helm`, `kubernetes`, and a bit of `bash`, particularly for automating updates.
+     Configuring the `builder` key 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. 
+     </details> 
 
-## Prerequisites
+* The customer used to install must have the following:
 
-Before you install, complete the following prerequisites:
+     * A valid email address. This email address is only used as a username for the Replicated registry and is never contacted. For more information, see [Creating a Customer](/vendor/releases-creating-customer).
 
-<Prerequisites/>
+     * The **Existing Cluster (Helm CLI)** install type enabled. For more information, see [Manage Install Types for a License](licenses-install-types).
+
+     * The **Helm CLI Air Gap Instructions** install option enabled.
 
 ## Install
 
-The installation instructions provided in the Download Portal are designed to walk your customer through the first installation of your chart in an air gap environment.
+Helm air gap installation instructions are provided in either the Enterprise Portal or the Download Portal, depending on which is enabled for the customer.
+
+For more information about enabling the Enterprise Portal for a customer, see [Manage Enterprise Portal Access](/vendor/enterprise-portal-invite).
+
+### Enterprise Portal (Beta)
+
+To install with Helm in an air gap environment using the Enterprise Portal:
+
+1. In the [Vendor Portal](https://vendor.replicated.com), go to **Customers > [Customer Name] > Reporting**.
+
+1. In the **Enterprise portal** section, click **Visit** to log in to the portal.
+
+1. In the Enterprise Portal, go to the **Install** tab then click **Helm** in the left nav.
+
+1. On the first page of the installation wizard, complete any pre-install instructions. If the vendor did not include any custom pre-install instructions, continue to the next step.
+
+1. Complete the following fields and then click **Continue**:
+
+     * **Instance Name**: Enter a name for the instance.
+     * **Kubernetes Distribution**: Select the Kubernetes distribution of the cluster where you will install.
+     * **Cluster Network Availability**: Select the network availability of the cluster. For air gap installations, select **No outbound requests allowed (air gap)**.
+     * **Registry Access**: Select the option that describes your current workstation's access to the internal image registry where you will push application images during installation. For air gap installations, select either **My workstation can only access the internet AND the registry (NOT the cluster)** or **I need to download artifacts and transfer them for offline installation**.
+
+     The following shows an example of the Helm air gap installation instructions in the Enterprise Portal:
+
+     ![Helm air gap installation guide](/images/enterprise-portal-installation-guide-helm-air-gap.png)
+     [View a larger version of this image](/images/enterprise-portal-installation-guide-helm-air-gap.png)
+
+1. On the **Helm Air Gap Install** page, follow the instructions provided to install the chart and then click **Continue**.
+
+1. On the last page of the installation wizard, complete any custom post-installation instructions for the application.
+
+### Download Portal
 
-To install with Helm in an air gap environment:
+To install with Helm in an air gap environment using the Download Portal:
 
 1. In the [Vendor Portal](https://vendor.replicated.com), go to **Customers > [Customer Name] > Reporting**.
 
-1. In the **Download portal** section, click **Visit download portal** to log in to the Download Portal for the customer.
+1. In the **Download portal** section, click **Visit download portal** to log in to the portal.
 
 1. In the Download Portal left nav, click **Existing cluster with Helm**. 
 
@@ -74,23 +110,23 @@ To install with Helm in an air gap environment:
 
 ## Perform Updates
 
-This section describes the processes of performing manual and automatic updates with Helm in air gap environments using the instructions provided in the Download Portal.
+This section describes the processes of performing manual and automatic updates with Helm in air gap environments using the instructions provided in the Enterprise Portal or the Download Portal.
 
 ### 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.
 
 However, the first step prompts the customer to select their current version an the target version to install. This step takes [required releases](/vendor/releases-about#properties) into consideration, thereby guiding the customer to the versions that are upgradable from their current version. 
 
 The additional steps are consistent with installation process until the `preflight` and `install` commands where customers provide the existing values from the cluster with the `helm get values` command. Your customer will then need to edit the `values.yaml` to reference the new image tags.
 
 If the new version introduces new images or other values, Replicated recommends that you explain this at the top of your release notes so that customers know they will need to make additional edits to the `values.yaml` before installing. 
 
-### Automate Updates
+### Automate Updates (Download Portal Only)
 
 The instructions in the Download Portal for automating updates use API endpoints that your customers can automate against. 
 
-The instructions in the Download Portal provide customers with example commands that can be put into a script that they run periodically (nightly, weekly) using GitHub Actions, Jenkins, or other platforms.
+The instructions provide customers with example commands that can be put into a script that they run periodically (nightly, weekly) using GitHub Actions, Jenkins, or other platforms.
 
 This method assumes that the customer has already done a successful manual installation, including the configuration of the appropriate `values`.
 

docs/vendor/helm-install-troubleshooting.mdx

@@ -22,4 +22,26 @@ If any top-level charts in the release use the same name, the associated values
 
 Replicated recommends that you use unique names for top-level Helm charts in the same release.
 
-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. 
+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
+
+### Symptom
+
+You see an empty or incomplete list of application images in the Helm air gap installation instructions provided in the Replicated Enterprise Portal or Download Portal.
+
+Or, when attempting to install, you get an ImagePullBackOff error because Kubernetes is not able to access one or more images referenced in the Helm deployment.
+
+### Cause
+
+The Enterprise Portal and Download Portal provide instructions for installing with Helm in air-gapped environments. As part of installing with Helm in air-gapped environments, users are instructed to pull all required images for the Helm chart and then push them to their local image registry.
+
+To create the list of images for the Helm air gap installation instructions, the Vendor Portal uses the Helm values provided in the HelmChart custom resource `builder` key to template the chart and then parse the output for image references.
+
+If the `builder` key was not configured, then the Vendor Portal uses the default values for the chart when running `helm template`. If the Helm values used when templating the chart do not expose all the images that customers might need to install, then the installation fails when Kubernetes is unable to access one or more images in the Helm deployment from the user's local registry.
+
+### Solution
+
+Configure the `builder` key so that the ouput of `helm template` exposes all the images that might be required for users to install the chart in an air-gapped environment. For more information about how to configure the `builder` key, see [builder](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_.
+
+For more information about why the `builder` key is required to support air gap installations with Helm, see [Why you should create `HelmChart` resources for your Helm-only releases](https://community.replicated.com/t/why-you-should-create-helmchart-resources-for-your-helm-only-releases/1539) in the Replicated Community site.