A-9 — Redis Cluster: Hash Slots and Data Distribution

Why Cluster?

A single Redis node has two hard limits:

1. RAM — the entire dataset must fit in one machine's memory. A 1TB dataset cannot fit on a 256GB node.
2. Write throughput — all writes go through one single-threaded event loop. At some point, you hit the wall (~1M ops/sec on modern hardware).

Redis Cluster solves both by distributing data across multiple primary nodes, each responsible for a subset of the keyspace.

The Hash Slot Model

Redis Cluster partitions the keyspace into 16,384 hash slots (numbered 0–16383). Every key belongs to exactly one slot:

slot = CRC16(key) % 16384

Hash slots are assigned to primary nodes. A 3-node cluster might assign:

Node 1 (primary-1): slots 0–5460
Node 2 (primary-2): slots 5461–10922
Node 3 (primary-3): slots 10923–16383

When a client issues GET user:1001, Redis computes CRC16("user:1001") % 16384 = 7638. Slot 7638 belongs to Node 2. The client sends the GET to Node 2.

MOVED and ASK Redirections

Cluster clients must track which node owns which slots. When a client sends a command to the wrong node, the node responds with a MOVED redirection:

GET user:1001 → sent to Node 1 (wrong node)
Node 1 → -MOVED 7638 10.0.1.52:6379
          ↑ slot ↑ correct node address

The client updates its local slot-to-node map and resends the command to the correct node. A well-implemented Cluster client handles this automatically and transparently — application code does not see MOVED errors.

ASK redirections are similar but temporary — used during slot migration (when a slot is being moved from one node to another). ASK means "ask this specific node for this specific command, but do not update your slot map."

GET product:999 → slot being migrated
Node 1 → -ASK 12345 10.0.1.53:6379

Client: sends ASKING command to 10.0.1.53, then resends GET product:999
Note: ASKING is not stored; next request for slot 12345 still goes to Node 1
      until migration completes and a MOVED is issued

Hash Tags: Controlling Key Placement

Multi-key commands (MGET, MSET, pipelines, Lua scripts, transactions) require all keys to be on the same node. In Cluster mode, this means all keys must be in the same hash slot.

Hash tags force a specific portion of the key to be used for slot computation:

CRC16(key) % 16384   → uses the full key

# With hash tag {tag}: only the portion inside {} is hashed
CRC16(tag) % 16384

user:1001:profile  → CRC16("user:1001:profile") % 16384 = slot A
user:1001:session  → CRC16("user:1001:session") % 16384 = slot B (different!)

{user:1001}:profile → CRC16("user:1001") % 16384 = slot X
{user:1001}:session → CRC16("user:1001") % 16384 = slot X (same slot!)

With hash tags, all keys for a specific user share the same slot — enabling multi-key operations:

typescript
// Without hash tags: MGET fails in Cluster (keys on different slots)
redis.mget('user:1001:profile', 'user:1001:session')  // CROSSSLOT error

// With hash tags: MGET works (all keys on the same slot)
redis.mget('{user:1001}:profile', '{user:1001}:session')  // ✓

Design rule: For related keys that must be accessed together, use hash tags from the start. Retrofitting hash tags requires migrating all existing keys.

Multi-Key Command Constraints

Commands that operate on multiple keys fail in Cluster if the keys span different slots:

MGET key1 key2 key3    → CROSSSLOT error if keys are on different nodes
MSET key1 v key2 v     → CROSSSLOT error
RPOPLPUSH list1 list2  → CROSSSLOT error
SUNIONSTORE dest src1 src2  → CROSSSLOT error if different slots
Lua scripts via EVAL   → CROSSSLOT error if KEYS span different nodes
MULTI/EXEC transactions → keys must be on same slot

Workarounds:

1. Hash tags — co-locate related keys on the same slot
2. Application-side batching — split multi-key operations by slot, execute per-node, merge results in the application
3. Single-key alternatives — replace MGET with a pipeline of GET commands (each routed to the correct node automatically by the Cluster client)

typescript
// Replace MGET with a pipeline in Cluster (each GET routed correctly)
const pipeline = redis.pipeline();
['user:1001', 'user:1002', 'user:1003'].forEach(key => pipeline.get(key));
const results = await pipeline.exec();

Cluster Setup

A minimal production Cluster requires 6 nodes: 3 primaries + 3 replicas (one replica per primary).

bash
# Start 6 Redis instances with cluster mode enabled
# redis.conf for each:
cluster-enabled yes
cluster-config-file nodes.conf
cluster-node-timeout 5000    → ms to declare a node down (default 15000)

# Create the cluster (Redis 5.0+):
redis-cli --cluster create \
  10.0.1.1:6379 10.0.1.2:6379 10.0.1.3:6379 \
  10.0.1.4:6379 10.0.1.5:6379 10.0.1.6:6379 \
  --cluster-replicas 1

# Output will show slot distribution and ask for confirmation

