set tmp_script (mktemp); curl -sSL -o "{tmp_script}" https://raw.githubusercontent.com/kube-hetzner/terraform-hcloud-kube-hetzner/master/scripts/create.sh; chmod +x "{tmp_script}"; bash "{tmp_script}"; rm "{tmp_script}"

alias createkh='tmp_script=$(mktemp) && curl -sSL -o "${tmp_script}" https://raw.githubusercontent.com/kube-hetzner/terraform-hcloud-kube-hetzner/master/scripts/create.sh && chmod +x "${tmp_script}" && "${tmp_script}" && rm "${tmp_script}"'

mkdir /path/to/your/new/folder
cd /path/to/your/new/folder
curl -sL https://raw.githubusercontent.com/kube-hetzner/terraform-hcloud-kube-hetzner/master/kube.tf.example -o kube.tf
curl -sL https://raw.githubusercontent.com/kube-hetzner/terraform-hcloud-kube-hetzner/master/packer-template/hcloud-leapmicro-snapshots.pkr.hcl -o hcloud-leapmicro-snapshots.pkr.hcl
curl -sL https://raw.githubusercontent.com/kube-hetzner/terraform-hcloud-kube-hetzner/master/packer-template/hcloud-microos-snapshots.pkr.hcl -o hcloud-microos-snapshots.pkr.hcl
export HCLOUD_TOKEN="your_hcloud_token"
packer init hcloud-leapmicro-snapshots.pkr.hcl
for distro in k3s rke2; do
  packer build -var "selinux_package_to_install=${distro}" hcloud-leapmicro-snapshots.pkr.hcl
done
# (optional legacy)
# packer init hcloud-microos-snapshots.pkr.hcl
# packer build hcloud-microos-snapshots.pkr.hcl
hcloud context create <project-name>

Selective k3s upgrade:

kubectl label --overwrite node <node-name> k3s_upgrade=true
kubectl label node <node-name> k3s_upgrade-  # disable

Or delete upgrade plans:

kubectl delete plan k3s-agent -n system-upgrade
kubectl delete plan k3s-server -n system-upgrade

Manual OS upgrade:

kubectl drain <node-name>
ssh root@<node-ip>
systemctl start transactional-update.service
reboot

For CRD-dependent applications:

user_kustomizations = {
  "1" = {
    source_folder = "extra-manifests"
    kustomize_parameters = {
      target_namespace = "argocd"
    }
    pre_commands = ""
    post_commands = <<-EOT
      kubectl -n argocd wait --for condition=established --timeout=120s crd/appprojects.argoproj.io
      kubectl -n argocd wait --for condition=established --timeout=120s crd/applications.argoproj.io
      kubectl apply -f /var/user_kustomize/1/argocd-projects.yaml
      kubectl apply -f /var/user_kustomize/1/argocd-application-argocd.yaml
    EOT
  }
}

# Status
kubectl -n kube-system exec --stdin --tty cilium-xxxx -- cilium status --verbose

# Monitor traffic
kubectl -n kube-system exec --stdin --tty cilium-xxxx -- cilium monitor

# List services
kubectl -n kube-system exec --stdin --tty cilium-xxxx -- cilium service list

Full Cilium cheatsheet

Control outgoing traffic with static IPs:

{
  name        = "egress",
  server_type = "cx23",
  location    = "nbg1",
  labels      = ["node.kubernetes.io/role=egress"],
  taints      = ["node.kubernetes.io/role=egress:NoSchedule"],
  floating_ip = true,
  count       = 1
}

Configure Cilium:

locals {
  cluster_ipv4_cidr = "10.42.0.0/16"
}

cluster_ipv4_cidr = local.cluster_ipv4_cidr
enable_kube_proxy = false

cilium_values = <<-EOT
ipam:
  mode: kubernetes
k8s:
  requireIPv4PodCIDR: true
kubeProxyReplacement: true
routingMode: native
ipv4NativeRoutingCIDR: "10.0.0.0/8"
endpointRoutes:
  enabled: true
loadBalancer:
  acceleration: native
bpf:
  masquerade: true
