Skip to main content

Packaging Air Gap Bundles for Helm Charts

This topic describes how to package and build air gap bundles for releases that contain one or more Helm charts. This topic applies to applications deployed with Replicated KOTS.

Overview

Air gap bundles (.airgap) contain the images needed to install and run a single release of your application in air gap environments with no outbound internet access. For more information about how to build and download air gap bundles, see Downloading Air Gap Bundles.

When building the .airgap bundle for a release that contains one or more Helm charts, the vendor portal renders the Helm chart templates in the release using values supplied in the KOTS HelmChart custom resource builder key. This ensures that the .airgap bundle includes all images needed to successfully deploy the chart in air gap environments.

Configure the builder Key

To build an .airgap bundle for a release that contains one or more Helm charts, you must configure the builder key in the KOTS HelmChart custom resource for each Helm chart in the release.

In the builder key, you provide the minimum Helm values required to render the chart templates so that the output includes any images that must be included in the air gap bundle. The vendor portal uses these values to render the Helm chart templates when building the .airgap bundle for the release.

The values in the builder key map to values in the given Helm chart's values.yaml file. For example, spec.builder.postres.enabled in the example HelmChart custom resource below would map to a postgres.enabled field in the values.yaml file for the samplechart chart:

# KOTS HelmChart custom resource

apiVersion: kots.io/v1beta2
kind: HelmChart
metadata:
name: samplechart
spec:
chart:
name: samplechart
chartVersion: 3.1.7
builder:
postgres:
enabled: true

For requirements, recommendations, and examples of common use cases for the builder key, see the sections below.

Requirements and Recommendations

The builder key has the following requirements and recommendations:

  • Replicated recommends that you include only the minimum Helm values in the builder key that are required to template the Helm chart with the correct image tags.
  • Use only static, or hardcoded, values in the builder key. You cannot use template functions in the builder key because values in the builder key are not rendered in a customer environment.
  • Any Helm values that are required for rendering Helm chart templates must have a value supplied in the builder key. For more information about the Helm required function, see Using the 'required' function in the Helm documentation.

Example: Set the Image Registry for Air Gap Installations

For air gap installations, if the Replicated proxy service domain proxy.replicated.com is used as the default image name for any images, you need to rewrite the image to the upstream image name so that it can be processed and included in the air gap bundle. You can use the builder key to do this by hardcoding the upstream location of the image (image registry, repository, and tag), as shown in the example below:

apiVersion: kots.io/v1beta2
kind: HelmChart
metadata:
name: samplechart
spec:
chart:
name: samplechart
chartVersion: 3.1.7
builder:
my-service:
image:
registry: 12345.dkr.ecr.us-west-1.amazonaws.com
repository: my-app
tag: "1.0.2"

When building the .airgap bundle for the release, the vendor portal uses the registry, repository, and tag values supplied in the builder key to template the Helm chart, rather than the default values defined in the Helm values.yaml file. This ensures that the image is pulled from the upstream registry using the credentials supplied in the vendor portal, without requiring any changes to the Helm chart directly.

Example: Include Conditional Images

Many applications have images that are included or excluded based on a given condition. For example, enterprise users might have the option to deploy an embedded database with the application or bring their own database. To support this use case for air gap installations, the images for any conditionally-deployed components must always be included in the air gap bundle.

For example, a Helm chart might include a conditional PostgreSQL Deployment, as shown in the Helm template below:

{{- if .Values.postgresql.enabled }}
apiVersion: apps/v1
kind: Deployment
metadata:
name: postgresql
labels:
app: postgresql
spec:
selector:
matchLabels:
app: postgresql
template:
metadata:
labels:
app: postgresql
spec:
containers:
- name: postgresql
image: "postgres:10.17"
ports:
- name: postgresql
containerPort: 80
# ...
{{- end }}

To ensure that the postgresql image is included in the air gap bundle for the release, the postgresql.enabled value is added to the builder key of the HelmChart custom resource and is hardcoded to true:

apiVersion: kots.io/v1beta2
kind: HelmChart
metadata:
name: samplechart
spec:
chart:
name: samplechart
chartVersion: 3.1.7
values:
postgresql:
enabled: repl{{ ConfigOptionEquals `postgres_type` `embedded_postgres`}}
builder:
postgresql:
enabled: true