Deploying to Air-Gapped Environments

1. Downloading Charts for Offline Use

Command	Description	Flags
helm pull	Downloads a chart from a repository and saves it locally	`--version`, `--destination`, `--untar`
helm repo add	Adds a chart repository to local Helm configuration	`--username`, `--password`
helm repo update	Updates the list of charts from all repositories	None

Example: Pulling a Chart Locally

helm pull nginx --version 1.2.3 --destination ./charts

Example: Adding a Private Repository

helm repo add private https://my-private-repo.com/chart --username user --password pass

Note: Ensure that the chart version matches the one used in production to avoid compatibility issues.

2. Bundling Chart Dependencies

Property	Description	Values	Notes
dependencies	List of chart dependencies	`[{name, version, repository, condition, tags, enabled}]`	Used in `Chart.yaml`
alias	Alias for a dependency	`string`	Used to avoid naming conflicts
repository	Repository URL or alias	`string`	Can be local path or remote repo URL
version	Version constraint	`string`	Supports semantic versioning (e.g., `>=1.0.0`)
condition	Conditional rendering	`string`	Path to a value in `values.yaml`

Example: Chart.yaml with Dependencies

apiVersion: v2
name: my-app
version: 1.0.0
dependencies:
  - name: nginx
    version: "1.2.3"
    repository: https://kubernetes-charts.storage.googleapis.com
  - name: postgresql
    version: "10.1.0"
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled

Example: values.yaml with Conditional Dependency

postgresql:
  enabled: true
  auth:
    postgresPassword: "secret"

Note: Dependencies are resolved and bundled using helm dependency build. Ensure all dependencies are accessible in the environment where the chart is deployed.

3. Mirroring Container Images

Image Source	Mirroring Method	Notes
Original Registry	Skopeo / Crane	Used to copy images from source to target registry
Target Registry	Private or local registry	Must be accessible in air-gapped environment

Example: Using Skopeo to Mirror Images

skopeo copy --src-creds username:password --dest-creds username:password docker://original-registry.com/image:tag docker://mirror-registry.com/image:tag

Note: Ensure the target registry is accessible in the air-gapped environment before mirroring.

Warning: Skopeo requires access to both source and target registries during the copy process.

4. Setting Up Private Registry

Component	Description	Notes
Registry Type	`Harbor`, `Nexus`, `Quay`	Popular private registry solutions for Helm charts
Chart Storage	`OCI Registry`, `File System`	Storage backend for chart artifacts
Authentication	`Basic Auth`, `Token`	Access control methods for registry

Example: Harbor Configuration

registry:
  host: "harbor.example.com"
  username: "admin"
  password: "secret123"
  chartRepo:
    name: "private-charts"
    url: "https://harbor.example.com/chartrepo/private-charts"

Note: Ensure registry is accessible from air-gapped environment and has proper TLS configuration.

Warning: Do not expose private registry credentials in public repositories or logs.

Feature	Support Status	Notes
OCI Artifact Support	NEW	Support for OCI-compliant chart storage
Chart Push/Pull	DEPRECATED	Legacy Helm registry commands may be removed in future versions

5. Configuring Air-Gapped Repository

Example: Setting up local Helm repository

# Create local repository directory
mkdir -p /opt/helm-repo

# Download chart from remote registry
helm pull mychart --version 1.2.3 --destination /opt/helm-repo

# Serve charts locally
helm serve --repo-dir /opt/helm-repo --address 0.0.0.0:8080

Configuration	Description	Value
helm.repo.url	URL to the local Helm repository	`http://localhost:8080`
helm.repo.name	Name of the repository in Helm	`local-repo`

Note: Ensure the repository is accessible from all nodes in the air-gapped environment.

Warning: Make sure to synchronize the local repository with the latest chart versions regularly.

6. Updating Image References

