Building Air-gapped, Offline & Hardened Kubernetes Clusters with Kubespray

What this project is about

Many Kubernetes examples assume full Internet access and a simple single-node cluster. This project focuses on clusters with little or no Internet connectivity and shows how to run air-gapped and offline Kubernetes clusters with Kubespray.

• Fully air-gapped clusters with no direct Internet access from Kubernetes nodes
• Offline / disconnected clusters where you install and operate Kubernetes using internal package repositories and a private container registry
• Multi-node clusters with a highly available control plane
• Opinionated hardening and post-install validation
• A reusable runbook that other engineers can follow end-to-end

Air-gapped vs. Offline – what do we mean?

In this project I use two related terms:

Offline / disconnected Kubernetes cluster

A cluster that is installed and operated without relying on direct Internet access. All OS packages and container images are served from internal mirrors and registries.

Air-gapped Kubernetes cluster

A stricter version of the same idea, where the cluster nodes have no routable path to the public Internet at all. All updates, images and packages must be brought in via bastion hosts, USB, or other controlled paths.

The runbook and configs in this repo work for both: you can use them as-is for strict air-gapped environments, or adapt them for “just offline” clusters that occasionally sync from an upstream mirror.

Deep-dive GitHub issues & extended runbooks

Some of the more advanced parts of this project are documented as GitHub issues. These issues act as extended runbooks you can follow step by step.

• Issue #2 – Removing AlwaysPullImages + Enforcing IfNotPresent – a detailed runbook for removing the AlwaysPullImages admission plugin and enforcing k8s_image_pull_policy: IfNotPresent with: pre-checks, Kubespray vars cleanup, re-applying cluster.yml, fixing kubeadm config / apiserver manifests on each control-plane node, and final verification.
• Issue #3 – GitLab CI/CD for Kubespray-Based Kubernetes Cluster – a full design and implementation guide for wiring this Kubespray project into GitLab CI/CD, with a shell runner on the Kubespray (Ansible) host and jobs like kubespray-full, kubespray-cilium and kubespray-custom-cni that call ci/run-kubespray.sh and pass Kubespray tags to re-apply Kubespray safely to the existing cluster.

These deep-dive issues complement the main runbook by covering day-2 operations such as reconfiguring admission plugins and automating Kubespray re-applies through GitLab pipelines.

Skills demonstrated

• Kubernetes cluster provisioning with Kubespray
• Designing and operating air-gapped and offline / disconnected clusters
• High-availability control plane design
• Private container registry & internal OS repositories
• Security hardening and operational runbooks

Getting started

To dive into the details, start with the main runbook in the GitHub repository and adapt the inventories, group vars and scripts to your own environment (IP addressing, OS version, storage, network policies, etc.).

For a high-level overview, you can also read the accompanying article on Dev.to, which explains the architecture and motivation behind the project.