Redis and Valkeyadvanced

Redis Cluster

Hash slots, resharding, and the multi-key constraints that shape application code in a clustered Redis.

2 min readAdvancedUpdated 31 Jul 2026Edit this page

Redis Cluster distributes the keyspace across primaries using 16384 hash slots, with automatic failover and no separate coordinator process.

Redis Cluster hash slot distribution

Slots and key routing

The slot for a key is CRC16(key) mod 16384. Each primary owns a contiguous set of slots. Clients cache the slot map and connect directly to the owning node; if a slot has moved, the node replies MOVED and the client updates its map.

redis-cli --cluster create \
  10.20.1.10:6379 10.20.1.11:6379 10.20.1.12:6379 \
  10.20.1.20:6379 10.20.1.21:6379 10.20.1.22:6379 \
  --cluster-replicas 1

CLUSTER INFO
CLUSTER SHARDS
CLUSTER KEYSLOT shop:user:1001

Multi-key operations

Multi-key commands require all keys in one slot

MGET, MSET, SINTER, transactions and Lua scripts fail with a CROSSSLOT error if their keys span slots. This is the constraint that most affects application code when moving from a single instance to a cluster.

Use hash tags — only the substring inside {} is hashed:

{shop:user:1001}:profile
{shop:user:1001}:sessions

Both hash to the same slot and can be used together. Choose the tag carefully: everything sharing a tag lives on one node, so an over-broad tag such as {shop} puts the entire dataset on a single shard.

Failover

Each primary should have at least one replica. Nodes gossip; when a majority of primaries agree a node is failing, one of its replicas is promoted.

The cluster requires a majority of primaries to be reachable to remain available. With cluster-require-full-coverage yes (the default), the cluster stops serving all requests if any slot is uncovered. Setting it to no keeps the healthy slots serving while the affected range errors — usually the better behaviour for a cache.

Resharding

# Move 1000 slots to a new node.
redis-cli --cluster reshard 10.20.1.10:6379 \
  --cluster-from <source-node-id> \
  --cluster-to <target-node-id> \
  --cluster-slots 1000 --cluster-yes
 
# Even out slot distribution after adding nodes.
redis-cli --cluster rebalance 10.20.1.10:6379

Constraints to design around

One database only. SELECT is not supported in cluster mode; there is only database 0.
No cross-slot transactions or scripts.
SCAN is per node, so a full keyspace scan means iterating every primary.
Pub/Sub is broadcast cluster-wide unless you use sharded pub/sub (SPUBLISH).
Client libraries must be cluster-aware. A plain client will follow MOVED redirects poorly or not at all.

When you do not need it

Cluster exists to exceed one node's memory or throughput. If the dataset fits comfortably in one instance's RAM and one core can serve the command rate, a primary with replicas and Sentinel is simpler to operate and imposes none of the multi-key constraints above.