Redis Cluster Mastery: Step‑by‑Step Setup, Scaling, and Management Guide

Redis Cluster Tutorial

Redis Cluster provides a way to run a Redis installation where data is automatically sharded across multiple Redis nodes.

1. Redis Cluster TCP Ports

Each node requires two TCP ports: the client port (default 6379) and the cluster bus port (client port + 10000, e.g., 16379) used for node‑to‑node communication, failure detection, configuration updates and fail‑over. Clients must only use the client port.

The offset between the command port and the cluster bus port is always 10000. Both ports must be reachable by other nodes and clients.

Client communication port (usually 6379) must be open to all clients.

Cluster bus port (client port + 10000) must be reachable by all other nodes.

2. Redis Cluster Data Sharding

Redis Cluster uses 16384 hash slots. The hash slot for a key is calculated as CRC16(key) modulo 16384. Each node is responsible for a subset of the slots.

Node A: slots 0‑5500

Node B: slots 5501‑11000

Node C: slots 11001‑16383

Slots can be moved between nodes without stopping the cluster, allowing seamless addition or removal of nodes.

Multiple keys can be operated on in a single command only if they belong to the same hash slot; hash tags can force keys into the same slot.

3. Redis Cluster Master‑Slave Model

Each hash slot has one master and N replicas. If a master fails, a replica is promoted to master, keeping the cluster available.

4. Consistency Guarantees

Redis Cluster does not provide strong consistency; writes may be lost because replication is asynchronous. Writes can be lost if a master acknowledges a write and then crashes before propagating it to its replicas.

Synchronous writes are possible with the WAIT command, but strong consistency is still not guaranteed.

A network partition can also cause lost writes when the minority side continues to accept writes that later get discarded.

The node‑timeout setting determines when a master is considered failed and a replica is promoted.

5. Configuration Parameters

cluster-enabled yes/no – enable cluster mode.

cluster-config-file <filename> – file where the node stores its configuration.

cluster-node-timeout <ms> – timeout after which a node is considered failed.

cluster-slave-validity-factor <factor> – multiplier for node‑timeout to determine how long a slave can be unreachable.

cluster-migration-barrier <count> – minimum number of slaves a master must have to be eligible for promotion.

cluster-require-full-coverage yes/no – whether the cluster stops accepting writes when some slots are uncovered.

6. Creating and Using a Redis Cluster

To create a cluster you need several Redis instances started with cluster-enabled yes and a proper cluster-node-timeout. A minimal configuration file looks like:

port 7000
cluster-enabled yes
cluster-config-file nodes.conf
cluster-node-timeout 5000
appendonly yes

After starting the instances, use the redis-trib.rb (or create‑cluster) tool to create the cluster, e.g.:

./redis-trib.rb create --replicas 1 127.0.0.1:7000 127.0.0.1:7001 127.0.0.1:7002 127.0.0.1:7003 127.0.0.1:7004 127.0.0.1:7005

The command assigns one slave to each master. cluster nodes shows node ID, address, flags, and slots.

6.1 Adding a New Node

Create a new instance, then run:

./redis-trib.rb add-node 127.0.0.1:7006 127.0.0.1:7000

6.2 Adding a Node as a Replica

./redis-trib.rb add-node --slave 127.0.0.1:7006 127.0.0.1:7000

6.3 Removing a Node

./redis-trib.rb del-node 127.0.0.1:7000 <node-id>

6.4 Resharding

./redis-trib.rb reshard 127.0.0.1:7000

6.5 Killing and Stopping Instances

pkill -9 redis

6.6 Using create‑cluster

Navigate to utils/create-cluster, run create-cluster start and then create-cluster create to build the cluster.

7. Help and References

Run redis-trib.rb --help for command usage. See the official tutorial at https://redis.io/topics/cluster-tutorial .