Reference

• 1: Variables Reference
• 2: Outputs Reference
• 3: Cloud-Init Templates
• 4: Ansible Playbooks Reference
• 5: OS Images
• 6: Project Structure
• 7: Cost Estimate

1 - Variables Reference

All configurable inputs for the OpenTofu infrastructure. Set these in terraform.tfvars.

Required Variables

Cluster Configuration

Network Configuration

Server Configuration

The cost-optimized x86 line is cx23, cx33, cx43, and cx53; the Arm equivalents are cax11 through cax41. See Cost Estimate for specifications, current prices, and the constraints on the Arm line.

Node type examples

# Master-only (default)
master_control_node_type = "cx23"
control_node_types = []
worker_node_types  = []

# 3 control nodes + 2 workers
control_node_types = [
  { type = "cx23", count = 2 },
]
worker_node_types = [
  { type = "cx23", count = 2 },
]

# Mixed worker types
worker_node_types = [
  { type = "cx23", count = 2 },
  { type = "cx33", count = 1 },
]

Authentication

SSH Keys

If left empty, new keys will be auto-generated and stored in the OpenTofu state. When using custom keys, manage private keys yourself.

Cloudflare Configuration

Admin Node

NAT64/DNS64

Kubernetes

2 - Outputs Reference

All outputs exposed by the OpenTofu configuration. These are consumed by the setup scripts and can be queried manually.

Network Information

Cluster Metadata

Master Control Node

All Control Nodes (master + replicas)

Worker Nodes

Admin Node

SSH Keys

These outputs are sensitive when auto-generated keys are used.

SSH Config

Feature Flags

Next Steps Banner

Querying outputs

# List all outputs
tofu output

# Get a specific output
tofu output master_control_node_private_ip

# Get a sensitive output (raw)
tofu output -raw control_node_ssh_private_key

# Export SSH key to file
tofu output -raw control_node_ssh_private_key > ~/.ssh/k8s-cluster_control-node_key
chmod 600 ~/.ssh/k8s-cluster_control-node_key

3 - Cloud-Init Templates

Cloud-init templates are located in cloud-init/ and rendered by OpenTofu via templatefile() in main.tf. They configure each server on first boot.

admin-node.yaml.tpl

Purpose: Minimal jump host for initial SSH access.

Used by: hcloud_server.admin_node

Template variables:

What it configures:

• Admin user with sudo NOPASSWD
• SSH hardening with AllowTcpForwarding yes (needed for ProxyJump)
• fail2ban for SSH protection
• UFW allowing public SSH (port 22 from anywhere)

control-node.yaml.tpl

Purpose: Kubernetes control plane node with optional Cloudflare Tunnel.

Used by: hcloud_server.master_control_node, hcloud_server.control_node_replica

Template variables:

What it configures:

• Admin user with sudo NOPASSWD and root password for emergency console access
• SSH hardening (key-only auth, AllowTcpForwarding yes)
• fail2ban for SSH protection
• UFW: SSH from internal network (10.0.0.0/8) + localhost (for Cloudflare Tunnel)

Conditional sections:

• is_master = true: Installs cloudflared, allows SSH from localhost, creates /etc/cloudflared/config.yml with edge-ip-version: "6". When cloudflare_tunnel_token is set, runs cloudflared service install <token> to auto-configure the tunnel as a systemd service.
• is_master = false: Skips cloudflared installation (token always empty for replicas)
• enable_nat64 = true: Configures DNS64 resolvers in systemd-resolved, adds NAT64 route (64:ff9b::/96), creates networkd-dispatcher persistence script
• enable_k8s_prereqs = true: Installs the selected container runtime (containerd with SystemdCgroup and sandbox image fix, or cri-o from OBS repo with kubelet socket configuration), kubeadm, kubelet, kubectl, loads kernel modules (overlay, br_netfilter), sets sysctl params, disables swap, opens kubelet (10250) + etcd (2379-2380) ports

worker-node.yaml.tpl

Purpose: Kubernetes worker node with restricted network access.

Used by: hcloud_server.worker_node

Template variables:

What it configures:

• Admin user with sudo NOPASSWD and root password for emergency console access
• SSH hardening with AllowTcpForwarding no (workers cannot be used as jump hosts)
• fail2ban for SSH protection
• UFW: deny all by default, SSH from internal network only, outbound limited to DNS + HTTP/S

Conditional sections:

• enable_nat64 = true: Uses DNS64 resolvers instead of Hetzner DNS, adds NAT64 prefix UFW rule
• enable_k8s_prereqs = true: Same as control node prerequisites (runtime selected by container_runtime), but without etcd ports

Template rendering

Templates are rendered in main.tf via templatefile():

