Skip to main content

​
Overview

An air-gapped environment is isolated from the internet. This means all artifacts (helm charts, container images) needed for the platform must be made available locally or in an internal network without internet access. This guide covers the air-gapped-specific setup that must be completed before you follow the standard control plane or compute plane installation:
  1. Push all images and helm charts to a private OCI-compatible registry (or configure a mirror of TrueFoundry’s registry)
  2. Deploy a policy engine (JSPolicy or Kyverno) to intercept and rewrite image/helm references at runtime so they resolve to your private registry
  3. Continue with standard installation — once the above is done, follow the normal control plane or compute plane installation guides
If you set up a mirror or pull-through cache of TrueFoundry’s registry (tfy.jfrog.io) in your own private registry, you can skip the artifact upload step and jump directly to Step 2 — Configure Policy Engine.

​
Requirements

You need an OCI-compatible registry accessible from within the cluster that can serve:
  • OCI-compatible container images with username/password or another auth mechanism
  • OCI-compatible helm charts without authentication
You can reuse TrueFoundry’s own registry (tfy.jfrog.io/tfy-images for images, tfy.jfrog.io/tfy-helm for helm charts) if it is reachable from your environment, rather than replicating everything locally.
You need a secure environment with internet access and push access to the target registry. This is used only for the initial upload and subsequent upgrades. If you are using a registry mirror, this environment is not required.
The following tools must be installed in the environment where you run the upload script:
If you choose JSPolicy as your policy engine, it requires access to an npm registry with the js-yaml package. You must host this from within the cluster or point to TrueFoundry’s npm mirror (https://tfy.jfrog.io/artifactory/api/npm/tfy-npm-registry). This requirement does not apply if you use Kyverno.
If running on AWS, Karpenter needs access to certain APIs via private VPC endpoints. See the Karpenter private cluster guide for details.

​
Step 1 — Upload Artifacts to Your Private Registry

A list of all images and helm charts required by a TrueFoundry installation is maintained in the infra-charts repository as an artifacts-manifest.json per helm chart. Choose the manifest that matches your environment:
EnvironmentManifest
AWS EKStfy-k8s-aws-eks-inframold
Azure AKStfy-k8s-azure-aks-inframold
GCP GKE Standardtfy-k8s-gcp-gke-standard-inframold
Civo Talostfy-k8s-civo-talos-inframold
Generic Kubernetestfy-k8s-generic-inframold
1

Download the artifacts manifest

Shell
wget <link_to_artifacts_manifest>
2

Authenticate with your target registry

Shell
docker login --username <username> --password <password> <target_registry>
3

Set up the upload script

Clone the repo and install dependencies:
Shell
git clone https://github.com/truefoundry/infra-charts.git
python3 -m venv venv && source venv/bin/activate
pip install -r infra-charts/scripts/upload-artifacts/requirements.txt
4

Run the upload script for images and helm charts

Run once for images, once for helm charts:
Shell
# Push container images
python infra-charts/scripts/upload-artifacts/upload_artifacts.py \
  image artifacts-manifest.json <registry_url>

# Push helm charts
python infra-charts/scripts/upload-artifacts/upload_artifacts.py \
  helm artifacts-manifest.json <registry_url>
The script accepts three arguments:
  • artifact_type — either image or helm
  • file_path — path to the artifacts-manifest.json file
  • destination_registry — your private registry URL

​
Step 2 — Configure Policy Engine

A policy engine sits between the Kubernetes API server and the scheduler, intercepting admission requests to mutate image and helm repository references at runtime — transparently redirecting them to your private registry without modifying your deployment manifests. TrueFoundry provides pre-built configuration charts for two policy engines. Choose one:
  • JSPolicy — a lightweight Kubernetes policy engine that uses JavaScript (V8) to write admission policies as code. Well-suited for environments already using the Loft ecosystem.
  • Kyverno — a CNCF policy engine for Kubernetes that uses declarative YAML-based policies. A good choice if you prefer a CNCF-graduated project or already run Kyverno.
1

Create namespace and registry secret

Shell
kubectl create ns jspolicy
If your registry requires authentication, create a pull secret:
Shell
kubectl create secret docker-registry regcred \
  --docker-server=<registry_url> \
  --docker-username=<username> \
  --docker-password=<password> \
  -n jspolicy
2

Install the JSPolicy helm chart

Create jspolicy-values.yaml:
YAML
image: <registry_url>/loftsh/jspolicy:0.2.2
replicaCount: 2
env:
  ## Needed if npmjs.org is not accessible
  npm_config_registry: "https://tfy.jfrog.io/artifactory/api/npm/tfy-npm-registry"

## Only add this section if your registry requires authentication
imagePullSecrets:
- regcred
Install the chart:
Shell
helm install jspolicy \
  <registry_url>/loft/jspolicy -n jspolicy --create-namespace -f jspolicy-values.yaml
3

Install ArgoCD CRDs

These must be installed before the JSPolicy config chart because JSPolicy resources reference ArgoCD CRDs:
Shell
kubectl apply -f https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/crds/application-crd.yaml
4

Install the tfy-jspolicy-config chart

Create jspolicy-config-values.yaml. This configures JSPolicy to rewrite all image and helm repository references to your private registry:
YAML
replaceImageRegistry:
  enabled: true
  excludeNamespaces:
    - kube-system
    - kube-public
    - kube-node-lease
  includeNamespaces: []
  ## Replace all registries with your private registry
  registryReplacementMap:
    "*": <registry_url>

replaceArgoHelmRepo:
  enabled: true
  excludeNamespaces: []
  includeNamespaces: []
  ## Protocol is mandatory (oci:// or http://)
  registryReplacementMap:
    "*": <registry_url>
Install the chart:
Shell
helm install tfy-jspolicy-config <registry_url>/infra-charts/tfy-jspolicy-config \
  --version 0.1.5 -n jspolicy -f jspolicy-config-values.yaml

​
Step 3 — Proceed with Standard Installation

Your cluster is now configured to pull all images and helm charts from your private registry. Continue with the appropriate installation guide:
If you are doing a combined control plane + compute plane installation on the same cluster using a custom registry, refer to the control plane & compute plane installation with custom registry guide for the exact helm values to use.