Skip to content
SHC Docs

The cluster

The front door forms the cluster when it has a bootstrap block and manage_platform is on. The block names the shc version, the vault password and the licence. The vault password comes from a random_password resource, so it is minted into state like the SSH key. The licence token comes from the file you put on work; multi-node clustering needs it before the first join.

Replace main.tf with this one. The manage_platform line is gone and two blocks are new.

~/learn/cluster/main.tf
provider "hcloud" {}
resource "random_password" "vault" {
length = 24
special = false
}
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}"
on_destroy = var.on_destroy
bootstrap = {
package = {
version = var.shc_version
}
vault_password = random_password.vault.result
license = {
token = file(pathexpand("~/shc-license.token"))
}
}
}

You will log in to the nodes from work. ssh.tf writes the minted private key to a file and an SSH configuration with one Host per node, so home01 on the command line means the machine Hetzner calls home01.learn. The nodes’ host keys go in ssh/known_hosts beside it, not in your own, so page 07 can drop them with the machines.

~/learn/cluster/ssh.tf
resource "local_sensitive_file" "ssh_key" {
filename = pathexpand("~/learn/cluster/ssh/key")
content = module.shc.ssh_private_key
file_permission = "0600"
}
resource "local_file" "ssh_config" {
filename = pathexpand("~/learn/cluster/ssh/config")
content = join("", [
for n in module.shc.nodes :
"Host ${split(".", n.name)[0]}\n HostName ${n.management.ipv4}\n User admin\n IdentityFile ${local_sensitive_file.ssh_key.filename}\n UserKnownHostsFile ${pathexpand("~/learn/cluster/ssh/known_hosts")}\n StrictHostKeyChecking accept-new\n\n"
])
}

The plan adds nothing on Hetzner. It adds the cluster record, one shc_node per machine, the licence between the first node and the joins, the password and the two local files.

work
$ tofu -chdir=learn/cluster fmt
$ tofu -chdir=learn/cluster plan
...
# module.shc.module.core[0].shc_cluster.main[0] will be created
...
# module.shc.module.core[0].shc_license.estate[0] will be created
...
# module.shc.module.core[0].shc_node.bootstrap[0] will be created
...
# module.shc.module.core[0].shc_node.workers["far01.learn"] will be created
...
# module.shc.module.core[0].shc_node.workers["home02.learn"] will be created
...
# module.shc.module.core[0].shc_node.workers["home03.learn"] will be created
...
Plan: 9 to add, 0 to change, 0 to destroy.
...

Apply. The provider adds the Based apt repository on home01 over SSH, installs shc at shc_version and holds it there, and runs shc init. It installs the licence, then installs the same version on the other three and joins each one. This takes several minutes.

work
$ tofu -chdir=learn/cluster apply -auto-approve
...
Apply complete! Resources: 9 added, 0 changed, 0 destroyed.
...
$ tofu -chdir=learn/cluster output bootstrap_node
"home01.learn"

Log in to home01 as admin and read the cluster. SHC commands on a node run as root, so each one is behind sudo. Run the first command again if a node is still joining.

work
$ ssh -F learn/cluster/ssh/config home01 sudo shc node ls
NAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD LEADER VOTER
far01.learn healthy ready active hetzner hetzner/hel1 ok 0.1.2 no no
home01.learn healthy ready active hetzner hetzner/nbg1 ok 0.1.2 yes yes
home02.learn healthy ready active hetzner hetzner/nbg1 ok 0.1.2 no yes
home03.learn healthy ready active hetzner hetzner/nbg1 ok 0.1.2 no yes
work
$ ssh -F learn/cluster/ssh/config home01 sudo shc cluster status
cluster name: shc-cluster
leader: home01.learn
nodes: 4 healthy of 4
voters: 3
quorum: healthy, 2 voters required
leader-only work, recorded by home01.learn 58s ago:
...
$ ssh -F learn/cluster/ssh/config home01 sudo shc license status
state: keyed
tier: pro
...
$ ssh -F learn/cluster/ssh/config far01 sudo shc node status
...

Four nodes in two Hetzner locations, three of them voters, and the node facts came from the cloud: hetzner is the cloud and hetzner/nbg1 and hetzner/hel1 are the locations each node detected. Nothing was typed on a node to get here.

Next: Grow by a count.