Step-by-Step Guide to Building and Scaling a Redis Cluster on Redis 6.0+

Redis Cluster Overview

Redis Cluster is Redis's distributed database solution that uses sharding to share data across nodes while providing replication and failover. Compared with master‑slave replication and Sentinel, it offers a more complete high‑availability architecture, overcoming single‑machine storage limits and unbalanced write loads.

This article summarizes a hands‑on learning experience, detailing the step‑by‑step process of building a Redis Cluster environment and performing cluster scaling.

1 Redis Cluster Environment Setup

All six nodes (three masters and three slaves) run on the same server, distinguished by ports. The simple architecture is shown below:

The setup uses Redis 6.0+, compiled from source to obtain redis-server and redis-cli. Since Redis 5.0, the cluster management script redis‑trib.rb has been integrated into redis-cli.

The following four steps constitute the cluster build process:

Start nodes in cluster mode (each node starts as a master).

Node handshake – connect independent nodes into a network.

Slot assignment – distribute the 16384 hash slots among master nodes.

Master‑slave replication – assign a slave to each master.

1.1 Start Nodes

Each node’s configuration file (e.g., redis_6379_cluster.conf) must enable clustering and specify the cluster config file, log file, and other parameters:

# redis_6379_cluster.conf
port 6379
cluster-enabled yes
cluster-config-file "node-6379.conf"
logfile "redis-server-6379.log"
dbfilename "dump-6379.rdb"
daemonize yes

After editing the six configuration files, start each server with redis-server redis_XXXX_cluster.conf and verify processes using ps -aux | grep redis:

$ ps -aux | grep redis
... 800  0.1  0.0  49584  2444 ?        Ssl 20:42   0:00 redis-server 127.0.0.1:6379 [cluster]
... 805  0.1  0.0  49584  2440 ?        Ssl 20:42   0:00 redis-server 127.0.0.1:6380 [cluster]
... 812  0.3  0.0  49584  2436 ?        Ssl 20:42   0:00 redis-server 127.0.0.1:6381 [cluster]
... 817  0.1  0.0  49584  2432 ?        Ssl 20:43   0:00 redis-server 127.0.0.1:6479 [cluster]
... 822  0.0  0.0  49584  2380 ?        Ssl 20:43   0:00 redis-server 127.0.0.1:6480 [cluster]
... 827  0.5  0.0  49584  2380 ?        Ssl 20:43   0:00 redis-server 127.0.0.1:6481 [cluster]

1.2 Node Handshake

After starting, each node is isolated. Use CLUSTER NODES to view the single‑node view, then connect nodes with CLUSTER MEET:

127.0.0.1:6379> CLUSTER NODES
37784b3605ad216fa93e976979c43def42bf763d :6379@16379 myself,master - 0 0 0 connected 449 4576 5798 7568 8455 12706

redis-cli -p 6379 -c
127.0.0.1:6379> CLUSTER MEET 127.0.0.1 6380
OK
127.0.0.1:6379> CLUSTER MEET 127.0.0.1 6381
OK
...

Running CLUSTER NODES again shows all six nodes as masters:

c47598b25205cc88abe2e5094d5bfd9ea202335f 127.0.0.1:6380@16380 master - 0 1603632880310 4 connected 5001-10000
87b7dfacde34b3cf57d5f46ab44fd6fffb2e4f52 127.0.0.1:6379@16379 myself,master - 0 1603632879000 1 connected 0-5000
51081a64ddb3ccf5432c435a8cf20d45ab795dd8 127.0.0.1:6381@16381 master - 0 1603632879000 2 connected 10001-16383
9d587b75bdaed26ca582036ed706df8b2282b0aa 127.0.0.1:6481@16481 master - 0 1603632878000 5 connected
4c23b25bd4bcef7f4b77d8287e330ae72e738883 127.0.0.1:6479@16479 master - 0 1603632880000 3 connected
32ed645a9c9d13ca68dba5a147937fb1d05922ee 127.0.0.1:6480@16480 master - 0 1603632881317 0 connected

