Skip to content
SHC Docs

A Hetzner node

A cloud node is a node some company runs. SHC records who runs it and where, and a connection to that company’s account gives the cluster what the account sells: on Hetzner Cloud, DNS, a load balancer and block volumes from one API token.

You need a Hetzner Cloud project and an API token with read and write permission. Put the token on home01 as ~/hetzner.token, one line, readable by you alone.

home01
$ chmod 600 ~/hetzner.token

In the Hetzner Cloud console create one server: Debian 13, type cx33, location hel1, your SSH key. Install SHC on it following Installation and allow the cluster ports between it and the learn nodes. Call the node hz01. Join it, saying who runs it and where, as Hetzner names the location.

The join asks home01 for its token over ssh, so give root on hz01 the learn nodes’ names and a key home01 accepts, as the learn nodes have.

hz01
$ ssh home01 shc node token --fields token -o text | shc node join - --name hz01 --cloud hetzner --location hel1
✔ joined cluster as node "hz01" at 46.62.245.105
home01
$ shc node ls
NAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD LEADER VOTER
home01 healthy ready active learn learn/home ok 0.1.0 yes yes
hz01 healthy ready active hetzner hetzner/hel1 ok 0.1.0 no no

hz01 reads cloud hetzner and location hetzner/hel1. For a few seconds after the join its condition reads unknown, then vault-locked until a peer hands it the vault key, within a minute, then ready. Run the read again until it does. Connect the account. The token is a secret, so it comes from the file and never from the command line. region is where the connection creates volumes.

home01
$ shc connection connect hetzner --cred region=hel1 --cred token=- --value-file ~/hetzner.token
...
$ shc connection ls
...
$ shc connection show hetzner
...

The connection lights three providers: hetzner for DNS, hcloud-lb for a load balancer and hcloud-volume for block volumes. A block volume reaches only the nodes in the connection’s region, so on this cluster that is hz01. Install notes from the app ladder onto hz01 and ask for block storage by the connection’s name: the first volume on an estate is a decision, so SHC creates none until an install names the provider.

explained, not walked: select the volume connection
$ shc config set storage.volumes.provider hetzner
$ shc config set storage.volumes.hcloud.filesystem ext4
$ shc config set storage.volumes.auto_failover true

storage.volumes.provider names the backend outright when more than one connection could serve volumes. Here hetzner is the connection’s name; its credentials supply the token and region. hcloud.filesystem selects the filesystem, and auto_failover lets a volume follow its deployment to another node without an operator’s word. The install waits for hz01 to read ready.

home01
$ shc install notes -s hzdb --where node=hz01 --storage hetzner
installing deployment "hzdb"
[hzdb] Healthy 1/1
✔ postgres healthy
✔ installed deployment "hzdb"
$ shc volume ls
...
$ shc ls
...

pgdata is a Hetzner volume now, attached to hz01. Read it from the server’s side, then from Postgres.

hz01
$ lsblk -o NAME,SIZE,MOUNTPOINT
...
home01
$ shc exec -s hzdb -S postgres -- psql -U postgres -tAc "insert into notes values ('on a volume')"
INSERT 0 1
home01
$ shc volume snapshot pgdata -s hzdb
shc: [X501331VOLSNU] volume provider hcloud cannot snapshot block volumes, the Hetzner Cloud volume API has no snapshot action, only attach, detach, resize and change_protection; a Hetzner snapshot is a server image and does not copy attached block volumes

Hetzner sells no volume snapshot, so shc volume snapshot refuses with X501331VOLSNU and says why: the Hetzner Cloud volume API has no snapshot action, only attach, detach, resize and change_protection, and a Hetzner snapshot is a server image that does not copy attached block volumes. A volume’s data can still be read on its node without the deployment: a mount is leased and the daemon releases it when the lease runs out.

hz01
$ shc volume mount pgdata -s hzdb --ttl 5m
...
$ shc volume mounts
...
explained, not walked: a mount handle, a volume outliving its deployment, a dead node and a stalled failover do not happen on this walk
$ shc volume umount <handle>
$ shc volume mount pgdata -s hzdb --ttl 5m --read-write
$ shc volume rm pgdata -s hzdb --yes
$ shc volume rm pgdata -s hzdb --force --yes
$ shc volume rebind pgdata -s hzdb hz01 <new-node> --yes
$ shc volume assert-lease-lost hz01 --reason "node lost" --yes

umount ends a lease early by the handle mount printed. --read-write mounts for writing, which only makes sense with the deployment stopped. rm deletes a volume the uninstall left behind, --force one still attached. rebind moves a volume from the node holding it to another when that node is gone for good, and assert-lease-lost names a node and tells a stalled failover it will never write again; both are a decision, not a step.

uninstall backs the deployment up first, and that backup is sealed into a repository. shc init sealed the repository’s key in the vault but set no repository, so set one on home01’s disk, as the app ladder’s A backup and an export does.

home01
$ shc config set backup.repo /var/backups/shc/repo
...
KEY VALUE SCOPE
backup.repo /var/backups/shc/repo global

Uninstall hzdb. Its safety backup archives the data first, so the uninstall deletes the Hetzner volume with the deployment.

home01
$ shc uninstall hzdb -y
uninstalling deployment "hzdb"
[hzdb] Complete 5/5
✔ remove from hz01
✔ take the safety backup
✔ leave every node's service VIP table
✔ tear down
✔ remove the copy on home01
✔ uninstalled deployment "hzdb"
$ shc volume ls
no block volumes in tenant "prod"

With --no-backup nothing archives the data, so the uninstall keeps the volume, detached from hz01, and names it with the shc volume rm that deletes it.

Take hz01 out of the cluster and remove the connection. The system ingress keeps a traefik replica on every node, so a node that still hosts one refuses to leave with X409025LVDEPS: drain it first, from any node, and the cluster moves what it hosts. Then the node leaves from itself; the cluster notices.

home01
$ shc node drain hz01 --yes
...
hz01
$ shc node leave
✔ node "hz01" left the cluster
✔ membership state moved to /var/lib/shc/left-cluster-20261011T105200Z-8e611813-627c-4667-be59-6474cf295a8d
✔ member subsystems and deployment containers stopped; images, deployment files and deployment volumes kept
home01
$ shc node ls
NAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD LEADER VOTER
home01 healthy ready active learn learn/home ok 0.1.0 yes yes
$ shc connection rm hetzner --yes
...

Delete the server in the Hetzner Cloud console. A server that left the cluster still costs money until it is deleted.

This page leaves the cluster as the runtimes ladder left it: the learn nodes, with no cloud node and no connection.

Next: An Alibaba Cloud node.