Reference Type	Description	Example	Notes
image.repository	Repository name for the container image	`"nginx"`	Used in conjunction with `image.tag`
image.tag	Tag of the container image	`"1.21.6"`	Can be a version or digest
image.pullSecrets	Secrets to use for pulling images from private registries	`[{ name: "my-secret" }]`	Required for private registries
image.pullPolicy	Policy for pulling images (Always, IfNotPresent, Never)	`"IfNotPresent"`	Defaults to `IfNotPresent`

Example: Updating Image References in Values

image:
  repository: "my-registry.com/my-app"
  tag: "v1.2.3"
  pullPolicy: "Always"
  pullSecrets:
    - name: "my-private-registry-secret"

Example: Using Image Digests

image:
  repository: "nginx"
  tag: "sha256:abc123..."

Note: When deploying in air-gapped environments, ensure that all image references point to local or mirrored registries to avoid network dependencies.

7. Packaging All Dependencies

Dependency Type	Description	Packaging Method	Notes
Chart Dependencies	Dependencies declared in `Chart.yaml`	`helm dependency build`	Downloads and packages dependencies into `charts/` directory
Local Chart Archives	Pre-packaged chart archives (e.g., `.tgz`)	`helm package`	Can be included in `charts/` for offline use
External Chart Repositories	Charts from external Helm repositories	`helm repo add` + `helm dependency build`	Must be mirrored or cached locally for air-gapped environments
Local Chart Sources	Source charts in local directories	`helm package` or `helm dependency build`	Can be bundled as sub-charts or archived for reuse

Example: Packaging Chart Dependencies

helm dependency build my-chart
helm package my-chart

Note: When packaging for air-gapped environments, ensure all dependencies are included in the final chart archive or local repository.

8. Validating Offline Installation

Example: Check Chart Integrity

helm chart export my-chart-1.0.0.tgz -d /tmp/chart-export
helm lint /tmp/chart-export

Validation Step	Description	Command	Status
Chart Integrity	Ensures chart files are not corrupted	`helm chart export <chart>.tgz -d /tmp/chart-export`	NEW
Linting	Checks for common issues in chart structure	`helm lint /tmp/chart-export`	NEW
Template Rendering	Validates that templates render without errors	`helm template /tmp/chart-export`	NEW

Note: Ensure all dependencies are included in the offline package.

Warning: Do not skip linting in air-gapped environments.

Validation Checklist

Chart exports correctly
Lint passes without errors
Templates render successfully
All dependencies are present

9. Managing Updates in Air-Gapped

Update Method	Description	Notes
helm pull	Downloads a chart from a registry to local disk	Useful for offline storage and transfer
helm package	Packages a chart directory into a chart archive (.tgz)	Can be used to create local archives for distribution
helm repo add	Adds a chart repository to local Helm configuration	Must be done before pulling charts from that repo

Example: Pulling and Packaging a Chart

helm pull nginx-ingress --version 1.34.0
helm package nginx-ingress-1.34.0.tgz

Note: Ensure that the chart version matches the target environment's requirements.

Warning: Chart dependencies must also be managed in air-gapped environments.

10. Documenting Air-Gapped Procedures

Example: Helm Chart Documentation Template

# Air-Gapped Deployment Documentation
#
# Chart Name: my-app
# Version: 1.2.3
# Namespace: production

## Prerequisites
- Helm v3.8.0+
- Private registry accessible in air-gapped environment
- Local copy of all required container images

## Deployment Steps
1. Pull chart from source repository
2. Package chart locally: `helm package .`
3. Transfer packaged chart to air-gapped environment
4. Load images into local registry
5. Install chart: `helm install my-app ./my-app-1.2.3.tgz --set image.registry=localhost:5000`

## Configuration
- Registry URL: `localhost:5000`
- Chart Values: [values.yaml](#)

Documentation Section	Description	Required Elements
Prerequisites	Preconditions needed for deployment	List of tools, access rights, and environment setup
Deployment Steps	Step-by-step process for installation	Each step must be numbered and actionable
Configuration	Chart-specific settings and overrides	Values files, registry URLs, namespace details

Note: Ensure all documentation is versioned and stored in a secure, accessible location for future reference.

Warning: Never include sensitive credentials or private keys in documentation templates.