Cluster

Introduction

Replication and Sentinel protect you from single-server failure, but they do not help when your dataset outgrows the RAM of one machine. Redis Cluster shards data across multiple master nodes, giving you horizontal scalability and continued availability if individual nodes fail. This chapter explains the hash-slot model, walks through creating a cluster, and highlights the constraints you must accept when moving from a single Redis instance to a distributed topology.

Prerequisites

Completion of Replication and Sentinel
Six Redis instances (three masters and three replicas) running on separate ports or machines
Redis 5.0 or newer for the built-in redis-cli --cluster helper

The Hash Slot Model

Redis Cluster partitions data into 16,384 hash slots (numbered 0 through 16383). Every key belongs to exactly one slot, computed from the key name:

plaintext

slot = CRC16(key) mod 16384

Each master node owns a contiguous range of slots. When you store a key, Redis routes it to the node responsible for that slot.

plaintext

Tip

Why 16,384?

The number is large enough to distribute data evenly, small enough to fit slot-to-node mappings comfortably in a single packet, and practical to reshuffle when adding or removing nodes.

Hash Tags for Locality

By default, a key maps to a slot based on its full name. If you need related keys to live on the same node—so you can use multi-key operations—you can use hash tags:

bash

# Everything inside {user:42} hashes to the same slot
SET {user:42}:name "Ada"
SET {user:42}:email "ada@example.com"
HSET {user:42}:profile age 30 city "London"

Only the substring between the first { and the first } inside the key name is used for the CRC16 calculation. This guarantees that user:42:name and user:42:email always reside on the same shard.

Creating a Cluster

Start Six Instances

Create six minimal configuration files. The only cluster-specific settings are cluster-enabled, cluster-config-file, and cluster-node-timeout.

conf

# node-6379.conf
port 6379
cluster-enabled yes
cluster-config-file nodes-6379.conf
cluster-node-timeout 5000
appendonly yes
daemonize yes

Repeat for ports 6380, 6381, 6382, 6383, and 6384. Start each instance:

bash

redis-server node-6379.conf
redis-server node-6380.conf
# ... and so on

Form the Cluster

Redis ships with a cluster helper built into redis-cli:

bash

redis-cli --cluster create \
  127.0.0.1:6379 127.0.0.1:6380 127.0.0.1:6381 \
  127.0.0.1:6382 127.0.0.1:6383 127.0.0.1:6384 \
  --cluster-replicas 1

The --cluster-replicas 1 flag assigns one replica to each master automatically. The command proposes a slot distribution; type yes to confirm.

Verify the Topology

bash

# Connect to any node
redis-cli -p 6379
 
# Show cluster nodes
CLUSTER NODES
 
# Show slot assignments
CLUSTER SLOTS

CLUSTER NODES returns a long line per node including its ID, role, master ID (if a replica), connection status, and assigned slot ranges.

Routing Requests: MOVED and ASK

Cluster clients must handle redirection. If a client sends a request to the wrong node, Redis replies with a MOVED or ASK error.

MOVED

A MOVED error means the slot has permanently moved to another node. The client should update its slot map and retry.

plaintext

127.0.0.1:6379> GET somekey
(error) MOVED 15495 127.0.0.1:6382

ASK

An ASK error appears during a slot migration. The client should send an ASKING command and retry on the target node.

plaintext

127.0.0.1:6379> GET somekey
(error) ASK 15495 127.0.0.1:6382

Modern client libraries (Jedis, Lettuce, redis-py, ioredis) handle both redirections automatically. You rarely see these errors unless you use redis-cli without the -c cluster-aware flag.

bash

# Use -c to have redis-cli follow redirects automatically
redis-cli -c -p 6379
GET somekey
# Redirected to slot [15495] located at 127.0.0.1:6382
# "value"

Adding and Removing Nodes

Adding a New Master

bash

# Join the new node to the cluster
redis-cli --cluster add-node 127.0.0.1:6385 127.0.0.1:6379
 
# Reshard: move some slots from existing masters to the new node
redis-cli --cluster reshard 127.0.0.1:6379

The resharding wizard asks how many slots to move and which node should receive them. You can also specify source nodes manually.

Adding a New Replica

bash

# Add a replica to a specific master
redis-cli --cluster add-node 127.0.0.1:6386 127.0.0.1:6379 \
  --cluster-slave --cluster-master-id <master-node-id>

Removing a Node

bash

# Reshard its slots away first
redis-cli --cluster reshard 127.0.0.1:6379
 
# Then remove it
redis-cli --cluster del-node 127.0.0.1:6379 <node-id>

Warning

Never Remove a Master That Still Holds Slots

Always migrate slots away before deleting a master node. Otherwise, the cluster enters a degraded state and rejects writes for those slots.

Failover in Cluster Mode

Like Sentinel, Redis Cluster detects node failures and promotes replicas automatically. The difference is that the detection and election logic are built into the nodes themselves; you do not run separate Sentinel processes.

A master stops responding to pings.
Replicas and other masters mark it as PFAIL (possibly failed).
If a majority of masters agree, the state becomes FAIL.
The failed master's replicas vote to elect one of themselves.
The winning replica takes over its master's slots.

You can also trigger a manual failover:

bash

# On the replica you want to promote
redis-cli -p 6382 CLUSTER FAILOVER

Cluster Limitations

Moving to Cluster gives you scale, but it introduces constraints that do not exist on a single instance.

Feature	Single Instance	Cluster
Multi-key commands (`MGET`, `MSET`)	Unlimited	Only if all keys hash to the same slot (use hash tags)
Transactions (`MULTI` / `EXEC`)	Full support	Only if all keys are in the same slot
Lua scripts	Full support	Must target a single slot; no cross-slot reads
Database selection (`SELECT`)	16 databases	Only database `0`
Key scan (`KEYS`, `SCAN`)	Single namespace	Must run per node

Tip

Design for Cluster Early

If you think you may need Cluster in the future, adopt hash-tagged key naming from the start. Retrofitting a single-instance application to be cluster-safe is tedious and error-prone.

Monitoring Cluster Health

bash

# Cluster state: ok or fail
redis-cli -p 6379 CLUSTER INFO
 
# Per-node view
redis-cli -p 6379 CLUSTER NODES
 
# Count keys per slot range (run on each master)
redis-cli -p 6379 CLUSTER COUNTKEYSINSLOT 15495

Watch these fields in CLUSTER INFO:

cluster_state: Must be ok.
cluster_slots_assigned: Must be 16384.
cluster_slots_fail: Should be 0.
cluster_known_nodes: Matches your expected node count.

FAQ

How many nodes should a production cluster have?

At minimum, three masters plus one replica each (six nodes) for quorum and failover. Larger datasets scale by adding more master-replica pairs.

Can I run a Redis Cluster on a single machine?

Yes, for testing or development, by binding each instance to a different port. In production, distribute masters and replicas across separate physical or virtual machines, racks, and ideally availability zones.

What happens if I lose a majority of master nodes?

The cluster stops accepting writes. It needs a majority of masters to agree on failovers and configuration changes. This is a deliberate trade-off to prevent split-brain scenarios.

Is resharding online or does it require downtime?

Resharding is online. Redis migrates slots one by one while the cluster continues to serve traffic. Individual keys are briefly unavailable during their move, but the cluster as a whole stays up.

Do client libraries need special configuration for Cluster?

Yes. Standard Redis clients connect to one node. Cluster-aware clients (for example, Jedis with JedisCluster, Lettuce with RedisClusterClient) accept a list of seed nodes, maintain a slot map, and follow MOVED redirects automatically.