Manage nodes
See the fleet
orchestrator-zero node list # every node
orchestrator-zero node list --state pending # pending, accepted, rejected, blocked or purging
orchestrator-zero node list --tenant acme
orchestrator-zero node show node-7f3a01b2c4d5 # one node in detail
Add --json to any of them for scripts.
A node's states
| State | Meaning |
|---|---|
pending | Joined without a token and waiting for an operator |
accepted | Allowed in; it connects and runs work |
rejected | Refused at approval |
blocked | Shut out; it keeps its files and can be unblocked |
purging | Removing itself from its machine on its next control stream, then forgotten |
Block and unblock
orchestrator-zero node block node-7f3a01b2c4d5 --reason "lost laptop"
orchestrator-zero node unblock node-7f3a01b2c4d5
Blocking takes effect within two seconds on every server: the node's control stream closes, its Temporal calls are refused and its runtime stops. Jobs it was running continue on other nodes where they can. The reason goes to the audit log. Unblocking needs nothing on the node; it notices within ten seconds.
Remove a node
orchestrator-zero node delete node-7f3a01b2c4d5
delete forgets the node. Its key may join again, as a new node. The node's files stay on its machine.
Purge a node
Purging makes a node remove itself from its machine. It cannot be undone:
orchestrator-zero node purge node-7f3a01b2c4d5 --yes
In the web UI, it is Purge in a node's Actions, which asks first.
- The node stops getting work at once, as a blocked node does.
- On its next control stream it gets a purge command signed with the cluster CA's key. A blocked node gets it too, and an offline node gets it when it comes back.
- The node checks the signature against the CA certificate it holds, and that the command names its own cluster and ID. A command that fails the check is refused, and the audit log records
node.purge.refused. - It answers the edge, which forgets the node (
node.purgedin the audit log), and then it stops its runtimes and plugins and deletes its data directory (keys, plugins, runtimes, Python and tools) and its binary.
To join again, the machine must be set up again. The node deletes its data directory only if it holds a node identity, and follows no symbolic links out of it. A node that never comes back stays purging; node delete forgets it.
Join tokens
orchestrator-zero token create --tenant default --ttl 24h --max-uses 5 --label team=data --description "data team laptops"
orchestrator-zero token list
orchestrator-zero token revoke <token-id>
--ttl 0 makes a token that never expires and --max-uses 0 one that can be used any number of times. Revoking a token stops new joins; nodes that already joined with it stay.