Redis Cluster (Hash Slots)

Data is sharded over 16384 hash slots owned by masters, each with replicas; clients follow MOVED/ASK redirections and multi-key commands must share a slot.

The problem

When the dataset or write rate no longer fits one node, you must shard. Redis Cluster splits the key space over many masters, each with replicas, and handles failover itself — with no proxy in the middle.

How it works

  • The key space is split into 16384 hash slots: `HASH_SLOT = CRC16(key) mod 16384`. Each master owns a subset of slots; a cluster has at most 16384 masters, and about 1000 is the recommended ceiling.
  • Hash tags: if a key contains `{...}`, only the text inside the braces is hashed, so `{user:1}:cart` and `{user:1}:profile` share a slot. Multi-key commands, transactions and Lua scripts work only when all keys are in one slot.
  • Clients are cluster-aware: they cache the slot map, and a node that does not own a slot answers `-MOVED slot host:port` (permanent: update the map) or `-ASK` (temporary, during migration).
  • Each node opens two ports: the client port (6379) and the cluster bus (port + 10000) used for gossip, failure detection and failover. Both must be reachable between nodes; NAT and port remapping are not supported.
  • Failure detection is by gossip: a master is failed when a majority of masters have seen it unreachable for `cluster-node-timeout`; one of its replicas is then elected by the masters and promoted.
  • Resharding moves slots between masters online (`redis-cli --cluster reshard`), using MIGRATING / IMPORTING and ASK redirections; replicas can migrate to masters left without any replica.
  • Replication between nodes is asynchronous and the winner of a failover wins (“last failover wins”): there are small windows where acknowledged writes are lost, and larger ones for clients stuck in a minority partition. After `cluster-node-timeout` the minority side stops accepting writes.
  • By default (`cluster-require-full-coverage yes`) the cluster stops serving if any slot has no owner; relax it only if partial availability is acceptable.

Examples

Create a 3-master, 3-replica cluster and inspect it; -c follows redirections.

bash
redis-cli --cluster create \
  10.0.0.1:6379 10.0.0.2:6379 10.0.0.3:6379 \
  10.0.0.4:6379 10.0.0.5:6379 10.0.0.6:6379 \
  --cluster-replicas 1

redis-cli -c -h 10.0.0.1 CLUSTER KEYSLOT '{user:1}:cart'
redis-cli -h 10.0.0.1 CLUSTER NODES
redis-cli --cluster check 10.0.0.1:6379

Per-node cluster settings.

properties
cluster-enabled yes
cluster-config-file nodes.conf
cluster-node-timeout 15000
cluster-require-full-coverage yes
appendonly yes

In practice

  • Large caches and session stores — Hash tags group related keys; the keyspace is spread evenly by CRC16 so hot shards are rare.
  • Cluster-aware clients — redis-py-cluster / redis-py, go-redis ClusterClient, Lettuce and Jedis cache the slot map and follow MOVED.
  • Managed services — ElastiCache and other clouds expose cluster mode with the same slot model and resharding.
  • Pitfall — A single hot key or a huge hash tag group lands on one node: hash slots balance keys, not load.

Trade-offs

Pros

  • Linear scale of memory and write throughput over masters
  • Built-in failover and resharding without a proxy or external coordinator
  • Continues serving while a majority of masters and a replica per failed master remain

Cons

  • Multi-key operations restricted to one slot; some commands unavailable across slots
  • Asynchronous replication: acknowledged writes can be lost, more so on the minority side of a partition
  • Operationally heavier: two ports per node, cluster-aware clients, careful resharding

← All Redis entries