The root module
A root module is a directory of .tf files. Yours is ~/learn/cluster. It
declares the providers it needs, the variables it takes, one call of the
Hetzner front door, and the outputs you want to read back. Write the five files
below on work.
versions.tf names the providers. hcloud creates the machines, shc forms
the cluster, and random and local serve the next page. shc is pinned to
0.1.3, the release of the modules page 00 unpacked: a module speaks the
provider it was released with, and an unpinned tofu init takes the newest.
terraform { required_version = ">= 1.6.0"
required_providers { hcloud = { source = "hetznercloud/hcloud" version = "~> 1.45" } shc = { source = "selfhosted-cloud/shc" version = "0.1.3" } random = { source = "hashicorp/random" } local = { source = "hashicorp/local" } }}variables.tf declares what the root module takes. shc_version has no
default: the release every machine installs is a choice you write down.
variable "cluster_name" { description = "Names every machine, the network, the firewalls and the placement group." type = string default = "learn"}
variable "home_region" { description = "The Hetzner location of the home group." type = string default = "nbg1"}
variable "far_region" { description = "The Hetzner location of the far group." type = string default = "hel1"}
variable "home_count" { description = "How many machines the home group has." type = number default = 3}
variable "server_type" { description = "The Hetzner server type of every machine." type = string default = "cx23"}
variable "image" { description = "The operating system image of every machine." type = string default = "debian-13"}
variable "shc_version" { description = "The shc release every machine installs by apt from the Based repository. A new value on a live cluster is the upgrade, one node at a time." type = string}
variable "on_destroy" { description = "Set to force before a destroy that takes the deployments with it." type = string default = null}
variable "labels" { description = "Extra labels on every Hetzner resource." type = map(string) default = {}}main.tf calls the front door. Two node groups share one private network:
home with three machines in home_region and far with one machine in
far_region. Hetzner names the machines home01.learn, home02.learn,
home03.learn and far01.learn, and those are the SHC node names too.
create_ssh_key makes the module mint the SSH key the cluster uses, so no key
file of yours is involved. bootstrap_node_name pins which node runs
shc init; without it the first node of the alphabetically first group would,
and that is far01. manage_platform = false stops after the machines, so
you can look at them before SHC goes on.
provider "hcloud" {}
module "shc" { source = "../shc/terraform/modules/shc/hetzner"
cluster_name = var.cluster_name region = var.home_region image = var.image create_ssh_key = true labels = var.labels
node_groups = { home = { count = var.home_count server_type = var.server_type runtime = "docker" } far = { count = 1 server_type = var.server_type runtime = "docker" region = var.far_region } }
networking = { private = true ip_range = "10.10.0.0/16" subnet = "10.10.1.0/24" }
firewall = { public_ports = [] }
bootstrap_node_name = "home01.${var.cluster_name}" manage_platform = false}outputs.tf reads facts back out of the module. nodes is the whole node
list, one entry per machine, bootstrap first.
output "node_names" { value = [for n in module.shc.nodes : n.name]}
output "node_addresses" { value = [for n in module.shc.nodes : n.management.ipv4]}
output "bootstrap_node" { value = module.shc.bootstrap_node.name}
output "cluster_endpoint" { value = module.shc.cluster_endpoint}
output "ssh_private_key" { value = module.shc.ssh_private_key sensitive = true}terraform.tfvars gives values to variables. It holds no secret: the token
is in your environment and the module mints the SSH key and, on the next
page, the vault password. shc_version is 0.1.2, the release before the
modules’, so the upgrade page has a newer one to roll the cluster to.
home_region = "nbg1"far_region = "hel1"home_count = 3server_type = "cx23"shc_version = "0.1.2"init installs six providers, two of them the module’s own, and reads the module. fmt lines the files
up and validate checks them without touching Hetzner.
$ tofu -chdir=learn/cluster init...OpenTofu has been successfully initialized!...$ tofu -chdir=learn/cluster fmt$ tofu -chdir=learn/cluster validateSuccess! The configuration is valid.plan shows what apply would create: the key, the network and its subnet,
one firewall per group, the placement group, and the four machines.
$ tofu -chdir=learn/cluster plan... # module.shc.hcloud_server.node["far01.learn"] will be created... # module.shc.hcloud_server.node["home01.learn"] will be created... # module.shc.hcloud_server.node["home02.learn"] will be created... # module.shc.hcloud_server.node["home03.learn"] will be created...Apply it. Hetzner boots four Debian 13 machines and cloud-init prepares each
one with Docker and an admin user that holds the cluster key.
$ tofu -chdir=learn/cluster apply -auto-approve...$ tofu -chdir=learn/cluster output node_names[ "far01.learn", "home01.learn", "home02.learn", "home03.learn",]$ tofu -chdir=learn/cluster output bootstrap_node"home01.learn"$ tofu -chdir=learn/cluster output...cluster_endpoint is not in that list. It is null, and it stays null on this
ladder: the module opens no port to the daemon’s API unless public_ports
names one, so there is no address off the cluster to give. OpenTofu keeps no
null output in the state, so asking for it by name answers not found. The
state file ~/learn/cluster/terraform.tfstate now records every
resource, including the private key. Treat it as a secret.
Next: The cluster.