egressGateway:
  enabled: true
MTU: 1450
EOT

Cilium Egress Gateway requires kube-proxy replacement, so keep `enable_kube_proxy = false` when enabling it.

# Optional: keep selected egress policies pinned to a Ready egress node automatically
cilium_egress_gateway_ha_enabled = true

Example policy:

apiVersion: cilium.io/v2
kind: CiliumEgressGatewayPolicy
metadata:
  name: egress-sample
  labels:
    kube-hetzner.io/egress-ha: "true"
spec:
  selectors:
    - podSelector:
        matchLabels:
          org: empire
          class: mediabot
          io.kubernetes.pod.namespace: default
  destinationCIDRs:
    - "0.0.0.0/0"
  excludedCIDRs:
    - "10.0.0.0/8"
  egressGateway:
    nodeSelector:
      matchLabels:
        node.kubernetes.io/role: egress
    egressIP: { FLOATING_IP }

Full Egress Gateway docs

Cilium can own Gateway API directly:

cni_plugin                 = "cilium"
enable_kube_proxy         = false
cilium_gateway_api_enabled = true

When enabled, kube-hetzner installs the standard Gateway API CRDs for the selected Cilium line, enables gatewayAPI.enabled in Cilium values, and enables cert-manager Gateway API support. This is separate from Traefik's Kubernetes Gateway provider. Choose one Gateway API controller per cluster; v3 rejects enabling Cilium Gateway API and Traefik's Gateway provider at the same time.

Use examples/cilium-gateway-api for a working GatewayClass/Gateway/HTTPRoute/cert-manager HTTP-01 starting point.

k3s and RKE2 can use their embedded Spegel registry mirror to share images between trusted cluster nodes:

embedded_registry_mirror = {
  enabled                  = true
  registries               = ["docker.io", "registry.k8s.io", "ghcr.io", "quay.io"]
  disable_default_endpoint = false
}

kube-hetzner sets embedded-registry: true on server nodes and merges empty mirror entries into the effective registries.yaml. Existing registries_config entries and endpoints are preserved.

This is opt-in because the mirror assumes equal node trust. Images pulled with credentials on one node may be shared with other nodes, and tags can be poisoned by a node that can place images in containerd. Use digest-pinned images for critical workloads. In Tailscale multinetwork clusters, advertised node-private routes are required so the mirror can reach peers across Network shards.

Cert-Manager handles HA certificate management (Traefik CE is stateless).

1. Configure your issuer
2. Add annotations to Ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt
spec:
  tls:
    - hosts:
        - "*.example.com"
      secretName: example-com-letsencrypt-tls
  rules:
    - host: "*.example.com"
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-service
                port:
                  number: 80

Full Traefik + Cert-Manager guide

Ingress-Nginx with HTTP challenge: Add load_balancer_hostname = "cluster.example.org" to work around this known issue.

F5 NGINX Ingress Controller: ingress_controller = "nginx" installs the Kubernetes ingress-nginx controller. To run the F5 controller, set ingress_controller = "none" and install F5's chart separately.

Create (recommended):

export HCLOUD_TOKEN=<your-token>
for distro in k3s rke2; do
  packer build -var "selinux_package_to_install=${distro}" ./packer-template/hcloud-leapmicro-snapshots.pkr.hcl
done

Create (legacy MicroOS):

export HCLOUD_TOKEN=<your-token>
packer build ./packer-template/hcloud-microos-snapshots.pkr.hcl

Delete:

hcloud image list
hcloud image delete <image-id>

Override the default OS snapshot on any nodepool or individual node with os_snapshot_id:

agent_nodepools = [
  {
    name        = "storage",
    server_type = "cx33",
    location    = "nbg1",
    labels      = ["node.kubernetes.io/server-usage=storage"],
    taints      = [],
    count       = 1
    os_snapshot_id = "348644983"  # Custom snapshot with LVM partitions
  },
]

Per-node override (in a nodes map):

nodes = {
  "0" : { os_snapshot_id = "348644983" },
  "1" : {},  # uses nodepool or global default
}

