Drain or rename a node

Draining marks a worker as closed for new hostings. Sites already on it keep serving traffic. Use it before maintenance, a disk replacement or a planned reboot, so the automatic placement stops choosing that node.

Before you start

• Sign in as an Owner.
• The node is a worker. The master cannot be drained; to keep new sites off it, see Choose where new sites go.
• Draining does not move anything. To move existing sites away, use Move / copy on each site.

Steps

Drain

1. Open Nodes in the sidebar and click the worker’s row.
2. In the Placement section, click Drain and confirm Drain node in the dialog.

The page shows “Node <node-id> drained — auto-placer will skip it. Existing hostings keep serving.” The row gets a Drained flag. Hover over it to see the reason and the sentence “new sites are not placed here; existing ones keep serving.”

The panel records the reason Maintenance. To record your own reason, drain from a shell on the master:

sudo hctl node drain <node-id> --reason "disk replacement Friday"

sudo hctl node list shows each node’s id and whether it is drained.

Return to service

1. Open the drained node’s row. Under Placement, click Return to service and confirm Return to service.
2. The page shows “Node <node-id> returned to active service.”

From a shell: sudo hctl node undrain <node-id>.

Rename

Every enrolled worker has a label, set at enrollment, and a node ID that never changes. Renaming changes only the label, which the panel shows in lists and in Which server should host this?. The master’s label is its hostname and cannot be edited.

1. In the worker’s Placement section, edit the label in the field next to Rename. It holds up to 80 characters and cannot be empty.
2. Click Rename. The page shows “Node renamed to ‘<label>’.”

From a shell on the master:

sudo hctl node label <node-id> "Worker 2"

Check that it worked

• Add a website, under Hostings, no longer lists the drained node in Which server should host this?. The Auto choice skips it as well.
• The row shows the Drained flag while drained, and no flag after the return.
• Sites already on the node still load.
• After a rename, the row title and the verdict line use the new label, and the Node ID is unchanged.

If it fails

• “Drain toggle failed: …” followed by the reason: the master could not save the change. Read the reason and retry.
• A new site still lands on the node: the node was not drained when the site was created. Check the row for the Drained flag.
• Auto skips a node you did not drain: Auto picks only nodes that answer, so an offline worker is skipped whether or not it is drained. Check it with Check the health of your nodes.
• “Label cannot be empty.” or “Rename failed: …”: type a label before you click Rename, or read the reason after “Rename failed” and retry.