user_data = templatefile("${path.module}/cloud-init/control-node.yaml.tpl", {
  ssh_public_key         = local.control_node_public_key
  root_password          = var.root_password
  admin_user             = var.admin_user
  keyboard_layout        = var.keyboard_layout
  is_master              = true
  enable_nat64           = var.enable_nat64
  dns64_resolvers        = var.dns64_resolvers
  enable_k8s_prereqs     = var.enable_k8s_prereqs
  kubernetes_version     = var.kubernetes_version
  container_runtime      = var.container_runtime
  cloudflare_tunnel_token = var.cloudflare_tunnel_token
})

4 - Ansible Playbooks Reference

All playbooks are in ansible/playbooks/ and target the k8s_cluster host group by default.

update-system.yml

Purpose: Run apt update && apt upgrade on all nodes.

Usage:

cd ansible
ansible-playbook playbooks/update-system.yml
ansible-playbook playbooks/update-system.yml --limit control_nodes
ansible-playbook playbooks/update-system.yml -e "reboot_after_update=true"

Variables:

Tasks:

1. Update apt cache
2. Upgrade all packages (dist-upgrade with autoremove)
3. Check if reboot is required (/var/run/reboot-required)
4. Reboot if required and enabled
5. Wait for system to come back online

security-hardening.yml

Purpose: Apply security measures on all nodes.

Usage:

cd ansible
ansible-playbook playbooks/security-hardening.yml

Variables:

Tasks:

1. Install and configure unattended-upgrades (security updates only)
2. Enable automatic update checks (daily)
3. Verify fail2ban is running and monitoring SSH
4. Set secure permissions on /etc/shadow
5. Disable core dumps
6. Apply sysctl hardening (reverse path filtering, source route rejection, ASLR)

configure-nat64.yml

Purpose: Configure DNS64 resolvers and NAT64 routing on already-running nodes. Cloud-init only runs at first boot – use this playbook for existing nodes or to reconfigure.

Usage:

cd ansible
ansible-playbook playbooks/configure-nat64.yml
ansible-playbook playbooks/configure-nat64.yml --limit control_nodes
ansible-playbook playbooks/configure-nat64.yml -e '{"dns64_resolvers":["2a01:4f8:c2c:123f::1"]}'

Variables:

Tasks:

1. Configure DNS64 resolvers in systemd-resolved
2. Add NAT64 route via default IPv6 gateway
3. Create networkd-dispatcher script for persistent route
4. Update UFW rules on worker nodes (remove Hetzner DNS, add DNS64 + NAT64 rules)
5. Verify DNS64 resolution and NAT64 connectivity

prepare-k8s-nodes.yml

Purpose: Install container runtime (containerd or CRI-O), kubeadm, kubelet, and kubectl on already-running nodes. Cloud-init only runs at first boot – use this playbook for existing nodes.

Usage:

cd ansible
ansible-playbook playbooks/prepare-k8s-nodes.yml
ansible-playbook playbooks/prepare-k8s-nodes.yml --limit control_nodes
ansible-playbook playbooks/prepare-k8s-nodes.yml -e "kubernetes_version=1.32"
ansible-playbook playbooks/prepare-k8s-nodes.yml -e "container_runtime=cri-o"

Variables:

Tasks:

1. Load kernel modules (overlay, br_netfilter)
2. Set sysctl parameters (bridge-nf-call-iptables, ip_forward)
3. Disable swap
4. Install and configure container runtime (containerd with SystemdCgroup, or CRI-O from OBS repo)
5. Add Kubernetes apt repository
6. Install kubelet, kubeadm, kubectl (held at current version)
7. Open UFW ports on control nodes (kubelet 10250, etcd 2379-2380)
8. Verify kubeadm version and container runtime status

Ansible configuration

The ansible.cfg file configures:

• Remote user: kubernetes-admin
• Host key checking: disabled (nodes are ephemeral)
• Privilege escalation: sudo NOPASSWD
• SSH args: ForwardAgent, ControlMaster, ControlPersist for fast connections
• Pipelining: enabled for performance

5 - OS Images

Hetzner Cloud offers the following Debian/Ubuntu images:

Why Debian 13?

• Stability: long support cycles
• Compatibility: the pkgs.k8s.io apt repository used for kubeadm, kubelet, and kubectl ships Debian packages
• Small footprint: leaner than Ubuntu, but not as small as Alpine
• No glibc/musl issues: unlike Alpine, no compatibility problems

Hetzner Cloud doesn’t provide dedicated “slim” or “minimal” variants. The standard images are fairly compact already.

6 - Project Structure