Caution: You are responsible for ensuring the snapshot ID matches the correct os type (leapmicro/microos) and node architecture (x86 for cx*/cpx* servers, ARM for cax* servers). A mismatched snapshot will cause provisioning failures.

When not set, the module automatically selects the most recent snapshot matching the node's os and architecture.

Set automatically_upgrade_os = false (attached volumes don't handle auto-reboots well).

Uses k3s service load balancer instead of external LB. Ports 80 & 443 open automatically.

1. Create a Leap Micro snapshot in your project first (or MicroOS if you explicitly use it)
2. Configure SSH keys as Terraform Cloud variables (mark private key as sensitive):

ssh_public_key  = var.ssh_public_key
ssh_private_key = var.ssh_private_key

Password-protected keys: Requires local execution mode with your own agent.

apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
  name: rancher
  namespace: kube-system
spec:
  valuesContent: |-
    # Your values.yaml customizations here

Works for all add-ons: Longhorn, Cert-manager, Traefik, etc.

Create secret:

apiVersion: v1
kind: Secret
metadata:
  name: encryption-secret
  namespace: kube-system
stringData:
  encryption-passphrase: foobar

Create storage class:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: hcloud-volumes-encrypted
provisioner: csi.hetzner.cloud
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
parameters:
  csi.storage.k8s.io/node-publish-secret-name: encryption-secret
  csi.storage.k8s.io/node-publish-secret-namespace: kube-system

Create secret:

apiVersion: v1
kind: Secret
metadata:
  name: longhorn-crypto
  namespace: longhorn-system
stringData:
  CRYPTO_KEY_VALUE: "your-encryption-key"
  CRYPTO_KEY_PROVIDER: "secret"
  CRYPTO_KEY_CIPHER: "aes-xts-plain64"
  CRYPTO_KEY_HASH: "sha256"
  CRYPTO_KEY_SIZE: "256"
  CRYPTO_PBKDF: "argon2i"

Create storage class:

kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: longhorn-crypto-global
provisioner: driver.longhorn.io
allowVolumeExpansion: true
parameters:
  nodeSelector: "node-storage"
  numberOfReplicas: "1"
  staleReplicaTimeout: "2880"
  fromBackup: ""
  fsType: ext4
  encrypted: "true"
  csi.storage.k8s.io/provisioner-secret-name: "longhorn-crypto"
  csi.storage.k8s.io/provisioner-secret-namespace: "longhorn-system"
  csi.storage.k8s.io/node-publish-secret-name: "longhorn-crypto"
  csi.storage.k8s.io/node-publish-secret-namespace: "longhorn-system"
  csi.storage.k8s.io/node-stage-secret-name: "longhorn-crypto"
  csi.storage.k8s.io/node-stage-secret-namespace: "longhorn-system"

Longhorn encryption docs

Enable admission controllers:

control_plane_exec_args = "--kube-apiserver-arg enable-admission-plugins=PodTolerationRestriction,PodNodeSelector"

Assign namespace to architecture:

apiVersion: v1
kind: Namespace
metadata:
  annotations:
    scheduler.alpha.kubernetes.io/node-selector: kubernetes.io/arch=amd64
  name: this-runs-on-amd64

With tolerations:

apiVersion: v1
kind: Namespace
metadata:
  annotations:
    scheduler.alpha.kubernetes.io/node-selector: kubernetes.io/arch=arm64
    scheduler.alpha.kubernetes.io/defaultTolerations: '[{ "operator" : "Equal", "effect" : "NoSchedule", "key" : "workload-type", "value" : "machine-learning" }]'
  name: this-runs-on-arm64

Setup backup:

1. Configure etcd_s3_backup in kube.tf
2. Add cluster_token output:

output "cluster_token" {
  value     = module.kube-hetzner.cluster_token
  sensitive = true
}

Restore:

1. Add restoration config to kube.tf:

locals {
  cluster_token = var.cluster_token
  etcd_version = "v3.5.9"
  etcd_snapshot_name = "name-of-the-snapshot"
  etcd_s3_endpoint = "your-s3-endpoint"
  etcd_s3_bucket = "your-s3-bucket"
  etcd_s3_access_key = "your-s3-access-key"
  etcd_s3_secret_key = var.etcd_s3_secret_key
}

variable "cluster_token" {
  sensitive = true
  type      = string
}

variable "etcd_s3_secret_key" {
  sensitive = true
  type      = string
}

module "kube-hetzner" {
  cluster_token = local.cluster_token

  postinstall_exec = compact([
    (
      local.etcd_snapshot_name == "" ? "" :
      <<-EOF
      export CLUSTERINIT=$(cat /etc/rancher/k3s/config.yaml | grep -i '"cluster-init": true')
      if [ -n "$CLUSTERINIT" ]; then
        k3s server \
          --cluster-reset \
          --etcd-s3 \
          --cluster-reset-restore-path=${local.etcd_snapshot_name} \
          --etcd-s3-endpoint=${local.etcd_s3_endpoint} \
          --etcd-s3-bucket=${local.etcd_s3_bucket} \
          --etcd-s3-access-key=${local.etcd_s3_access_key} \
          --etcd-s3-secret-key=${local.etcd_s3_secret_key}
        mv /etc/rancher/k3s/k3s.yaml /etc/rancher/k3s/k3s.backup.yaml

        ETCD_VER=${local.etcd_version}
        case "$(uname -m)" in
            aarch64) ETCD_ARCH="arm64" ;;
            x86_64) ETCD_ARCH="amd64" ;;
        esac;
        DOWNLOAD_URL=https://github.com/etcd-io/etcd/releases/download
        curl -L $DOWNLOAD_URL/$ETCD_VER/etcd-$ETCD_VER-linux-$ETCD_ARCH.tar.gz -o /tmp/etcd-$ETCD_VER-linux-$ETCD_ARCH.tar.gz
        tar xzvf /tmp/etcd-$ETCD_VER-linux-$ETCD_ARCH.tar.gz -C /usr/local/bin --strip-components=1

        nohup etcd --data-dir /var/lib/rancher/k3s/server/db/etcd &
        echo $! > save_pid.txt

        etcdctl del /registry/services/specs/traefik/traefik
        etcdctl del /registry/services/endpoints/traefik/traefik

        OLD_NODES=$(etcdctl get "" --prefix --keys-only | grep /registry/minions/ | cut -c 19-)
        for NODE in $OLD_NODES; do
          for KEY in $(etcdctl get "" --prefix --keys-only | grep $NODE); do
            etcdctl del $KEY
          done
        done

        kill -9 `cat save_pid.txt`
        rm save_pid.txt
      fi
      EOF
    )
  ])
}

