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

This article is a practical summary of learning Redis Cluster (based on Redis 6.0+), detailing the step‑by‑step process of building a Redis Cluster environment and performing cluster scaling.

1 Redis Cluster Environment Setup

For convenience, all six nodes are placed on a single server: three master nodes and three slave nodes. The simple architecture is shown below.

We download the latest Redis 6.0+ source from GitHub and compile the common tools redis-server and redis-cli. Since Redis 5.0, the cluster management script redis-trib.rb has been integrated into redis-cli.

This section builds the cluster without using redis-trib.rb to become familiar with the basic management steps; later scaling will use redis-trib.rb (via redis-cli).

Start nodes: launch each node in cluster mode.

Node handshake: connect independent nodes into a network.

Slot assignment: allocate the 16384 hash slots to master nodes.

Master‑slave replication: assign slaves to masters.

1.1 Start Nodes

Each node initially runs as a master; the only difference is that it is started with the cluster option. Example configuration for the node listening on port 6379:

# 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

The cluster-config-file parameter specifies where the node stores its cluster configuration. When the cluster changes (e.g., nodes are added or removed), each node updates this file, and on restart the node reads it to re‑join the cluster automatically.

After editing the configuration files for all six nodes, start them with redis-server redis_xxxx_cluster.conf and verify the processes:

$ 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 the nodes, each node is isolated. Use CLUSTER NODES to view the current node list, then connect them 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
# -c runs redis-cli in cluster mode
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
127.0.0.1:6379> CLUSTER MEET 127.0.0.1 6480 OK
127.0.0.1:6379> CLUSTER MEET 127.0.0.1 6381 OK
127.0.0.1:6379> CLUSTER MEET 127.0.0.1 6382 OK

After the meet commands, all six nodes appear as masters:

c47598b25205cc88abe2e5094d5bfd9ea202335f 127.0.0.1:6380@16380 master - 0 1603632309283 4 connected
87b7dfacde34b3cf57d5f46ab44fd6fffb2e4f52 127.0.0.1:6379@16379 myself,master - 0 1603632308000 1 connected
51081a64ddb3ccf5432c435a8cf20d45ab795dd8 127.0.0.1:6381@16381 master - 0 1603632310292 2 connected
9d587b75bdaed26ca582036ed706df8b2282b0aa 127.0.0.1:6481@16481 master - 0 1603632311000 3 connected
4c23b25bd4bcef7f4b77d8287e330ae72e738883 127.0.0.1:6479@16479 master - 0 1603632312000 5 connected
32ed645a9c9d13ca68dba5a147937fb1d05922ee 127.0.0.1:6480@16480 master - 0 1603632313000 0 connected

The fields of CLUSTER NODES are documented in the official Redis manual.

1.3 Slot Assignment

Redis Cluster shards data into 16384 slots. Each key belongs to one slot, and each node can own zero or up to all 16384 slots. When all slots are assigned, the cluster state is ok; otherwise it is fail.

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 slot assignment the node view shows:

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

Cluster info confirms the state:

cluster_state:ok
cluster_slots_assigned:16384
cluster_slots_ok:16384

1.4 Master‑Slave Replication

At this point all nodes are masters, so high availability is not yet achieved. Use CLUSTER REPLICATE <node_id> to make a node a slave of a master:

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

Now the cluster has three masters and three slaves, providing high availability.

1.5 Executing Commands in the Cluster

When a client sends a command, the receiving node checks whether the key’s slot belongs to it. If not, it returns a MOVED error, directing the client to the correct node.

Example:

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"

Sending a command to a slave also results in redirection to its master.

127.0.0.1:6480> KEYS *
1) "name"
127.0.0.1:6480> get name -> Redirected to slot [5798] located at 127.0.0.1:6380
"huey"

1.6 Cluster Failover

If a master goes down, its slaves elect a new master and continue serving requests. The logs show the election process and state transition back to ok. When the original master recovers, it becomes a slave of the new master.

462:S 26 Oct 14:08:12.750 * FAIL message received ...
462:S 26 Oct 14:08:13.447 # Cluster state changed: ok

2 Cluster Scaling Practice

Scaling involves re‑sharding slots among nodes. Adding nodes:

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

After adding, use redis-cli --cluster reshard to move slots so that each master holds roughly 4096 slots.

$ redis-cli --cluster reshard 127.0.0.1:6479
How many slots do you want to move (from 1 to 16384)? 4096
What is the receiving node ID? ...

Set the slave relationship for the new nodes:

redis-cli -p 6482 cluster replicate af81109fc29f69f9184ce9512c46df476fe693a3

Removing nodes requires moving their slots away first, then deleting them:

redis-cli --cluster del-node 127.0.0.1:6482 706f399b248ed3a080cf1d4e43047a79331b714f
redis-cli --cluster del-node 127.0.0.1:6382 af81109fc29f69f9184ce9512c46df476fe693a3

3 Summary

Building a Redis Cluster consists of four core steps—starting nodes, node handshake, slot assignment, and master‑slave replication—while scaling involves the same operations. Using the integrated redis-cli --cluster commands simplifies management and reduces the risk of manual errors.