Reference on KubeClaw

Variables Reference

Mon, 01 Jan 0001 00:00:00 +0000

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

Required Variables

Variable	Type	Description
`hcloud_token`	`string`	Hetzner Cloud API Token (sensitive)

Cluster Configuration

Variable	Type	Default	Description
`cluster_name`	`string`	`"k8s-cluster"`	Name prefix for all resources
`location`	`string`	`"fsn1"`	Hetzner Cloud location (`fsn1`, `nbg1`, `hel1`, `ash`, `hil`)

Network Configuration

Variable	Type	Default	Description
`network_ip_range`	`string`	`"10.0.0.0/8"`	IP range for the private network
`subnet_ip_range`	`string`	`"10.0.0.0/24"`	IP range for the subnet
`network_zone`	`string`	`"eu-central"`	Network zone (`eu-central`, `us-east`, `us-west`)
`enable_public_ipv6`	`bool`	`true`	Enable public IPv6 for replica control nodes and worker nodes. The master always has public IPv6 (required for cloudflared). Setting to `false` air-gaps replicas and workers.

Server Configuration

Variable	Type	Default	Description
`server_image`	`string`	`"debian-13"`	Server image to use
`master_control_node_type`	`string`	`"cx23"`	Server type for the master control node (runs cloudflared)
`control_node_types`	`list(object({type, count}))`	`[]`	Server types and counts for replica control nodes
`worker_node_types`	`list(object({type, count}))`	`[]`	Server types and counts for worker nodes

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.

Outputs Reference

Mon, 01 Jan 0001 00:00:00 +0000

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

Network Information

Output	Description
`network_id`	ID of the private network
`network_name`	Name of the private network

Cluster Metadata

Output	Description
`cluster_name`	Name of the cluster
`admin_user`	Admin user name
`ssh_key_prefix`	Prefix used for SSH key filenames

Master Control Node

Output	Description
`master_control_node_id`	ID of the master control node
`master_control_node_name`	Name of the master control node
`master_control_node_private_ip`	Private IP of the master control node

All Control Nodes (master + replicas)

Output	Description
`control_node_count`	Total number of control nodes (master + replicas)
`control_node_ids`	IDs of all control nodes
`control_node_names`	Names of all control nodes
`control_node_private_ips`	Private IPs of all control nodes

Worker Nodes

Output	Description
`worker_node_count`	Number of worker nodes
`worker_node_ids`	IDs of worker nodes
`worker_node_names`	Names of worker nodes
`worker_node_private_ips`	Private IPs of worker nodes

Admin Node

Output	Description
`admin_node_id`	ID of the admin node (null if disabled)
`admin_node_name`	Name of the admin node (null if disabled)
`admin_node_ipv6`	Public IPv6 address of the admin node (null if disabled)
`admin_node_private_ip`	Private IP of the admin node (null if disabled)
`enable_admin_node`	Whether the admin node is enabled

SSH Keys

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

Cloud-Init Templates

Mon, 01 Jan 0001 00:00:00 +0000

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:

Variable	Source
`ssh_public_key`	`local.admin_node_public_key`
`root_password`	`var.root_password`
`admin_user`	`var.admin_user`
`keyboard_layout`	`var.keyboard_layout`

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.

Ansible Playbooks Reference

Mon, 01 Jan 0001 00:00:00 +0000

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:

Variable	Default	Description
`reboot_after_update`	`false`	Reboot after update if the system requires it
`reboot_timeout`	`300`	Timeout (seconds) to wait for reboot

Tasks:

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

security-hardening.yml

Purpose: Apply security measures on all nodes.

OS Images

Mon, 01 Jan 0001 00:00:00 +0000

Hetzner Cloud offers the following Debian/Ubuntu images:

Image	Name	Recommendation
`debian-13`	Debian 13 Trixie	Recommended for K8s
`debian-12`	Debian 12 Bookworm	Stable, well-proven
`ubuntu-24.04`	Ubuntu 24.04 LTS	Good for K8s
`ubuntu-22.04`	Ubuntu 22.04 LTS	Well-proven

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.

Project Structure

Mon, 01 Jan 0001 00:00:00 +0000

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)

File	Purpose
`main.tf`	Core infrastructure: providers, SSH keys, network/subnet, firewalls, servers, cloud-init rendering
`variables.tf`	All configurable inputs with types, defaults, and descriptions
`outputs.tf`	Exposes IPs, SSH keys (sensitive), ssh_config_snippet, and next-steps banner
`terraform.tfvars.example`	Reference configuration (actual `.tfvars` is gitignored)

Cloud-Init Templates

File	Purpose
`cloud-init/admin-node.yaml.tpl`	Minimal jump host: admin user, SSH hardening, fail2ban, public SSH
`cloud-init/control-node.yaml.tpl`	Control plane: cloudflared (master only), UFW, fail2ban, optional NAT64 + K8s prereqs
`cloud-init/worker-node.yaml.tpl`	Worker: restrictive UFW, no TCP forwarding, optional NAT64 + K8s prereqs

Scripts

File	Purpose
`scripts/setup-ssh.sh`	Export SSH keys, generate `~/.ssh/config` with backup
`scripts/ssh-agent-setup.sh`	Fix SSH permissions, start ssh-agent, load keys
`scripts/generate-ansible-inventory.sh`	Build Ansible inventory from OpenTofu state
`scripts/build-docs.sh`	Build the Hugo site locally
`scripts/serve-docs.sh`	Preview the site locally
`scripts/deploy-docs.sh`	Build Hugo and push to `gh-pages`

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.

Cost Estimate

Mon, 01 Jan 0001 00:00:00 +0000

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.