Skip to content
SHC Docs

Example: hetzner-shc

terraform/examples/hetzner-shc is the root the ladder’s own was cut from. It builds five nodes in two groups and wires DNS, Let’s Encrypt and a load balancer through the module’s topology block instead of root-level resources. Read it after page 07; the pages from here on show what each example does differently, not the whole file.

  • Two groups of different sizes and server types, and the second group opens the node port range on a firewall of its own. The global firewall applies to every group; a group’s firewall adds to it for that group only.
  • The control group sets control_plane = true: its three nodes join the control plane and are its three voters. The two workers join outside it.
  • A key you bring: ssh_public_key and ssh = { private_key_path } in place of create_ssh_key. The module reads the private key file itself.
  • bootstrap.host names the cluster’s public host, and bootstrap.acme seeds a Let’s Encrypt provider at init, so public routes get real certificates.
  • topology.kind = "lb" with a Hetzner DNS connection: the module creates the connection, sets dns.provider, and attaches ports 80 and 443 of the system traefik deployment to a Hetzner load balancer. The same token the hcloud provider reads feeds the connection, passed as TF_VAR_hcloud_token.
  • license_token_path names a licence file of yours, as the ladder’s root passed one. More than one node needs a licence that includes clustering before the first join, and the trial does not include it. With no path the root gives the trial consent instead, which starts the 30-day clock and forms no cluster: the worker joins are refused X403029LICENT.
  • on_destroy is passed through, unset. Page 07 applied "force" before its destroy, and this root’s destroy needs the same.
node_groups = {
control = { count = 3, server_type = "cx33", runtime = "docker", control_plane = true }
workers = {
count = 2, server_type = "cx43", runtime = "docker", region = var.workers_region
firewall = {
public_ports = [
{ port = "30000-32767", protocol = "tcp" },
{ port = "30000-32767", protocol = "udp" },
]
}
}
}
on_destroy = var.on_destroy
bootstrap = {
accept_ee_trial = var.license_token_path == ""
license = var.license_token_path == "" ? null : { token = file(pathexpand(var.license_token_path)) }
package = { version = var.shc_version }
vault_password = var.vault_pw
host = var.shc_host
acme = {
providers = { prod = { email = var.acme_email } }
default = "prod"
}
}
topology = {
kind = "lb"
dns = {
name = "hetzner"
type = "hetzner"
zones = [var.dns_zone]
credentials = { token = var.hcloud_token }
}
}

Seven more inputs of modules/shc/hetzner kept their defaults on every page. Each is for a standing estate, not a lab.

shown, not applied: each of these changes a standing estate; the ladder's cluster is built and destroyed in one sitting
module "shc" {
source = "../shc/terraform/modules/shc/hetzner"
# Extra operator keys on the admin user, baked into cloud-init at create
# time; changing the list later replaces every server.
extra_authorized_keys = [file(pathexpand("~/.ssh/operator.pub"))]
# A blue/green generation of the same cluster_name: "g2" is a second set
# of machines, disks and firewalls beside the first, handed over by DNS.
generation = "g2"
generation_in_names = true
# The address plane the SSH control channel rides: "public" (default) or
# "private", when work sits on the cluster's private network.
ssh_address = "private"
# The LAN prefix the node routes hang off, only when the network attached
# differs from the one networking declares.
routes_lan = "10.10.0.0/16"
# No spread placement group for the nodes.
placement_group = false
# Delete protection on every machine and volume; a destroy fails until
# it is applied false again.
protected = true
}

It needs a DNS zone hosted at Hetzner, a contact email for Let’s Encrypt, a key pair of yours and a licence that includes clustering. HCLOUD_TOKEN, TF_VAR_hcloud_token, TF_VAR_vault_pw and TF_VAR_ssh_public_key come from the environment; the rest goes in terraform.tfvars, copied from terraform.tfvars.example. The licence file is named on the command line, and so is on_destroy, applied before the destroy.

Terminal window
cp learn/shc/terraform/examples/hetzner-shc/terraform.tfvars.example learn/shc/terraform/examples/hetzner-shc/terraform.tfvars
tofu -chdir=learn/shc/terraform/examples/hetzner-shc init
tofu -chdir=learn/shc/terraform/examples/hetzner-shc plan -var license_token_path=~/shc-license.token
tofu -chdir=learn/shc/terraform/examples/hetzner-shc apply -var license_token_path=~/shc-license.token
tofu -chdir=learn/shc/terraform/examples/hetzner-shc apply -var license_token_path=~/shc-license.token -var on_destroy=force
tofu -chdir=learn/shc/terraform/examples/hetzner-shc destroy -var license_token_path=~/shc-license.token -var on_destroy=force

This page was not walked: the lb topology needs a DNS zone at Hetzner, and the learning project has none.

Next: Example: hetzner-lan.