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.
$ chmod 600 ~/hetzner.tokenIn 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.
$ 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$ shc node lsNAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD LEADER VOTERhome01 healthy ready active learn learn/home ok 0.1.0 yes yeshz01 healthy ready active hetzner hetzner/hel1 ok 0.1.0 no nohz01 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.
$ 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.
$ shc config set storage.volumes.provider hetzner$ shc config set storage.volumes.hcloud.filesystem ext4$ shc config set storage.volumes.auto_failover truestorage.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.
$ shc install notes -s hzdb --where node=hz01 --storage hetznerinstalling 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.
$ lsblk -o NAME,SIZE,MOUNTPOINT...$ shc exec -s hzdb -S postgres -- psql -U postgres -tAc "insert into notes values ('on a volume')"INSERT 0 1$ shc volume snapshot pgdata -s hzdbshc: [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 volumesHetzner 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.
$ shc volume mount pgdata -s hzdb --ttl 5m...$ shc volume mounts...$ 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" --yesumount 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.
$ shc config set backup.repo /var/backups/shc/repo...KEY VALUE SCOPEbackup.repo /var/backups/shc/repo globalUninstall hzdb. Its safety backup archives the data first, so the
uninstall deletes the Hetzner volume with the deployment.
$ shc uninstall hzdb -yuninstalling 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 lsno 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.
$ shc node drain hz01 --yes...$ 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$ shc node lsNAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD LEADER VOTERhome01 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.