Resharding a Valkey cluster allows you to rebalance slots across existing nodes or add new nodes without downtime.
Let’s watch it happen. Imagine we have a simple 3-node Valkey cluster:
192.168.1.10:7000` (master) - Slots 0-5460
192.168.1.11:7000` (master) - Slots 5461-10922
192.168.1.12:7000` (master) - Slots 10923-16383
We want to add a new node, 192.168.1.13:7000, and rebalance the slots so each of the four nodes gets roughly 4096 slots.
First, add the new node to the cluster. It starts empty.
valkey-cli -c -h 192.168.1.10 -p 7000 cluster meet 192.168.1.13 7000
Now, initiate the rebalancing. We’ll use redis-cli --cluster reshard. This command is interactive, guiding you through the process. You’ll be asked which node to send slots to, and how many slots.
redis-cli --cluster reshard 192.168.1.10:7000
The tool will first list the current slot distribution and prompt you:
How many slots do you want to rebalance? For example: 4096
>>> 4096
Next, it asks where to send the slots from. You can specify a source node, or ask it to pick one automatically. For a balanced rebalance, you’ll typically want to spread the load. Let’s say we want to move some slots from each existing node to the new one. The reshard command will ask for the [node-id] of the source node. You can get node IDs using valkey-cli -c -h <ip> -p <port> cluster nodes.
Let’s assume the node IDs are:
node1: 1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c
node2: 2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c
node3: 3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1d
node4: 4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1e (new node)
The tool will prompt:
Moving slot 4096 from <node-id-of-node1> to <node-id-of-node4>.
# ...
Moving slot 5461 from <node-id-of-node2> to <node-id-of-node4>.
# ...
Moving slot 10923 from <node-id-of-node3> to <node-id-of-node4>.
For each slot range, it asks:
Do you want to rebalance this slot [enter to continue, or specify a different node, or 'all', or 'quit'?]
>>> all
Typing all tells redis-cli --cluster reshard to attempt to balance the slots as evenly as possible across all nodes in the cluster, including the new one. It calculates the required moves.
The reshard process works by migrating slots one by one. For each slot being moved:
- The source node temporarily marks the slot as
IMPORTINGfrom the destination node. - The destination node marks the slot as
MIGRATINGto the source node. redis-cli --cluster reshardinstructs the client (which isredis-cliitself in this case) to issue aMIGRATEcommand. This command moves the actual keys associated with that slot from the source to the destination.- Once all keys for the slot have been migrated, the slot status is updated on both nodes to reflect the new owner.
This "all" option is the magic. It doesn’t just move slots to the new node; it redistributes them across the entire cluster to achieve the desired balance. If you had specified a source node, it would move only from that source.
After the command completes, your cluster might look like this:
192.168.1.10:7000` (master) - Slots 0-4095
192.168.1.11:7000` (master) - Slots 4096-8191
192.168.1.12:7000` (master) - Slots 8192-12287
192.168.1.13:7000` (master) - Slots 12288-16383
The critical part is that during this entire process, your Valkey cluster remains available for reads and writes. Clients connected to the cluster automatically discover the slot changes and direct their requests to the correct nodes. The IMPORTING and MIGRATING states ensure that keys are not lost and that requests for slots being moved are handled correctly by proxying them to the node that currently holds the data.
The most surprising aspect of this process is how gracefully Valkey handles the "hot" migration of keys. When a slot is being migrated, redis-cli --cluster reshard issues a MIGRATE command. This command tells the source node to send all keys for that slot to the destination node. Crucially, if a client attempts to access a key during this migration, the source node will redirect the client to the destination node, ensuring that the operation is completed without error, even if the data hasn’t fully transferred yet. This redirection happens seamlessly because the slot states (IMPORTING and MIGRATING) are updated on the nodes, and clients respect these states.
The next step is typically observing the cluster’s health and performance after the rebalance, ensuring all keys have been successfully migrated and that the load is distributed as expected.