1. Set environment variables:

export TF_VAR_cluster_token="..."
export TF_VAR_etcd_s3_secret_key="..."

1. Run terraform apply

resource "hcloud_network" "k3s_proxied" {
  name     = "k3s-proxied"
  ip_range = "10.0.0.0/8"
}

resource "hcloud_network_subnet" "k3s_proxy" {
  network_id   = hcloud_network.k3s_proxied.id
  type         = "cloud"
  network_zone = "eu-central"
  ip_range     = "10.128.0.0/9"
}

resource "hcloud_server" "your_proxy_server" { ... }

resource "hcloud_server_network" "your_proxy_server" {
  depends_on = [hcloud_server.your_proxy_server]
  server_id  = hcloud_server.your_proxy_server.id
  network_id = hcloud_network.k3s_proxied.id
  ip         = "10.128.0.1"
}

module "kube-hetzner" {
  existing_network = { id = hcloud_network.k3s_proxied.id }  # Note: object required!
  network_ipv4_cidr = "10.0.0.0/9"
  additional_kubernetes_install_environment = {
    "http_proxy" : "http://10.128.0.1:3128",
    "HTTP_PROXY" : "http://10.128.0.1:3128",
    "HTTPS_PROXY" : "http://10.128.0.1:3128",
    "CONTAINERD_HTTP_PROXY" : "http://10.128.0.1:3128",
    "CONTAINERD_HTTPS_PROXY" : "http://10.128.0.1:3128",
    "NO_PROXY" : "127.0.0.0/8,10.0.0.0/8,",
  }
}

