Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Jul 2, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
b671bf2
wip: clarify how builder is used for helm air gap installs
paigecalvert Jun 26, 2025
30b4c3e
add troubleshooting info
paigecalvert Jun 26, 2025
962288f
edit
paigecalvert Jun 26, 2025
16e9e79
edits to troubleshooting info
paigecalvert Jun 27, 2025
fa7e8d6
add enterprise portal install instructions
paigecalvert Jun 27, 2025
54ae778
edits
paigecalvert Jun 27, 2025
604d749
edits
paigecalvert Jun 27, 2025
85a1dfb
add subheadings
paigecalvert Jun 27, 2025
98c0614
clarify that builder isn't needed in all cases
paigecalvert Jun 30, 2025
4b1987f
clarify that airgap bundles are manually built
paigecalvert Jun 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 13 additions & 11 deletions docs/reference/custom-resource-helmchart-v2.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ Updated this description per feedback to explain how the air gap instructions are automatically available in the enterprise portal & how you have to trigger an air gap bundle build yourself


* 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/>
76 changes: 56 additions & 20 deletions docs/vendor/helm-install-airgap.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added "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..." and "If your default values expose all images needed for air gap installations, you do not need to configure the builder key." per feedback


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**.

Expand Down Expand Up @@ -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`.

Expand Down
24 changes: 23 additions & 1 deletion docs/vendor/helm-install-troubleshooting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Binary file added static/images/enterprise-portal-installation-guide-helm-air-gap.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.