Stage 3 · Build

Redis

Redis Cluster

Hash slots, sharding, cluster topology, and resharding safely.

8 min readDatabases for SREBuild

Why Redis Cluster?

Redis Cluster provides horizontal scaling by distributing data across multiple Redis nodes. It automatically shards data, handles node failures, and rebalances the cluster. Each node is responsible for a portion of the total keyspace.

Feature	Standalone	Cluster
Max data size	Single machine RAM	Total cluster RAM
Max throughput	Single machine IOPS	Sum of all nodes
High availability	Sentinel required	Built-in
Cross-node transactions	Supported	Not supported (multi-key must be on same node)
Lua scripts	Supported	Only for keys on same node

Hash Slots

Redis Cluster divides the keyspace into 16,384 hash slots. Each node is assigned a subset of slots. A key's slot is determined by CRC16(key) % 16384. This deterministic mapping allows clients to route commands to the correct node.

Hash slot operations


# Check which slot a key belongs to
CLUSTER KEYSLOT user:1          # 5649
CLUSTER KEYSLOT user:2          # 5765
CLUSTER KEYSLOT order:1         # 8932

# Check cluster slot assignment
CLUSTER SLOTS
# 1) 1) (integer) 0        (start slot)
#    2) (integer) 5460      (end slot)
#    3) 1) "10.0.0.1"       (node IP)
#       2) (integer) 6379    (node port)

# Force keys to same slot using hash tags
CLUSTER KEYSLOT {user}:1:profile    # slot based on "user"
CLUSTER KEYSLOT {user}:2:orders     # same slot as above!
CLUSTER KEYSLOT {order}:42:items    # slot based on "order"

Hash tags { } force multiple keys to the same slot. Use {user} to co-locate user data, enabling MULTI transactions and Lua scripts across related keys.

CROSSSLOT error

Multi-key operations (MGET, SUNION, transactions) fail if keys are on different nodes. Use hash tags {prefix} to ensure related keys are on the same slot. This is the most common source of Cluster confusion.

Cluster Setup

Create a Redis Cluster


# 1. Create 6 nodes (3 primary + 3 replica)
mkdir -p /etc/redis/cluster/{7001,7002,7003,7004,7005,7006}

# 2. Configure each node
for port in 7001 7002 7003 7004 7005 7006; do
cat > /etc/redis/cluster/$port/redis.conf << EOF
port $port
cluster-enabled yes
cluster-config-file nodes-$port.conf
cluster-node-timeout 5000
appendonly yes
dir /var/lib/redis/cluster/$port
EOF
done

# 3. Start all nodes
for port in 7001 7002 7003 7004 7005 7006; do
    redis-server /etc/redis/cluster/$port/redis.conf &
done

# 4. Create the cluster
redis-cli --cluster create \
    10.0.0.1:7001 10.0.0.1:7002 10.0.0.1:7003 \
    10.0.0.1:7004 10.0.0.1:7005 10.0.0.1:7006 \
    --cluster-replicas 1

--cluster-replicas 1 means each primary gets one replica. The create command assigns slots evenly across primaries and pairs replicas to primaries.

Resharding

Reshard the cluster


# Check cluster status
redis-cli --cluster check 10.0.0.1:7001

# Reshard: move 1000 slots from node 7001 to 7002
redis-cli --cluster reshard 10.0.0.1:7001 \
    --cluster-from <source-node-id> \
    --cluster-to <target-node-id> \
    --cluster-slots 1000 \
    --cluster-yes

# Interactive resharding
redis-cli --cluster reshard 10.0.0.1:7001
# How many slots? 1000
# Source node? <node-id>
# Destination node? <node-id>

# Add a new node to the cluster
redis-cli --cluster add-node 10.0.0.2:7007 10.0.0.1:7001

# Remove a node
redis-cli --cluster del-node 10.0.0.1:7001 <node-id>

Resharding moves slots between nodes while the cluster is running. Redis migrates keys slot by slot, redirecting clients with MOVED responses during migration. This is safe and non-blocking.

Reshard during low traffic

While resharding is non-blocking, it generates network traffic for key migration. Schedule large resharding operations during low-traffic periods to minimize impact on latency.

Cluster Operations

Cluster management commands


# Cluster information
CLUSTER INFO
# cluster_state:ok
# cluster_slots_assigned:16384
# cluster_slots_ok:16384
# cluster_known_nodes:6
# cluster_size:3

# List all nodes
CLUSTER NODES
# <node-id> 10.0.0.1:7001@17001 master - 0 1234567890 1 connected 0-5460
# <node-id> 10.0.0.2:7002@17002 master - 0 1234567890 2 connected 5461-10922

# Check specific node
CLUSTER MYID

# Monitor cluster events
CLUSTER COUNT-FAILURE-REPORTS <node-id>

# Force node to forget another node (use with caution)
CLUSTER FORGET <node-id>

CLUSTER NODES shows the complete topology including which slots each node owns and which node is its replica. This is the primary tool for understanding cluster state.

Failure Modes

Handling failures


# Primary failure:
# 1. Cluster marks primary as FAIL after cluster-node-timeout
# 2. Replica is automatically promoted
# 3. Other primaries update their routing tables

# Replica failure:
# 1. Primary continues serving
# 2. No automatic replica replacement (manual intervention needed)
# 3. Use CLUSTER REPLICATE to assign new replica

# Split-brain prevention:
# - cluster-require-full-coverage yes (default)
#   If any slot is unassigned, entire cluster refuses writes
# - cluster-require-full-coverage no
#   Cluster serves requests for available slots only

# Network partition handling:
# - Nodes on minority side become read-only (ASK/MOVED redirects)
# - Nodes on majority side continue normally
# - When partition heals, minority nodes sync from majority

Redis Cluster uses a gossip protocol to detect failures. Each node gossips with others to share state. When a majority of nodes agree a primary is down, failover proceeds automatically.

Cluster is not a silver bullet

Redis Cluster adds complexity: no multi-key transactions across nodes, Lua scripts limited to single node, debugging is harder. Use standalone + Sentinel for simpler use cases. Only use Cluster when you need horizontal scaling.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.