Scaling

This example starts with nodes 1–3, adds node 4 at 10.0.0.14, and then removes it. Open Manager → Cluster → Nodes.

Scale-out: add node 4

1. Configure and start the new node

Copy an existing node's configuration and keep unrelated settings unchanged. Update [node], remove nodes from [cluster], and use:

[node]
id = 4
data_dir = "/var/lib/wukongim"

[cluster]
id = "prod-im-a"
listen_addr = "0.0.0.0:7000"
advertise_addr = "10.0.0.14:7000"
seeds = ["10.0.0.11:7000"]
join_token = "the-same-secret-as-existing-nodes"
hash_slot_count = 256
slot_replica_n = 3
channel_replica_n = 3

Match the existing cluster's cluster.id, replica counts, and join_token. Start the process and check liveness:

sudo systemctl enable --now wukongim
curl --fail http://10.0.0.14:5001/healthz

2. Activate it in Manager

1. Wait for node 4 to show joining.
2. Open node 4 and select Activate node.
3. Wait for status active.

3. Move data in

1. Set Max slot moves to 1.
2. Select Plan slot onboarding and confirm that node 4 is the target.
3. Select Start onboarding. When active tasks reach 0, select Advance onboarding.
4. Repeat until no new task is created.

4. Verify

curl --fail http://10.0.0.11:5001/readyz
curl --fail http://10.0.0.12:5001/readyz
curl --fail http://10.0.0.13:5001/readyz
curl --fail http://10.0.0.14:5001/readyz

After all four requests pass and messages work, add 10.0.0.14:5100 and 10.0.0.14:5200 to the load balancer.

Scale-in: remove node 4

1. Remove node 4 from the load balancer and confirm that the other nodes can carry the traffic.
2. Open node 4, select Mark leaving, and wait for status leaving.
3. Select Enable drain mode. Wait for active, closing, and pending connection counts to reach 0.
4. Set Scale-in max slot moves to 1, then select Plan scale-in → Advance scale-in. Advance again after active tasks reach 0.
5. Select Refresh scale-in status. When Slot, Channel, and active task counts are 0 and Safe to remove: Yes appears, select Remove node.
6. Finally, run on node 4:

sudo systemctl disable --now wukongim

Check /readyz on the remaining nodes and test messages again. Keep node 4's data directory until the product is stable, then handle it under your data-retention process.

If an action is disabled or Manager shows a blocking reason, stop and keep the node running, then follow Troubleshooting. This procedure requires cluster.node:w.