Cluster Rebalancing Planner for Redis and Valkey

Paste the output of CLUSTER NODES and see which hash slots to move between the primaries of a Redis or Valkey cluster so each one carries its share, by slot count or by bytes. Fill a primary you just added, drain one you want to remove, or even out a cluster whose keys have drifted. You get the numbers before and after, every move, and a shell script of the standard commands that does the moving when you run it. The planning runs in your browser.

Nothing you paste leaves this page. The tool doesn’t send anything anywhere, and the page’s security policy stops it from fetching or loading anything from another site. It never connects to your cluster. The script it writes does, but only when you run it yourself.

On a wide screen you can open it full screen.

How to Use It

  1. Paste your cluster. The output of redis-cli -h HOST -p PORT CLUSTER NODES from any node, or valkey-cli. A primary you added with no slots yet takes part.
  2. Choose what to balance. Slot counts, or bytes. For bytes, paste a key list with sizes, such as MEMORY USAGE gives, or a list of slots with sizes.
  3. Set weights. Weight 2 gives a primary twice the normal share, and Drain empties it. Leave the threshold at 2 percent, as redis-cli --cluster rebalance does, or cap how many slots move in one go.
  4. Read the plan, then the script. Slots or bytes per primary before and after, each move with its slot ranges, and the script to download. Read it before you run it.

How Slots Move

A cluster moves data a slot at a time, with every key in it. For each slot the receiving primary is told it is IMPORTING the slot and the giving one that it is MIGRATING, the keys go across with MIGRATE, and then every primary is told the new owner with SETSLOT NODE. Clients keep working throughout: a key that has already moved gets an ASK redirect to its new home.

The planner gives each primary a target in proportion to its weight. Primaries above target give slots from the top of their highest range, so what they keep stays in long runs, and each slot goes to the primary furthest below target. By bytes, a slot only moves if that leaves the giver closer to its target than keeping it would. A slot can’t be split, so a slot full of keys that share one hash tag can limit how even it gets.

Before planning it checks the cluster is safe to change. It refuses, with the reason and the command that fixes it, when slots have no owner, a slot is half moved, two primaries claim one slot, or a primary is failing or has no address.

The Script

The script is plain shell. It moves one range of slots at a time, with one redis-cli call per node for each step, and stops at the first reply that isn’t OK. A slot only changes owner once the giving primary holds no key in it, since it would drop any key it still had; a key it can’t move, such as one with an empty name, stops the script at that slot with the key safe. A primary that gives away its last slot may turn into a replica of the one that took it and refuse the last commands, and the script accepts that only once the primary really is left with nothing. If it stops part way, redis-cli --cluster fix closes the slots it left open; then plan again.

How It Was Tested

Real clusters of seven nodes ran on Redis 6.2.24, 7.4.11 and 8.10.2 and Valkey 8.0.11 and 9.1.2, built from source: three primaries with a replica each and one empty primary, holding 4,000 keys, the biggest 300 under five shared hash tags. Each cluster went through three plans in a row, each carried out by the planner’s own script with that version’s redis-cli or valkey-cli:

  • Filling the empty primary moved 4,096 slots in 14 to 30 seconds.
  • Balancing by bytes took the fullest primary from 26 percent over its share to within 0.1 percent, moving about 6.6 percent of the bytes.
  • Draining a primary, with weight 2 for the new one, moved about 3,970 slots.

In all 15 runs every node ended up agreeing on exactly the owners in the plan, slot for slot, and all 4,000 keys read back with their exact values. The first version of the script moved one slot at a time and took over 15 minutes to fill the empty primary, which is why it now moves whole ranges.

The Code

The planner’s logic is one JavaScript file with no dependencies, open source under the Apache License 2.0. It runs as this page, as a command line in Node.js, and inside your own code:

redis-cli -h 10.0.0.1 CLUSTER NODES > nodes.txt
node rebalance/cli.js nodes.txt --script rebalance.sh
node rebalance/cli.js nodes.txt --drain 10.0.0.2:6379 --cli valkey-cli --script drain.sh

The full manual, the tests and the recorded clusters are in the rebalance folder on GitHub. The other tools work the same way.