Welcome¶

hetzner-kube-express is the shortcut from zero to a solid Kubernetes platform on Hetzner Cloud: one terragrunt run --all apply gets you a batteries-included cluster with ingress, observability, storage, cert-manager, gitops, postgres operator, and container registry.

What you get¶

flowchart LR
  user["Browser / kubectl / docker"]
  dns["Cloudflare DNS<br/>(via ExternalDNS)"]
  nodes["Hetzner agent nodes<br/>(Klipper exposes Traefik)"]
  traefik["Traefik<br/>(ingress + TLS)"]
  apps["Argo CD · SigNoz · Harbor · your apps"]
  cert["cert-manager<br/>(Let's Encrypt)"]
  r2[("Cloudflare R2<br/>state + secrets + kubeconfig")]
  tg["Terragrunt<br/>(one apply, full DAG)"]

  user --> dns --> nodes --> traefik --> apps
  cert -. issues certs .-> traefik
  tg -. provisions .-> nodes
  tg <-. reads/writes .-> r2

A single terragrunt run --all apply from an environment folder provisions the cluster, wires DNS, requests TLS certificates, and installs the bundled services. State and secrets stay in R2, so a fresh clone can pick up where the last apply left off.

What's bundled¶

Traefik

Ingress controller. Routes hostnames to in-cluster services and terminates TLS.
cert-manager

Automatic Let's Encrypt certificates via HTTP-01 through Traefik.
Argo CD

GitOps controller, exposed via a Traefik Ingress.
CloudNativePG

PostgreSQL operator, ready for declarative DB clusters.
Harbor

Container registry with bundled Trivy image scanning, exposed via a Traefik Ingress.
SigNoz

Observability stack with auto-instrumented Kubernetes metrics and auto-imported dashboards.

Built on top of¶

k3s via kube-hetzner

Lightweight Kubernetes distribution provisioned on Hetzner cx23 nodes in fsn1.
Cilium + Hubble

CNI with kube-proxy replacement; Hubble adds in-cluster network observability.
Klipper

k3s ServiceLB; exposes Traefik on every node's public IP so no paid Hetzner LB is needed.
Cloudflare R2

S3-compatible storage for Terraform state and per-env secrets.json (one bucket, both jobs).
ExternalDNS + Cloudflare DNS

Ingress-driven A records wired automatically to the cluster's agent node pool.
Terragrunt

Orchestrates the Terraform units as a dependency graph, one apply across the whole stack.

Cost shape¶

The default dev environment runs on a handful of cx23 nodes for less than $20/month. Most managed Kubernetes services charge ~$70/month just to keep the control plane running — before a single workload.

Special thanks¶

Huge thanks to the kube-hetzner maintainers. Their Terraform module does the heavy lifting — k3s on Hetzner, Cilium, Traefik, Klipper, cert-manager — and this project is largely a thin opinionated wrapper around it. If you find this useful, consider starring or sponsoring their repo.

Where to next¶

Get started User guide Join as a teammate

Want the high-level map first? Read How it fits together for the Terragrunt graph, module wiring, and R2 mental model.
New cluster? Head to Getting started for the one-time setup as cluster owner.
Onboarding onto an existing cluster? See Joining as a teammate.
Sending a PR? See Contributing for the repo layout, conventions, and Cursor skills setup.