Production-focused implementation guide

Build Kubernetes
where the Internet cannot reach.

A complete, engineering-first runbook for provisioning an air-gapped, hardened Kubernetes platform with Kubespray, Nexus, containerd, Cilium, HA control-plane design, and repeatable validation.

Open the main runbook Explore documentation
Offline-first artifact supply Security and rollback notes End-to-end verification
Cluster ready
3×Control planes
100%Private artifacts
0Internet dependency
KubernetesHA cluster platform
KubesprayRepeatable provisioning
NexusInternal repositories
containerdPrivate image runtime
CiliumModern cluster networking
Why this project exists

Designed for the conditions that simple tutorials ignore.

Public registries, direct package downloads, and permissive networking disappear in a real restricted environment. This repository documents the entire controlled path—from online preparation to offline deployment and operational validation.

Controlled artifact supply chain

Mirror and promote every RPM, binary, Python wheel, Helm package, and container image before deployment.

artifact-verification.shoffline-ready
sha256sum -c checksums.txt
curl -fsS http://nexus.internal/service/rest/v1/status
crictl pull nexus.internal/kubernetes/pause:3.10

Hardening without guesswork

Security controls are paired with impact analysis, validation steps, and rollback guidance.

  • Admission and API controls
  • Firewall and CNI traffic design
  • Secret-safe examples
  • Explicit rollback points

Executable runbooks

Commands are organized in deployment order with expected results and failure checks.

HA-first architecture

Control-plane availability, API VIP access, private registries, and workload isolation are designed together.

Verification at every layer

Validate repositories, nodes, API health, Cilium, DNS, runtime pulls, and workload scheduling.

Reference architecture

One controlled system, from artifact source to workload.

The design separates preparation, repository hosting, automation, control-plane access, networking, and workloads. Each layer has a defined source of truth and an explicit verification boundary.

1
Prepare and verify onlineCollect version-locked packages and images, generate checksums, and record provenance.
2
Promote into NexusExpose only approved RPM, raw, and OCI artifacts to the disconnected network.
3
Deploy through KubesprayUse controlled inventory and group variables to produce a repeatable cluster.
Platform data flow Restricted network
Artifact layer
YUM repositories
OCI images
Binaries & wheels
Automation layer
Inventory
group_vars
Kubespray
Kubernetes layer
HA control plane
containerd + Cilium
Worker workloads
Documentation map

Every critical configuration, one click away.

Start with the complete build guide, then move into the supporting Nexus, firewall, runtime, hardening, and CNI references.

Main Kubespray build guide

Complete path from artifact preparation through final cluster verification.

Nexus preparation

Internal repository design for RPM, raw artifacts, and container images.

Firewalld configuration

Zones, services, Cilium traffic, verification procedures, and rollback.

Offline variables

Kubespray offline URLs, internal endpoints, and artifact path configuration.

containerd variables

Private registry mirrors, runtime settings, and image resolution behavior.

Cluster variables

Core Kubernetes options used to shape the deployed cluster behavior.

Hardening variables

Security controls, admission configuration, and hardened cluster behavior.

Custom CNI variables

Cilium-oriented CNI settings and internal Helm repository configuration.
Deployment workflow

A repeatable path from connected preparation to disconnected operation.

The repository follows a deliberate sequence so failures are detected at the earliest possible boundary.

Prepare artifacts

Mirror RPM repositories, collect wheels and binaries, and pull all required images.

Verify integrity

Generate checksums, confirm versions, and retain a versioned offline bundle.

Transfer offline

Move approved artifacts through the controlled import path into the restricted network.

Seed Nexus

Publish RPM, raw, and OCI content into internal repositories and validate access.

Deploy cluster

Configure inventory and group variables, then execute the Kubespray playbooks.

Verify operation

Check API health, nodes, Cilium, DNS, runtime pulls, scheduling, and recovery paths.

Production safety boundary

Replace every sample IP, hostname, repository name, credential, and certificate reference. Validate the entire process in a lab, retain verified backups, and define rollback checkpoints before applying the runbook to a production environment.

Start building

Turn an isolated network into a repeatable Kubernetes platform.

Follow the main runbook from artifact collection to final cluster validation, then use the supporting documents for each platform layer.

Read the runbook