Skip to content
SHC Docs

Joining nodes

A node joins with a token minted on a member. The token is single-use and expires; --ttl sets how long it lives. Each join needs a fresh one, so each runs on the joining node and asks home01 for its token over ssh: shc node token --fields token -o text prints the token alone, and shc node join - reads it from standard input, so it is never copied or typed.

--control-plane puts the joiner in the control plane, the set of nodes that may vote. home02 and home03 are in home, the location of the first node, which is where the control plane starts; saying it makes it explicit. --nic and --runtime are what init took on home01, typed with the values the node would detect.

home02
$ ssh home01 shc node token --ttl 30m --fields token -o text | shc node join - --name home02 --cloud learn --location home --control-plane --nic eth0 --runtime docker
✔ joined cluster as node "home02" at 192.168.232.12
home03
$ ssh home01 shc node token --ttl 30m --fields token -o text | shc node join - --name home03 --cloud learn --location home --control-plane
✔ joined cluster as node "home03" at 192.168.232.13

far01 is a worker in the other location. It joins with an operator label of its own, tier=edge, which the placement page uses, and --public-address, the address internet traffic reaches the node at, recorded on the node row for managed DNS to read. far01’s is its hostname.

far01
$ ssh home01 shc node token --ttl 30m --fields token -o text | shc node join - --name far01 --cloud learn --location far --label tier=edge --public-address far01
✔ joined cluster as node "far01" at 192.168.232.14

A machine that also runs work outside SHC joins with --reserve, the room it keeps for that work, as on shc init.

explained, not walked: these machines run nothing beside SHC, so they keep no room back
$ ssh home01 shc node token --ttl 30m --fields token -o text | shc node join - --name far01 --cloud learn --location far --label tier=edge --public-address far01 --reserve cpu=1,memory=4Gi,disk=50Gi

A node that is a virtual machine joins with --hypervisor, the connection its host is read through, as <connection>/<instance>. SHC reads the host’s capacity and the other instances on it, never writes through it, and takes off the node’s room what the host cannot give it. shc node update sets it on a node that has joined, and an empty value clears it.

explained, not walked: these machines are cloud servers, with no connection to the host they run on
$ ssh home01 shc node token --ttl 30m --fields token -o text | shc node join - --name far01 --cloud learn --location far --label tier=edge --public-address far01 --hypervisor pve/far01
$ shc node update far01 --hypervisor pve/far01

A join typed without the page’s flags lands under a random name, worker- and eight letters, in the cloud and location the machine reports, and the cluster keeps fewer voters than this page shows. Take that node out from its own shell and click its join again. --force because traefik already runs on every node, and a plain leave refuses a node that hosts a deployment; the leader drops the node as it leaves.

explained, not walked: only a join that went wrong needs it
$ shc node leave --force --yes
$ ssh home01 shc node token --ttl 30m --fields token -o text | shc node join - --name home03 --cloud learn --location home --control-plane

Run shc node ls again until every node reads healthy and ready.

home01
$ shc node ls
NAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD STORE LEADER VOTER
far01 healthy ready active learn learn/far ok 0.1.47 replica no no
home01 healthy ready active learn learn/home ok 0.1.47 voter yes yes
home02 healthy ready active learn learn/home ok 0.1.47 voter no yes
home03 healthy ready active learn learn/home ok 0.1.47 voter no yes
$ shc cluster status
cluster name: shc-cluster
leader: home01
nodes: 4 healthy of 4
voters: 3
quorum: healthy, 2 voters required
leader-only work, recorded by home01 41s ago:
...

shc node update --reserve sets that room on a node already in the cluster, or changes it; a resource set to 0 clears it. Keep 1 GiB of far01’s disk back, then give it back:

home01
$ shc node update far01 --reserve disk=1Gi
...
$ shc node update far01 --reserve disk=0
...

Every node reaches every other over the mesh. Ping them all, then one.

home01
$ shc cluster ping
NODE STATUS RTT
far01 ok 34.74ms
home01 ok 0.12ms
home02 ok 1.22ms
home03 ok 0.46ms
$ shc cluster ping far01 -c 1 -T 2
NODE STATUS RTT
far01 ok 34.85ms

The licence meters the joins: four nodes of the ten it allows.

home01
$ shc license status
state: keyed
tier: pro
holder: Learn walk
source: file
features: audit, branding, clustering, console, container_runtime, environments, fleet, marketplace, mcp, multi_provider, quota, rbac, sso, support_bundle, tenancy
capacity:
licensed: max_nodes=10
now: max_nodes=4 max_cores=8 max_seats=1 max_tenants=0
term peak: max_nodes=4 max_cores=8 max_seats=1 max_tenants=0
term began: 2026-11-06T17:07:03Z
auto-check: on
last check: 2026-11-06T17:09:59Z, the broker did not answer, 1 failed attempt X502962LICRFR

A new cluster holds one tenant, master, and the platform’s own apps live there. Add prod, the tenant this ladder’s deployments go in, and select it with shc ctx -t, as the app ladder does. Every later command on home01 then reads prod without naming it. --no-admin leaves the tenant’s Keycloak realm without users, since no page here signs anyone in.

home01
$ shc tenant add prod --no-admin
✔ created tenant "prod"
warning: keycloak realm provisioning still in progress
$ shc ctx -t prod
...

The selection is home01’s own: a command typed on another node names its tenant with -t. -t master lists the platform’s apps, and its traefik now runs on every node. Leave prod selected throughout.

home01
$ shc tenant ls
ACTIVE NAME DEPLOYMENTS
master 3
* prod 0
$ shc ls -t master
STACK TENANT ENV APP STATUS NODES
keycloak master default keycloak running home01
postgres master default postgres running home01
traefik master default traefik running far01, home01, home02, home03

Next: The control plane and its voters.