Tailscale node transport is useful even before a cluster outgrows one Hetzner Network. In a normal single-network cluster it gives Terraform, kubeconfig, and operator SSH a private Tailnet path, so you can close public Kubernetes API and SSH firewall rules without introducing a separate bastion workflow. Kubernetes still keeps Hetzner private node IPs, so Hetzner CCM, CSI, and Load Balancers continue to see provider-owned addresses instead of Tailnet 100.64.0.0/10 addresses.

For clusters that need more than one Hetzner Cloud Network, the same transport becomes the production v3 scale-out path. Hetzner Networks still cap attached resources per Network and do not route separate Networks together. Tailscale fills that gap by advertising each node's own Hetzner private /32 route into the Tailnet and accepting those routes on every node.

Tailscale mode does not require exposing Kubernetes itself to the web. The recommended large-cluster shape keeps public Kubernetes API and SSH firewall rules closed, disables managed public ingress unless you explicitly need it, and uses the Tailnet for operator/API/node transport. Nodes may still have public IPv4/IPv6 enabled so they can bootstrap Tailscale and form direct WireGuard paths; the public firewall opens Tailscale UDP/41641, not Kubernetes API, SSH, or HTTP/S. A truly no-public-IP multinetwork topology needs private egress and externally managed Tailscale bootstrap for every external Network; the module NAT router covers only the primary kube-hetzner Network.

Minimal secure single-network shape:

node_transport_mode = "tailscale"

tailscale_auth_key = var.tailscale_auth_key

tailscale_node_transport = {
  # cloud_init brings Tailscale up before Terraform starts using SSH.
  bootstrap_mode  = "cloud_init"
  magicdns_domain = "example-tailnet.ts.net"
  auth = {
    mode = "auth_key"
  }
  routing = {
    # Single-network clusters already have Hetzner private reachability between
    # nodes, so route approval is optional. Leave this true for multinetwork.
    advertise_node_private_routes = false
  }
}

# Tailscale mode deliberately rejects public world-open API/SSH defaults.
firewall_kube_api_source = null
firewall_ssh_source      = null

# Every active Tailscale agent/autoscaler nodepool sets network_scope explicitly.
# Use "primary" when network_id is omitted/null.
# agent_nodepools = [{
#   name = "agent", server_type = "cx23", location = "nbg1",
#   labels = [], taints = [], count = 2, network_scope = "primary"
# }]

Multinetwork scale-out adds network_scope = "external" nodepools with external network_id values and requires approved node-private routes. Set network_scope explicitly in Tailscale mode so Terraform can validate primary-vs-external Network intent during plan, even when a network_id comes from an hcloud_network resource created in the same root.

node_transport_mode = "tailscale"

# Use a reusable shared key, or role-specific keys when autoscaler nodes should
# use a reusable ephemeral key while static nodes use durable tagged keys.
tailscale_auth_key = var.tailscale_auth_key
# tailscale_control_plane_auth_key = var.tailscale_control_plane_auth_key
# tailscale_agent_auth_key         = var.tailscale_agent_auth_key
# tailscale_autoscaler_auth_key    = var.tailscale_autoscaler_auth_key

tailscale_node_transport = {
  bootstrap_mode  = "cloud_init" # required when autoscaler_nodepools are used
  magicdns_domain = "example-tailnet.ts.net"
  auth = {
    mode = "auth_key"
    # Tagged nodes are recommended for production ACLs and route auto-approval,
    # but tags must be owned/permitted in your Tailnet policy before use.
    # advertise_tags_control_plane = ["tag:kube-hetzner-control-plane"]
    # advertise_tags_agent         = ["tag:kube-hetzner-agent"]
    # advertise_tags_autoscaler    = ["tag:kube-hetzner-autoscaler"]
  }
  routing = {
    advertise_node_private_routes = true
  }
}

