Mastering Redis Cluster: Setup, Sharding, and High Availability Guide

This document is an introductory tutorial on Redis Cluster from a user’s perspective, covering how to set up, test, and operate a cluster.

The tutorial avoids obscure distributed concepts and implementation details, recommending the official cluster specification for deeper study.

Redis Cluster is currently in Alpha; users should report issues via the Redis mailing list or GitHub.

Cluster Overview

Redis Cluster enables data sharing across multiple Redis nodes.

It does not support commands that need to operate on multiple keys simultaneously because moving data between nodes would degrade performance and cause unpredictable behavior under high load.

Cluster availability is achieved through partitioning: even if some nodes fail or lose communication, the cluster can continue processing requests.

Benefits include automatic data splitting across nodes and continued operation despite node failures.

Data Sharding

Redis Cluster uses sharding with 16,384 hash slots. Each key maps to a slot via CRC16(key) % 16384.

Each node handles a subset of slots. For example, a three‑node cluster might assign slots 0‑5500 to Node A, 5501‑11000 to Node B, and 11001‑16384 to Node C.

Adding or removing nodes only requires moving the relevant slots, without blocking the cluster.

Replication and Failover

Each node can have one or more replicas; one replica acts as the master, others as slaves.

If a master goes down, its replica is promoted to master, preserving slot handling. If both master and its replica are down, the cluster stops.

Consistency Guarantees

Redis Cluster does not provide strong consistency; writes may be lost under certain conditions, such as asynchronous replication or network partitions.

During a network split, a minority partition may continue accepting writes that are later discarded when the majority re‑elects a new master.

Node timeout settings determine how long a master can be unreachable before being considered down.

Creating and Using a Redis Cluster

Cluster mode must be enabled in each Redis instance’s configuration:

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

At least three master nodes are required; for testing, six nodes (three masters, three replicas) are recommended.

Setup steps:

mkdir cluster-test
cd cluster-test
mkdir 7000 7001 7002 7003 7004 7005

Create a redis.conf in each directory, adjusting the port number accordingly.

Compile Redis from the latest source and start each instance:

cd 7000
../redis-server ./redis.conf

Each node receives a unique ID stored in nodes.conf, which is used for inter‑node communication.

Cluster Creation

Use the redis-trib.rb tool to create the cluster:

./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 tool allocates hash slots, assigns replicas, and confirms the configuration. After confirming with yes, the cluster joins and all 16,384 slots are covered.

Clients

Client support is limited. Notable implementations include:

redis‑rb‑cluster (Ruby)

redis‑py‑cluster (Python, unmaintained)

Predis (PHP, partial support)

redis‑cli with -c flag (basic support)

Example using redis-cli:

$ redis-cli -c -p 7000
redis 127.0.0.1:7000> set foo bar
-> Redirected to slot [12182] located at 127.0.0.1:7002
OK

redis 127.0.0.1:7002> set hello world
-> Redirected to slot [866] located at 127.0.0.1:7000
OK

redis 127.0.0.1:7000> get foo
-> Redirected to slot [12182] located at 127.0.0.1:7002
"bar"

redis 127.0.0.1:7000> get hello
-> Redirected to slot [866] located at 127.0.0.1:7000
"world"

A serious client should cache slot‑to‑node mappings to avoid repeated redirections and update the cache when the cluster layout changes (e.g., after failover or node addition/removal).