A single Redis server is limited by one machine’s RAM and one main CPU thread for commands. Redis Cluster shards data across several master nodes, each with replicas for automatic failover. It’s the built-in way to scale Redis beyond one server. It also changes how your application uses Redis, so it’s worth understanding before you switch.

Do you need it?

Need Solution
Automatic failover, data fits one server Redis Sentinel (simpler). See Redis Sentinel
Data larger than one server’s RAM Redis Cluster
More write throughput than one server Redis Cluster
Just a cache that’s getting full First tune eviction and TTLs. See Redis maxmemory and eviction

Most applications are fine with one Redis server plus a replica and Sentinel.

How it works

  • The key space is divided into 16,384 hash slots. A key’s slot is CRC16(key) mod 16384.
  • Each master owns a range of slots, and each master can have replicas.
  • If a master fails, the other masters vote, and promote one of its replicas.
  • Clients talk to any node. If they ask the wrong one, the node replies MOVED <slot> <host:port>, and cluster-aware clients learn the slot map.

The minimum for a working cluster is 3 masters. With one replica each, that’s 6 nodes: on 3 to 6 servers.

Configure each node

# /etc/redis/redis.conf (each node)
port 6379
bind 0.0.0.0
protected-mode no
requirepass StrongClusterPass
masterauth StrongClusterPass
cluster-enabled yes
cluster-config-file nodes-6379.conf
cluster-node-timeout 5000
appendonly yes

Each node also uses a cluster bus port (data port + 10000, so 16379) for node-to-node communication. Open both ports only between the cluster nodes and your app servers, never to the internet:

sudo ufw allow from 10.0.0.0/24 to any port 6379,16379 proto tcp

See UFW firewall. A private network between the servers is ideal.

Create the cluster

With six nodes running (for example 3 servers, each with two Redis instances on ports 6379 and 6380):

redis-cli -a StrongClusterPass --cluster create \
  10.0.0.1:6379 10.0.0.2:6379 10.0.0.3:6379 \
  10.0.0.1:6380 10.0.0.2:6380 10.0.0.3:6380 \
  --cluster-replicas 1

Redis assigns slots to the masters, and tries to put each replica on a different host than its master. Check:

redis-cli -a StrongClusterPass -c -h 10.0.0.1 CLUSTER INFO
redis-cli -a StrongClusterPass -c -h 10.0.0.1 CLUSTER NODES
redis-cli -a StrongClusterPass --cluster check 10.0.0.1:6379

-c enables redirect-following in redis-cli.

Multi-key operations and hash tags

Commands touching several keys (MGET, MSET, transactions, Lua scripts, SUNION…) only work when all keys are in the same slot. Otherwise you get CROSSSLOT errors. Use hash tags: only the part inside {…} is hashed:

user:{42}:profile
user:{42}:cart
user:{42}:sessions     → all in the same slot

Design key names so data that’s used together shares a tag, but avoid putting too much under one tag, which creates hot slots.

Other limits: only database 0 (no SELECT), and KEYS or SCAN only cover one node at a time.

Clients must be cluster-aware

Use your library’s cluster mode:

from redis.cluster import RedisCluster
r = RedisCluster(host="10.0.0.1", port=6379, password="StrongClusterPass")
r.set("user:{42}:name", "Alice")
import { Cluster } from "ioredis";
const r = new Cluster([{ host: "10.0.0.1", port: 6379 }], { redisOptions: { password: "StrongClusterPass" } });

Most frameworks’ Redis integrations (session stores, cache backends, queues) support cluster mode, but check each one, especially for multi-key usage.

Failover and maintenance

  • Automatic failover: stop a master, and within about cluster-node-timeout a replica takes over. When the old master returns, it becomes a replica.
  • Manual failover (for maintenance): run CLUSTER FAILOVER on a replica.
  • Add a node: redis-cli --cluster add-node new:6379 existing:6379, then move slots with redis-cli --cluster rebalance or reshard. Slots move online.
  • If all copies of a slot are lost, the cluster stops accepting writes by default (cluster-require-full-coverage yes), to avoid partial data.

Persistence and backups

Each master holds part of the data, so back up every master (RDB snapshots or AOF). See Redis persistence: RDB and AOF.

Valkey

Valkey, the Linux Foundation fork of Redis, supports the same cluster protocol and commands, and is a drop-in alternative for self-hosted clusters.

Quick reference

Task Command
Enable cluster-enabled yes
Create redis-cli --cluster create … --cluster-replicas 1
Status CLUSTER INFO, CLUSTER NODES
Check redis-cli --cluster check host:port
Add node --cluster add-node, then rebalance
Same-slot keys Hash tags {…}
CLI with redirects redis-cli -c

Related: Redis as a cache and installing Redis on Ubuntu.

  • Redis
  • High Availability
  • Database