Mastering Redis Cluster: Step‑by‑Step Setup, Scaling, and Failover on Redis 6+

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.

Redis Cluster Overview

Redis Cluster is Redis's distributed database solution that uses sharding for data sharing and provides replication and failover. Compared with master‑slave replication and Sentinel, Redis Cluster offers a more complete high‑availability solution, overcoming single‑node storage limits and enabling write load balancing.

1. Building the Redis Cluster Environment

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

The environment uses the latest Redis 6.0+ source compiled from GitHub, providing redis-server and redis-cli. Since Redis 5.0, the cluster management tool redis-trib.rb has been integrated into redis-cli.

The cluster is built manually (without redis-trib.rb) to familiarize with basic steps; later scaling uses redis-trib.rb for resharding.

The setup consists of four steps:

Start nodes in cluster mode.

Node handshake to form a network.

Slot assignment: distribute the 16384 slots among master nodes.

Master‑slave replication.

1.1 Start Nodes

Each node starts as a master server but with the cluster-enabled yes option. 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

The cluster-config-file stores the node’s cluster state and is automatically maintained; no manual edits are needed.

After configuring all six nodes, start them with redis-server redis_XXXX_cluster.conf and verify with:

$ ps -aux | grep redis
... redis-server 127.0.0.1:6379 [cluster]
... redis-server 127.0.0.1:6380 [cluster]
... redis-server 127.0.0.1:6381 [cluster]
... redis-server 127.0.0.1:6479 [cluster]
... redis-server 127.0.0.1:6480 [cluster]
... redis-server 127.0.0.1:6481 [cluster]

1.2 Node Handshake

Initially each node is isolated. Use CLUSTER NODES to view a single node’s view, then connect nodes with CLUSTER MEET:

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
...

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

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

1.3 Slot Assignment

Redis Cluster splits the keyspace into 16384 slots. Assign slots to masters using 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 slots are covered.

1.4 Master‑Slave Replication

Configure slaves with CLUSTER REPLICATE <node_id> so each master has a replica, achieving high availability.

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

Alternatively, the entire cluster can be created in one command:

redis-cli --cluster create 127.0.0.1:6379 127.0.0.1:6479 127.0.0.1:6380 127.0.0.1:6480 127.0.0.1:6381 127.0.0.1:6481 --cluster-replicas 1

1.5 Executing Commands in the Cluster

When the cluster is online, a client sends a command to any node. The node determines the slot for the key and either executes it (if it owns the slot) or 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.

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 Failover

If a master goes down, its replicas elect a new master and continue serving requests. The log shows the election and state transition back to ok. When the original master recovers, it becomes a replica of the new master.

... FAIL message received ...
... Cluster state changed: fail
... Starting a failover election ...
... Failover election won: I'm the new master.
... Cluster state changed: ok

2. Cluster Scaling Practice

2.1 Adding Nodes

To add two nodes (6382 and 6482, with 6482 as a replica of 6382): start the nodes, then use redis-cli --cluster add-node to join them, followed by resharding to balance slots, and finally set the replica relationship.

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
# Reshard 4096 slots to the new master 6382
redis-cli --cluster reshard 127.0.0.1:6479
# Set replica
redis-cli -p 6482 cluster replicate af81109fc29f69f9184ce9512c46df476fe693a3

2.2 Removing Nodes

To remove the previously added nodes, first move all slots from 6382 to other masters, then delete the slave 6482 and finally the master 6382.

redis-cli --cluster reshard 127.0.0.1:6382   # move 4096 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. Summary

Setting up a Redis Cluster involves starting nodes, performing a handshake, assigning slots, and configuring master‑slave replication. Scaling—adding or removing nodes—follows the same steps. Using redis-cli --cluster commands simplifies management and reduces the risk of manual errors.