Cluster-Aware Client: ioredis.Cluster

typescript
import { Cluster } from 'ioredis';

const redis = new Cluster([
  { host: '10.0.1.1', port: 6379 },
  { host: '10.0.1.2', port: 6379 },
  { host: '10.0.1.3', port: 6379 },
  // You only need to list some nodes — the client discovers the full topology
], {
  redisOptions: {
    password: process.env.REDIS_PASSWORD,
    commandTimeout: 500,
  },
  clusterRetryStrategy: (times) => Math.min(times * 100, 3000),
  scaleReads: 'slave',   // route reads to replicas
});

// Commands work transparently — MOVED redirects handled automatically
await redis.set('user:1001', 'data');
await redis.get('user:1001');

// Multi-key with hash tags
await redis.mget('{user:1001}:profile', '{user:1001}:session');

Cluster Node Commands

CLUSTER INFO              → cluster state, slot coverage, etc.
CLUSTER NODES             → full topology: node IDs, IPs, slots, roles
CLUSTER MYID              → this node's ID
CLUSTER KEYSLOT key       → compute the hash slot for a key
CLUSTER COUNTFAILUREREPORTS node-id
CLUSTER SLOTS             → slot-to-node mapping (deprecated; use CLUSTER SHARDS in 7.0+)
CLUSTER SHARDS            → (Redis 7.0+) slot ranges + node info

127.0.0.1:6379> CLUSTER INFO
cluster_enabled:1
cluster_state:ok                → 'fail' means cluster is in a degraded state
cluster_slots_assigned:16384    → all slots assigned
cluster_slots_ok:16384
cluster_slots_pfail:0           → slots where primary is probably down
cluster_slots_fail:0            → slots where primary is confirmed down
cluster_known_nodes:6
cluster_size:3                  → number of primaries
cluster_current_epoch:12

cluster_state:fail means at least one slot has no reachable primary — the cluster is refusing some or all write commands.

Automatic Failover in Cluster

Each primary in a Cluster has one or more replicas. When a primary fails, its replicas detect the failure via gossip (covered in A-11) and one replica promotes itself after a timeout:

cluster-node-timeout 5000   → if no PING response for 5s, node is considered down
# Failover completes in approximately 1-2× cluster-node-timeout

After failover, the new primary owns all slots previously owned by the failed node. If the failed primary had multiple replicas, only one promotes — the others continue replicating from the new primary.

If a primary fails with no available replica (the replica also failed), the cluster enters a cluster_state:fail state for those slots. No writes are accepted for the missing slots until the node recovers.

Limitations of Redis Cluster

No cross-slot operations: Multi-key commands must use hash tags. This is a design-time constraint — it requires forethought about which keys need to be co-located.

Limited database support: Cluster only uses database 0. The SELECT command is not available in Cluster.

Lua script constraints: EVAL scripts in Cluster must have all KEYS in the same slot. Multi-slot Lua scripts fail with CROSSSLOT. This limits some patterns that work fine on standalone Redis.

No blocking cross-node operations: BLPOP works per-node. If a producer pushes to a list on Node 1 and a consumer blocks on Node 2 (different slot), the consumer never wakes.

Complexity: Cluster adds operational complexity — monitoring multiple nodes, handling resharding, managing replica assignments. For most workloads that fit within a single node's capacity, Sentinel (with a single large primary) is operationally simpler.

When to Use Cluster

Use Cluster when:

• Dataset size exceeds available RAM on a single node
• Write throughput exceeds ~500K ops/second on a single node
• You need geographic distribution of data (Cluster with geo-aware routing)

Do not use Cluster when:

• Your dataset fits on a single node — Sentinel is simpler
• You rely heavily on multi-key commands without hash tag planning
• Your application uses SELECT to separate databases (not supported in Cluster)
• You use complex Lua scripts accessing multiple keys across slots

Summary

• Redis Cluster distributes 16,384 hash slots across primary nodes; slot = CRC16(key) % 16384
• MOVED redirections: permanent reroute to correct node; ASK redirections: temporary reroute during slot migration
• Hash tags {tag} force slot computation on the tag — co-locate related keys: {user:1001}:profile and {user:1001}:session share a slot
• Multi-key commands (MGET, MSET, Lua EVAL) require all keys on the same slot — use hash tags or application-side batching
• Minimal production Cluster: 3 primaries + 3 replicas (one replica per primary)
• Automatic failover when a primary fails — replica promotes after cluster-node-timeout; cluster enters fail state if no replica available
• ioredis.Cluster handles MOVED/ASK transparently; scaleReads: 'slave' routes reads to replicas
• Cluster limitations: no cross-slot ops without hash tags, only database 0, higher operational complexity than Sentinel

Next: A-10 — Resharding, Node Addition, and Live Slot Migration — adding nodes to a running cluster, migrating slots with zero downtime, and the ASKING redirection that enables live traffic during migration.