Remove a node from the cluster

Removing a worker node makes the master forget it. The software on the machine keeps running and the sites it hosts keep serving, but the master no longer manages it. Use it when you retire a machine or want to enroll the same machine again from scratch.

Before you start

• Sign in as an Owner.
• Know how many sites the node carries. The row shows N sites.
• Move or copy the sites you want to keep to another node first. Open each site and use Move / copy. Removing a node does not move anything.
• If the machine is only misbehaving, drain it or update it instead.

Steps

Before you remove a node

The master deletes the node’s entry: its label, its enrollment and its recorded TLS pin and reply-signing key. Nothing is sent to the node, so its agent, nginx, PHP and the sites keep running there. If you force the removal while sites are still on it, those sites can no longer be managed from this panel.

Confirm that every site you want to keep is elsewhere. On the node’s row, N sites should read 0 sites, or open Hostings and check no site shows this node. Confirm a recent backup exists for any site you cannot move, on the site’s Backups tab.

To undo, create a new invite and enroll the machine again. It receives a new node ID, and sites left on the old ID are adopted with the steps in “Adopt orphaned sites” below.

1. Open Nodes in the sidebar and click the worker’s row.
2. At the bottom of the row, open Remove from the cluster….
3. Leave Force — orphan any sites still on this node unticked.
4. Click Remove node. The dialog asks you to type the node’s label. Type it and confirm Remove node.

The page shows “Node <node-id> removed from the cluster.” If sites still live on the node, nothing is removed, and the page shows “Refused — N hosting(s) still live on <node-id>. Move them to another node first (Move / copy on each hosting), OR re-submit with the Force option ticked to orphan them and delete the node anyway.”

Remove a node that still has sites

Tick Force — orphan any sites still on this node and click Remove node. The page shows how many sites were orphaned. They keep serving from the detached machine, and the master cannot manage them.

From a shell on the master, the same actions are:

sudo hctl node remove <node-id>
sudo hctl node remove <node-id> --force

In a terminal the command asks [y/N] first. Add -y to skip the question.

Adopt orphaned sites

A machine that is enrolled again gets a new node ID, so its old sites still point at the old ID. After you enroll it, run on the master:

sudo hctl node reassign --from <old-node-id> --to <new-node-id>

Run it only when the new node really holds those sites’ files. The --from ID must no longer be enrolled. If it still is, the command stops with “source node … is still enrolled — its sites are not orphaned”. The --to ID must be enrolled.

Check that it worked

• The node is gone from Nodes, and the verdict line no longer names it.
• On the master, sudo hctl node list does not list it.
• The audit log has a node.remove entry with the number of orphaned sites. See Review the audit log.
• After a reassign, the sites appear in Hostings again under the new node.

If it fails

• “Refused — N hosting(s) still live on …”: move the sites, or use Force.
• “Node … not found (already removed?)”: the node is already gone. Reload Nodes.
• “Remove failed: …”: the master could not complete the removal. Read the reason.
• hctl node reassign says “target node … is not enrolled — pick a live node”: enroll the machine first and use the ID shown on Nodes.