Choosing the Master

Exactly one node in any cluster of two or more is the master. This page describes how to set, change, and verify which node holds that role.

The default master

If you have not explicitly chosen a master, the cluster falls back to the first node that joined it. This is fine for single-host setups but rarely what you want for production, see Master & Thin Clients for why the master must be a node that can reach your origin web server.

Setting the master from the control panel

1. Open your cluster's details page.
2. Find the table of member nodes. The current master shows a gold ★; the rest show an outline ☆.
3. Click the outline ☆ next to the node you want to promote.
4. Confirm in the modal. The icon updates immediately.

The control panel updates the cluster record and the next subscribe call on each node will pick up the new master designation.

Applying the change to the cluster

On every node in the cluster:

sudo qscs subscribe domain <cluster-tag>
sudo systemctl restart qscs

The order matters: re-subscribe the new master first, then restart it; then re-subscribe and restart each thin client. After the dust settles you should see, on the new master:

DomainRegistry: N peers, role=Master

And on each thin client:

DomainRegistry: N peers, role=Node
[QSCS] Implicit upstream resolved to <new-master>:8080

What happens to the old master?

Once it re-subscribes, it becomes a thin client. Its [Origins] entries are rewritten to point at the new master's QSCS port. The real backend address on the old master is no longer in use by the cluster; you can leave it running as before.

Cannot reach the new master

If any thin client cannot reach the new master on its inter-node port (default 4443), it will be unable to refresh its cache. Make sure the new master's firewall rules allow inbound TCP from every other cluster member.