miroir/docs/ctl/node.md

miroir-ctl node

Purpose

Manage cluster topology — add, remove, drain, and list nodes.

Preconditions

• Target node must be running and reachable from the orchestrator
• Node's Meilisearch instance should be healthy before adding
• For removal: node should be drained first to avoid data loss

Examples

# Add a new node to replica group 0
miroir-ctl node add --id node-3 --address http://node-3:7700 --replica-group 0

# List all nodes with status
miroir-ctl node list

# Drain a node before removal (migrates its shards elsewhere)
miroir-ctl node drain node-2

# Remove a node after draining completes
miroir-ctl node remove node-2

# Force remove (dangerous — skips drain, may lose data)
miroir-ctl node remove node-2 --force --yes

Gotchas

• node add triggers automatic rebalancing — use miroir-ctl rebalance status --watch to track
• node drain is async — the command returns immediately but migrations continue in background
• Never use --force unless the node is permanently dead — you'll lose RF replicas
• node list shows the same info as miroir-ctl status but in table format

See also

• Plan §13.2 — node addition and rebalancing
• Plan §13.3 — node drain and removal
• miroir-ctl rebalance status — track migration progress