Mastering Redis Cluster: Step‑by‑Step Setup, Scaling, and Failover Guide

1. Redis Cluster Environment Setup

All six nodes (three masters and three slaves) run on a single server, distinguished by ports. The simple architecture is illustrated below.

The cluster is built from source (Redis 6.0+) to obtain redis-server and redis-cli. Since Redis 5.0, the former redis-trib.rb tool is integrated into redis-cli.

Four steps are required:

Start nodes in cluster mode.

Perform node handshakes to form a network.

Assign slots (16384 total) to masters.

Configure master‑slave replication.

1.1 Start Nodes

Each node starts as a master but with the cluster-enabled yes flag. Example configuration for 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

After editing all six configuration files, launch them with redis-server redis_XXXX_cluster.conf and verify with ps -aux | grep redis.

1.2 Node Handshake

Initially each node forms an isolated cluster. Use CLUSTER NODES to view a single entry, then connect nodes with CLUSTER MEET:

redis-cli -p 6379 -c
127.0.0.1:6379> CLUSTER MEET 127.0.0.1 6380
... (repeat for other ports) ...

After the meet commands, CLUSTER NODES shows all six nodes as masters.

1.3 Slot Assignment

The cluster shards data across 16384 slots. Assign slots to each master 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.

1.4 Master‑Slave Replication

Configure slaves to replicate their respective masters 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

1.5 Executing Commands in the Cluster

Clients send commands to any node; the node redirects to the correct master if the key’s slot belongs elsewhere, returning a MOVED error.

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

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

1.6 Failover

If a master goes down, its slaves elect a new master automatically. The log shows the election process and the cluster returning to ok state.

... FAIL message received ...
# Starting a failover election ...
# Cluster state changed: ok

2. Cluster Scaling Practice

2.1 Adding Nodes

Add two new nodes (6382 and 6482) where 6482 replicates 6382. Start the nodes, then use:

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

Rebalance slots so each master holds roughly 4096 slots:

redis-cli --cluster reshard 127.0.0.1:6479
# specify 4096 slots, target node ID of 6382, source node IDs of existing masters

Set the replication relationship for the new slave:

redis-cli -p 6482 cluster replicate af81109fc29f69f9184ce9512c46df476fe693a3

2.2 Removing Nodes

To delete the previously added nodes, first move all slots from 6382 to another master, then run:

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

3. Summary

Setting up a Redis Cluster involves starting nodes, handshaking, slot assignment, and master‑slave replication. Scaling—adding, rebalancing, or removing nodes—uses the same commands via redis-cli --cluster, simplifying management and reducing the risk of manual errors.