Edit

System Requirements

Purpose: For platform engineers and field operators, documents the hardware, OS, network, and software requirements for each role: the build host (Zone A), the bastion (Zone C), and the cluster nodes (Zone C). Pinned to the source of truth wherever possible.

Build host (Zone A — connected)

The build host downloads dependencies and produces the Zarf artifact.

OS

| OS | Status | |---|---| | Ubuntu 24.04 LTS | Tested, recommended. Matches UBUNTU_VERSION in config/versions.env. | | Ubuntu 22.04 LTS | Works; not what the build is regression-tested on. | | Other Linux | Best-effort. Requires Python 3.12 and Bash 5+. |

Hardware

| Resource | Minimum | Recommended | |---|---|---| | CPU | 4 cores | 8+ cores | | RAM | 8 GB | 16 GB | | Disk | 100 GB free | 200 GB free, SSD | | Network | 10 Mbps | 100+ Mbps |

Peak disk usage during a build is ~120 GB across build/, assets/, and dist/. After cleanup the artifacts in dist/ total 15–25 GB.

Required software

| Tool | Required version | Source | |---|---|---| | Python | 3.12 or newer | pyproject.toml: requires-python = ">=3.12" | | Git | 2.30 or newer | system package | | pip | matching the Python version | system package |

Runtime Python dependencies are pinned in pyproject.toml and installed by pip install -e .:

jsonschema==4.26.0
pyyaml==6.0.3
typer==0.25.1
rich==15.0.0
python-dotenv==1.2.2

Optional software

| Tool | Why | When | |---|---|---| | Zarf CLI 0.40+ | Build the .tar.zst package and SBOM | If you want a deployable artifact and not just zarf.yaml | | Cosign 2.0+ | Sign packages | For production builds | | Docker or Podman | Image operations and serve | Always, on the bastion | | Terraform 1.14+ | OpenStack provisioning | Only when versions.env was generated with --template openstack |

Network

Outbound HTTPS access (TCP 443) is required to:

| Host | Purpose | |---|---| | github.com, raw.githubusercontent.com | Source repositories | | registry.k8s.io, quay.io, ghcr.io, docker.io | Container images | | dl.k8s.io, storage.googleapis.com | Kubernetes binaries | | archive.ubuntu.com, security.ubuntu.com | OS packages | | pypi.org, files.pythonhosted.org | Python wheels | | charts.jetstack.io, kubernetes.github.io | Helm charts | | registry.terraform.io | Terraform providers (OpenStack only) |

Standard HTTP_PROXY / HTTPS_PROXY / NO_PROXY env vars are honored.

Bastion host (Zone C — disconnected)

The bastion serves the local container registry and apt/pip mirrors.

OS

| OS | Status | |---|---| | Ubuntu 24.04 LTS | Tested, recommended. | | Ubuntu 22.04 LTS | Works. |

Hardware

| Resource | Minimum | Recommended | |---|---|---| | CPU | 4 cores | 8+ cores | | RAM | 8 GB | 16 GB | | Disk | 100 GB free | 200 GB free, SSD | | Network to nodes | 1 Gbps | 10 Gbps |

Disk needs to fit the extracted package (~40 GB) plus the in-place image layer cache (~15 GB).

Required software

| Tool | Why | |---|---| | Zarf CLI 0.40+ | zarf package deploy | | Docker or Podman | Container runtime for registry and nginx | | OpenSSH client | Ansible connectivity to cluster nodes | | opencenter-airgap (optional) | If you prefer serve over zarf package deploy |

Network

| Direction | Port / proto | Source / destination | |---|---|---| | Inbound | 5000/TCP | Container registry, from cluster nodes | | Inbound | 80/TCP | Nginx file server, from cluster nodes | | Inbound | 3000/TCP | Gitea (optional), from cluster nodes | | Inbound | 22/TCP | SSH from operator workstation | | Outbound | 22/TCP, 6443/TCP | Cluster nodes |

Cluster nodes (Zone C — disconnected)

Each control-plane and worker node.

OS

Same as the bastion — Ubuntu 24.04 LTS recommended.

Hardware

| Role | CPU min | RAM min | Disk min | |---|---|---|---| | Control plane | 4 cores | 8 GB | 50 GB | | Worker (light) | 4 cores | 8 GB | 50 GB | | Worker (production) | 16+ cores | 32+ GB | 200+ GB SSD |

Pre-installed

  • Python 3.12+ (for Ansible).

  • OpenSSH server, with the bastion’s key authorized for the deploy user.

Installed by Kubespray

Versions pinned in config/versions.env:

| Component | Variable | |---|---| | containerd | CONTAINERD_VERSION (default 2.1.5) | | runc | RUNC_VERSION (default 1.3.4) | | kubelet, kubectl, kubeadm | KUBERNETES_VERSION (default v1.34.3) | | Calico | CALICO_VERSION (default v3.31.3) |

Network

Required between cluster nodes:

| Port / proto | Purpose | |---|---| | 6443/TCP | Kubernetes API | | 2379–2380/TCP | etcd (control plane) | | 10250/TCP | kubelet API | | 10256/TCP | kube-proxy health | | 179/TCP | Calico BGP | | 4789/UDP | Calico VXLAN (if used) |

Required outbound to bastion: 5000/TCP (registry), 80/TCP (mirrors).

Topology

| Topology | Use | |---|---| | 1 node, combined control plane + worker | Smoke testing only | | 1 control plane, ≥ 1 worker, 1 bastion | Lab | | 3 control plane, ≥ 3 worker, 1 bastion | Recommended for production |

Tested upper bounds: 5 control plane nodes (etcd performance ceiling), 100 workers (Kubernetes default).

Version compatibility

| Subsystem | Pinned in | Default | |---|---|---| | Kubernetes | KUBERNETES_VERSION | v1.34.3 | | Kubespray | KUBESPRAY_VERSION | master | | Python (build host) | pyproject.toml | >=3.12 | | Terraform (OpenStack template) | TERRAFORM_VERSION | 1.14.0 | | Zarf | runtime detected | 0.40+ |

Sanity-checking the host

# Build host
python3 --version            # >= 3.12
git --version                # >= 2.30
df -h $(pwd)                 # at least 100 GB free
which zarf || true           # optional but expected for full builds

# Bastion
zarf version                 # 0.40+
docker --version || podman --version
ss -tlnp | grep -E ':(80|3000|5000)\b'  # ports must be free before deploy

  • ../getting-started/first-deployment.md[First Deployment] — uses this requirements list as prerequisites.

  • versions-env.md[versions.env Reference] — every version pinned here.

  • ../concepts/architecture-overview.md[Architecture Overview] — why the three roles are split this way.