Building Air-Gapped Kubernetes Clusters

The Air-Gap Challenge

When you're deploying Kubernetes in an environment with zero internet access, everything changes. The standard kubectl apply workflow that relies on pulling images from Docker Hub or ghcr.io simply doesn't work. You need a fundamentally different approach.

In this article, we'll walk through the architecture decisions behind the Agentic RunBook and how we solve the air-gap problem at every layer of the stack.

Image Mirroring Strategy

The first problem to solve is container images. Every Kubernetes component — from the control plane to your application workloads — needs container images. In an air-gapped environment, you need to:

1. Mirror all images to an internal registry
2. Rewrite manifests to point to your internal registry
3. Automate the sync so updates don't require manual intervention

# Example: Mirror images for a specific Helm chart
skopeo sync --src docker --dest docker \
  registry.k8s.io/kube-apiserver:v1.30.0 \
  internal-registry.corp.local/k8s-mirrors/

Helm Charts in Air-Gapped Mode

Every Helm chart in the RunBook ships with configurable image references. Instead of hardcoding public registries, we use a global imageRegistry value:

# values-airgap.yaml
global:
  imageRegistry: internal-registry.corp.local
  imagePullSecrets:
    - name: registry-creds

This single configuration change rewires every chart to pull from your internal registry.

GitOps Without GitHub

ArgoCD and Flux don't need GitHub. They need a Git server. In our RunBook, we include configurations for:

• Gitea — Lightweight, self-hosted Git with a built-in container registry
• ArgoCD — Configured to sync from internal Gitea repositories
• Sealed Secrets — For managing sensitive configs without external KMS

What's Next

This is just the surface. The full RunBook includes 15+ Helm charts, operational playbooks, and video walkthroughs for every component. If you're building infrastructure for disconnected environments, this is your shortcut.