Skip to content
SHC Docs

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.

~/learn/cluster/versions.tf
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.

~/learn/cluster/variables.tf
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.

~/learn/cluster/main.tf
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.

~/learn/cluster/outputs.tf
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.

~/learn/cluster/terraform.tfvars
home_region = "nbg1"
far_region = "hel1"
home_count = 3
server_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.

work
$ tofu -chdir=learn/cluster init
...
OpenTofu has been successfully initialized!
...
$ tofu -chdir=learn/cluster fmt
$ tofu -chdir=learn/cluster validate
Success! 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.

work
$ 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.

work
$ 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.