kubeclaw/
├── main.tf                          # Infrastructure (providers, network, firewalls, servers)
├── variables.tf                     # All configurable inputs
├── outputs.tf                       # IPs, SSH keys, ssh_config_snippet, next-steps banner
├── terraform.tfvars.example         # Example configuration
├── hugo.yaml                        # Hugo + Docsy configuration
├── package.json                     # Docsy asset dependencies
├── themes/docsy/                    # Pinned Docsy theme submodule
├── aibox.toml                       # Dev Container source of truth (aibox apply)
├── aibox.lock                       # Pinned aibox toolchain versions
├── CLAUDE.md                        # Claude Code project instructions
├── README.md                        # Project overview (concise)
├── LICENSE                          # MIT License
├── .gitignore
├── .devcontainer/
│   ├── devcontainer.json            # Generated by aibox; do not edit directly
│   ├── Dockerfile                   # Generated by aibox; do not edit directly
│   ├── docker-compose.yml           # Generated by aibox; do not edit directly
│   ├── Dockerfile.local             # Project layer: installs cloudflared
│   └── docker-compose.override.yml  # Project override: writable SSH mount
├── cloud-init/
│   ├── admin-node.yaml.tpl         # Admin node (temporary jump host with public IPv6)
│   ├── control-node.yaml.tpl       # Control node (cloudflared on master, UFW, fail2ban, k8s prereqs)
│   └── worker-node.yaml.tpl        # Worker node (isolated, outbound DNS/HTTP/S only, k8s prereqs)
├── scripts/
│   ├── setup-ssh.sh                # Export SSH keys from tofu state, generate ~/.ssh/config
│   ├── ssh-agent-setup.sh          # Fix SSH permissions, start ssh-agent, load keys
│   ├── generate-ansible-inventory.sh  # Build ansible/inventory.ini from tofu state
│   ├── build-docs.sh              # Build Hugo site locally
│   ├── serve-docs.sh              # Preview Hugo site locally
│   └── deploy-docs.sh             # Build and deploy Hugo to gh-pages
├── ansible/
│   ├── ansible.cfg                  # Ansible defaults (user, pipelining, SSH args)
│   ├── inventory.ini                # Auto-generated inventory (do not hand-edit)
│   └── playbooks/
│       ├── update-system.yml        # System updates with optional reboot
│       ├── security-hardening.yml   # Unattended upgrades, fail2ban, sysctl hardening
│       ├── configure-nat64.yml      # NAT64/DNS64 for IPv4 reachability on running nodes
│       └── prepare-k8s-nodes.yml   # Kubernetes prerequisites (container runtime, kubeadm) on running nodes
├── assets/                         # Project brand layer for the Hugo site
│   ├── icons/logo.svg              # projectious mark used in the navbar
│   └── scss/                       # Brand tokens and Docsy surface styles
├── layouts/                        # Project template overrides (favicons, head hooks)
├── static/favicons/                # Brand favicon set
├── content/                        # Hugo documentation source
│   ├── _index.md                   # Branded landing page
│   └── docs/                       # Documentation section
│       ├── _index.md               # Documentation overview
│       ├── quick-start.md          # Combined prerequisites + deployment steps
│       ├── introduction/           # Concepts: architecture, security, DNS/NAT64
│       ├── guide/                  # Ordered deployment path (dev container -> OpenClaw)
│       ├── how-to/                 # Focused procedures, incl. the manual setup alternative
│       ├── reference/              # Variables, outputs, templates, playbooks, structure
│       ├── operations/             # Day-two: scaling, rotation, upgrades, troubleshooting
│       ├── roadmap/                # Planned work
│       └── contributing/           # Development setup and code of conduct
└── public/                         # Generated site output (gitignored)

Key Files

Infrastructure (root level)

Cloud-Init Templates

Scripts

Dev Container

The aibox configuration in aibox.toml is the source of truth for generated Dev Container files. Run aibox apply after changing it; do not hand-edit .devcontainer/Dockerfile, docker-compose.yml, or devcontainer.json. Dockerfile.local and docker-compose.override.yml are project-owned extensions and are safe to edit.

Ansible

Documentation site

7 - Cost Estimate

All figures are list prices in EUR excluding VAT, current as of the Hetzner price adjustment of 15 June 2026. Hetzner bills hourly; the monthly figure is the cap you will not exceed. Always check Hetzner Cloud pricing before committing – prices changed several times during 2026.

Server types

KubeClaw defaults to the cost-optimized CX line (shared vCPU, x86). The CAX line offers the same resources on Ampere Arm cores, but is only available in the German and Finnish locations (fsn1, nbg1, hel1) and requires arm64 container images throughout the cluster.

The higher-performance CPX (dedicated AMD share) and CCX (fully dedicated) lines are considerably more expensive – cpx22 is €19.49/month and ccx13 is €42.99/month – and are rarely worth it for a learning or small-production cluster.

Additional costs

Example: 2-node cluster

Scaling costs

Server cost only; add block volumes for any workload that needs persistent storage.

Notes

• The admin node (cx23, €5.49/month) is temporary. Set enable_admin_node = false once the Cloudflare Tunnel works, and the charge stops – see Quick Start.
• Mixed server types are supported, so workers can be sized independently of the control plane. See Scale Up/Down.
• Snapshots and backups are billed separately and are not included above.