agent_nodepools = [
  {
    name        = "agent-small-a"
    server_type = "cx23"
    location    = "nbg1"
    labels      = []
    taints      = []
    count       = 50
    # network_id omitted/null means the primary kube-hetzner network.
    network_scope = "primary"
  },
  {
    name        = "agent-small-b"
    server_type = "cx23"
    location    = "nbg1"
    labels      = []
    taints      = []
    count       = 50
    network_id    = 11959154 # existing external private network id
    network_scope = "external"
  },
]

autoscaler_nodepools = [
  {
    name        = "autoscaled-a"
    server_type = "cx23"
    location    = "nbg1"
    min_nodes   = 0
    max_nodes   = 50
    network_scope = "primary"
  },
  {
    name        = "autoscaled-b"
    server_type = "cx23"
    location    = "nbg1"
    min_nodes   = 0
    max_nodes   = 50
    network_id    = 11959154
    network_scope = "external"
  },
]

Large-scale reference layouts live in examples/tailscale-node-transport:

• large-scale-200.tf.example shows 200 total nodes across two Hetzner Networks while keeping each Network at exactly 100 attachments.
• massive-10000-nodes.tf.example shows the reference topology for 10,000 total nodes: 3 control planes, 7 static system agents, 90 autoscaled primary workers, and 99 external 100-node autoscaler shards. This is a quota/design reference, not a casual default; it requires Hetzner capacity approvals, Tailnet policy/device capacity, and production Kubernetes scale planning.

The important constraints are enforced during terraform plan:

• node_transport_mode = "tailscale" is mutually exclusive with multinetwork_mode = "cilium_public_overlay".
• Control planes always stay on the primary kube-hetzner network and no longer accept network_id.
• Static agents and autoscaler nodepools may use network_id to spread across existing Hetzner private Networks. In Tailscale mode, every active static agent node, agent nodepool, and autoscaler nodepool must set network_scope = "primary" or network_scope = "external".
• Control planes are not auto-attached to every external agent Network, avoiding Hetzner's 3-Networks-per-server limit.
• The module can advertise each node's Hetzner private /32 route through Tailscale, accepts Tailnet routes on nodes, and disables Tailscale subnet-route SNAT so Kubernetes/CNI traffic keeps the real Hetzner node source IP.
• Single-network clusters may set tailscale_node_transport.routing.advertise_node_private_routes = false to avoid Tailnet route approvals. Any nodepool with network_scope = "external" requires the default true.
• For multinetwork clusters, Tailnet ACLs must auto-approve node-private routes for the users, groups, or node tags you use, or the cluster will wait for manual route approval. Tags are optional in auth_key mode, but they are the cleanest production ACL boundary once tagOwners and autoApprovers are configured.
• With auth.mode = "auth_key", use a reusable tailscale_auth_key for one shared key, or role-specific keys (tailscale_control_plane_auth_key, tailscale_agent_auth_key, tailscale_autoscaler_auth_key). A single-use key only registers the first node. Prefer a reusable, pre-approved, tagged, ephemeral key for autoscaler nodes.
• With auth.mode = "oauth_client_secret", the module passes role-specific OAuth auth-key parameters: static nodes default to durable devices and autoscaler-created nodes default to ephemeral devices.
• Tailscale mode rejects world-open firewall_kube_api_source and firewall_ssh_source; use null for no public API/SSH rule or restrict to explicit CIDRs.
• Public module-managed control-plane Load Balancers are rejected in Tailscale mode. Private control-plane Load Balancers remain available for single-network HA/API patterns; kubeconfig still defaults to the first control plane's Tailnet MagicDNS endpoint unless you set an explicit endpoint.
• autoscaler_nodepools require tailscale_node_transport.bootstrap_mode = "cloud_init" because autoscaler-created nodes cannot be configured by Terraform remote-exec before joining.
• The module NAT router can be combined with Tailscale only for single-primary-network private egress. It does not provide egress for external Hetzner Networks, so multinetwork Tailscale nodepools need their own public IPv4/IPv6 egress. Do not set nat_router for external-network Tailscale topologies in this release.
• Managed Hetzner private Load Balancers work for single-primary-network Tailscale clusters. They still cannot span external nodepool Networks; when using network_id scale-out, use public LB targets, Klipper, no/custom ingress, or an external load balancer.