The output format is

<id> <ip:port@cport> <flags> <master> <ping-sent> <pong-recv> <config-epoch> <link-state> <slot> ...

.

1.3 Slot Assignment

Redis Cluster divides the keyspace into 16384 slots. Each master can own any number of slots; a slot is the basic unit for data placement and migration. The cluster becomes operational (state ok) only when all slots are assigned.

Assign slots with CLUSTER ADDSLOTS:

redis-cli -p 6379 cluster addslots {0..5000}
redis-cli -p 6380 cluster addslots {5001..10000}
redis-cli -p 6381 cluster addslots {10001..16383}

After assignment, CLUSTER INFO reports cluster_state:ok and all 16384 slots are covered.

1.4 Master‑Slave Replication

Configure each slave to replicate its corresponding master using CLUSTER REPLICATE <node_id>:

redis-cli -p 6479 cluster replicate 87b7dfacde34b3cf57d5f46ab44fd6fffb2e4f52
redis-cli -p 6480 cluster replicate c47598b25205cc88abe2e5094d5bfd9ea202335f
redis-cli -p 6481 cluster replicate 51081a64ddb3ccf5432c435a8cf20d45ab795dd8

Running CLUSTER NODES now shows the slave relationships.

1.5 Executing Commands in the Cluster

When a client sends a command, the receiving node calculates the key’s slot. If the slot belongs to the node, the command executes; otherwise the node returns a MOVED error directing the client to the correct node.

127.0.0.1:6379> CLUSTER KEYSLOT name
(integer) 5798
127.0.0.1:6379> set name huey -> Redirected to slot [5798] located at 127.0.0.1:6380 OK
127.0.0.1:6379> get fruits -> Redirected to slot [14943] located at 127.0.0.1:6381
"apple"

Commands sent to a slave are also redirected to its master.

1.6 Failover

If a master goes down, one of its slaves is promoted to master automatically. After the original master recovers, it becomes a slave of the new master.

462:S 26 Oct 14:08:12.750 * FAIL message received from c47598b25205cc88abe2e5094d5bfd9ea202335f about 87b7dfacde34b3cf57d5f46ab44fd6fffb2e4f52
... Cluster state changed: fail
... Starting a failover election ...
... Failover election won: I'm the new master.
... Cluster state changed: ok

2 Cluster Scaling Practice

Scaling involves re‑sharding slots among nodes. The example adds two new nodes (6382 and 6482) and later removes them.

2.1 Adding Nodes

Start the new nodes using the same configuration steps as 1.1, then add them to the cluster:

redis-cli --cluster add-node 127.0.0.1:6382 127.0.0.1:6379
redis-cli --cluster add-node 127.0.0.1:6482 127.0.0.1:6379

Perform a reshard to move 4096 slots to the new master (node 6382) so each master ends up with roughly 4096 slots:

redis-cli --cluster reshard 127.0.0.1:6479
# Follow prompts: move 4096 slots, target node ID = <em>6382's ID</em>, source nodes = 6379, 6380, 6381

Set the slave relationship for the new slave (6482) to replicate the new master:

redis-cli -p 6482 cluster replicate af81109fc29f69f9184ce9512c46df476fe693a3

2.2 Removing Nodes

First, reshard all slots from node 6382 to another master (e.g., 6479), then delete the slave and master nodes:

redis-cli --cluster reshard 127.0.0.1:6382
# Move all slots to node 6479
redis-cli --cluster del-node 127.0.0.1:6482 706f399b248ed3a080cf1d4e43047a79331b714f
redis-cli --cluster del-node 127.0.0.1:6382 af81109fc29f69f9184ce9512c46df476fe693a3

3 Conclusion

Building a Redis Cluster consists of node startup, handshake, slot assignment, and master‑slave replication. Scaling the cluster follows the same steps and can be efficiently managed with redis-cli --cluster commands, reducing operational complexity and the risk of mistakes.