Joining a Cluster

"Joining a cluster" means telling a freshly activated node which domain it belongs to. The control plane responds with the cluster's peer list and origin definitions, and QSCS rewrites /etc/qscs/qscs.conf accordingly.

Pre-flight checklist

• The node has been licensed: sudo qscs license <username>.
• You know the cluster's tag (visible in the control panel, for example europe-edge).
• If you are creating a brand-new cluster, you have created it in the control panel first.
• The cluster has at least one origin defined.

Subscribing

sudo qscs subscribe domain <cluster-tag>

Expected output (abridged):

[QSCS] Domain '<cluster-tag>' subscribed successfully!
[QSCS]   Node <uuid> attached to cluster
[Config] Updated /etc/qscs/qscs.conf — domain='<cluster-tag>', N peer(s)
[QSCS]   Peers:
[QSCS]     <peer-host>:4443 (<tag>) [Master]
[QSCS]     ...
[QSCS]   Origins: M written to config
[QSCS] Start the daemon: sudo systemctl restart qscs

Restart the daemon to pick up the new file:

sudo systemctl restart qscs

When to re-subscribe

Run qscs subscribe again whenever any of the following change in the control panel:

• A node is added or removed from the cluster.
• The master designation is moved to a different node.
• An origin is added, removed, or has its backend address changed.

The subscribe command is idempotent, running it when nothing has changed simply rewrites the same file.

Recommended order for cluster-wide changes

1. Make the change in the control panel.
2. Re-subscribe on the master first, then restart it.
3. Re-subscribe each thin client, then restart it.
4. Verify with journalctl -u qscs -n 50 --no-pager on each node.

Doing the master first means the thin clients always see a healthy upstream as they come back up.

Leaving a cluster

To detach a node, remove it from the cluster in the control panel; on every other member, re-subscribe and restart so they drop the departed node from their peer list. The leaving node may then be subscribed elsewhere, or simply shut down.