The older multinetwork_mode = "cilium_public_overlay" path remains as a gated lab preview for Cilium-only public transport experiments. Prefer Tailscale node transport for real private multinetwork clusters.

Assign nodepools to placement groups:

agent_nodepools = [
  {
    ...
    placement_group = "special"
  },
]

Legacy compatibility:

placement_group_index = 1

Count-based nodepools without an explicit placement_group are automatically sharded into spread groups of 10 servers. Hetzner projects also cap placement groups at 50 total, so very large static clusters must either disable placement groups, split across projects/clusters, or use autoscaler nodepools for burst capacity. kube-hetzner does not currently assign Hetzner Placement Groups to autoscaler-created nodes. If you set an explicit placement_group, split groups manually:

agent_nodepools = [
  {
    nodes = {
      "0"  : { placement_group = "pg-1" },
      "30" : { placement_group = "pg-2" },
    }
  },
]

Disable globally: enable_placement_groups = false

Set append_index_to_node_name = false to avoid node replacement:

agent_nodepools = [
  {
    name        = "agent-large",
    server_type = "cx33",
    location    = "nbg1",
    labels      = [],
    taints      = [],
    nodes = {
      "0" : {
        append_index_to_node_name = false,
        labels = ["my.extra.label=special"],
        placement_group = "agent-large-pg-1",
      },
      "1" : {
        append_index_to_node_name = false,
        server_type = "cx43",
        labels = ["my.extra.label=slightlybiggernode"],
        placement_group = "agent-large-pg-2",
      },
    }
  },
]

Protect resources from accidental deletion via Hetzner Console/API:

enable_delete_protection = {
  floating_ip   = true
  load_balancer = true
  volume        = true
}

Note: Terraform can still delete resources (provider lifts the lock).

Requirements:

1. Pre-configured network
2. NAT gateway with public IP (Hetzner guide)
3. WireGuard VPN access (Hetzner guide)
4. Route 0.0.0.0/0 through NAT gateway

Configuration:

existing_network = { id = 1234567 }
network_ipv4_cidr = "10.0.0.0/9"

# In all nodepools:
enable_public_ipv4 = false
enable_public_ipv6 = false

# For autoscaler:
autoscaler_enable_public_ipv4 = false
autoscaler_enable_public_ipv6 = false

# Optional private LB:
control_plane_load_balancer_enable_public_network = false

Fully private setup with:

• Egress: Single NAT router IP
• SSH: Through bastion (NAT router)
• Control plane: Through LB or NAT router port forwarding
• Ingress: Through agents LB only

enable_control_plane_load_balancer = true

nat_router = {
  server_type = "cax21"
  location    = "nbg1"
}

# Optional: use the router's private IP for SSH bastion traffic when the
# operator already reaches the private network through Tailscale/WireGuard/etc.
# use_private_nat_router_bastion = true

August 11, 2025: Hetzner removed legacy Router DHCP option. This module now automatically persists routes via the virtual gateway.

Use node_transport_mode = "tailscale" when Tailscale should be the official Kubernetes node transport for a single-network or multinetwork cluster. This external-overlay pattern is different: it is for operator access, custom control-plane endpoints, or post-bootstrap Tailscale Kubernetes Operator features that you manage outside kube-hetzner.

There is still no broad enable_tailscale switch. kube-hetzner manages only the narrow node-transport contract above. It does not manage tailnet ACLs, route approvals, Tailscale Services, workload ingress/egress policy, or the Tailscale Kubernetes Operator lifecycle. Use your overlay setup in an outer module or out-of-band bootstrap, then pass resulting endpoints back into kube-hetzner.

Cloudflare Zero Trust is documented separately because it is usually an Access/Tunnel edge rather than a node-to-node transport. Do not use Cloudflare Mesh/WARP as an officially supported kube-hetzner node transport in v3; use Tailscale for that contract.

The supported kube-hetzner primitives are:

• preinstall_exec / postinstall_exec for user-owned bootstrap hooks.
• node_connection_overrides for Terraform SSH/provisioners over Tailnet IPs.
• control_plane_endpoint for a stable external kube API endpoint.
• use_private_nat_router_bastion when a Tailscale/WireGuard/WARP path already reaches the private network.
• firewall_ssh_source / firewall_kube_api_source tightening after overlay access is proven.

# Bootstrap overlay client on each node (example commands only).
# Avoid long-lived auth keys here; command strings and cloud-init user-data can
# be visible in Terraform state/provider state or instance logs. Prefer an
# external bootstrap or short-lived, one-use preauth keys that are immediately
# rotated/revoked.
preinstall_exec = [
  "curl -fsSL https://tailscale.com/install.sh | sh",
  # "tailscale up --auth-key=${var.tailscale_auth_key} --ssh --hostname=$(hostname)",
]

# After overlay IPs are known, route Terraform SSH through them
# Keys must match final node names (with cluster prefix if enabled)
node_connection_overrides = {
  "k3s-control-plane" = "100.64.0.10"
  "k3s-agent-0"       = "100.64.0.11"
}

# Optional: use an external control-plane endpoint exposed through overlay
control_plane_endpoint = "https://cp.tailnet.example:6443"

Typical workflow:

1. Apply once to bootstrap nodes and install/join overlay agents.
2. Resolve overlay addresses and set node_connection_overrides.
3. Apply again and optionally tighten firewall_ssh_source / firewall_kube_api_source.
4. After Kubernetes is healthy, deploy the Tailscale Kubernetes Operator with Helm, ArgoCD, or user_kustomizations if you want Tailscale Services, workload ingress/egress, subnet routers, or kube API proxying.

For cluster node transport, prefer examples/tailscale-node-transport/README.md. For user-owned Tailscale operator access, see examples/external-overlay-tailscale/README.md. For Cloudflare Access/Tunnel operator and app access, see examples/external-overlay-cloudflare-access/README.md.

Cloudflare Zero Trust is useful in v3 as an operator and application access layer. Keep the cluster transport underneath simple:

• Use node_transport_mode = "tailscale" for supported secure node transport, especially single-network hardening and multinetwork scale-out.
• Use Cloudflare Access/Tunnel for the Kubernetes API, SSH, Rancher, Grafana, or ingress hostnames that you choose to publish through Cloudflare.
• Manage Cloudflare accounts, policies, tunnels, DNS records, WARP enrollment, and service tokens outside kube-hetzner.

This module deliberately does not add a Cloudflare provider, Cloudflare token variables, Cloudflare Mesh bootstrap, or node_transport_mode = "cloudflare". Cloudflare Mesh is still beta in Cloudflare's own docs, and using it as Kubernetes node transport would create a large support surface that v3 does not need.

For kubeconfig access through Cloudflare Access, prefer a local helper path such as cloudflared access tcp or a WARP/private-route design owned outside this module. Do not point control_plane_endpoint at an Access-protected hostname unless every joining control-plane and agent node can reach and authenticate to that endpoint; control_plane_endpoint is also used for node joins.

For SSH, use Cloudflare's own Access SSH patterns, or expose reachable overlay addresses through node_connection_overrides only after you have proven that Terraform can connect through them.

Full example: examples/external-overlay-cloudflare-access/README.md.

Create targeted SELinux profiles instead of weakening cluster-wide security:

Policy posture and rule provenance are documented in docs/selinux.md.

Troubleshooting note: When using large attached volumes (for example large Longhorn disks), first boot can hit cloud-init/systemd timeouts while SELinux relabeling completes. If you hit this repeatedly, a practical workaround is to disable SELinux only on the affected nodepool(s) instead of disabling it cluster-wide.

# Find container
crictl ps

# Generate inspection
crictl inspect <container-id> > container.json

# Create profile
udica -j container.json myapp --full-network-access

# Install module
semodule -i myapp.cil /usr/share/udica/templates/{base_container.cil,net_container.cil}

Apply to deployment:

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: my-container
          securityContext:
            seLinuxOptions:
              type: myapp.process

Thanks @carolosf