Redis Cluster Concepts

Redis Cluster is Redis’s built-in solution for horizontal scaling: instead of one instance holding your entire keyspace, the keyspace is split — sharded — across multiple master nodes, each responsible for a slice of the data. Each master can have one or more replicas for automatic failover, so a cluster gives you both more capacity and higher availability in a single deployment model. This lesson explains how sharding actually works under the hood, the commands you use to inspect a cluster, and the mistakes (especially around multi-key commands) that catch people off guard.

Overview / How it works

A standalone Redis instance keeps its whole keyspace in one process on one machine — great for simplicity, but your dataset and throughput are capped by that single node. Redis Cluster solves this by dividing the entire keyspace into 16384 hash slots. Every key is deterministically assigned to exactly one slot using CRC16(key) mod 16384 (or, if the key contains a {hash tag}, CRC16(hash tag) mod 16384 — more on that below). Each master node in the cluster owns a subset of those 16384 slots; together, all the masters cover the full range. A key’s slot never changes, but which node owns that slot can change over time as the cluster is resharded.

Nodes in a cluster talk to each other over a second port — the cluster bus, conventionally the client port plus 10000 (so port 6379 pairs with cluster bus port 16379) — using a binary gossip protocol. Through this gossip, every node eventually learns which slots every other node owns, and nodes detect failures by exchanging PING/PONG heartbeats and propagating suspicion when a node stops responding. When enough masters agree a node is down, and that node has a replica, the replica is automatically promoted — this is the cluster’s built-in failover, and it’s why Redis Cluster does not need a separate Sentinel deployment (Sentinel is for non-clustered replication setups instead).

Because Redis remains single-threaded for command execution even inside a cluster, each individual node still processes commands one at a time — atomicity for a command against a single key is untouched. What changes is that operations spanning multiple keys only work if all of those keys live in the same slot, because Redis Cluster does not do cross-node transactions or joins. If a client asks a node for a key it does not currently own, the node replies with a MOVED redirect telling the client which node actually owns that slot; during a live slot migration it may reply with ASK instead, meaning “temporarily ask that other node, this migration is in progress.” A cluster-aware client library follows these redirects transparently and caches the slot map so it usually talks to the right node on the first try — this lesson focuses on the concepts and the CLUSTER inspection commands you’ll use from redis-cli, since client-side cluster handling is covered in the client libraries section.

A production cluster needs a minimum of three masters (Redis refuses to form a cluster with fewer, since the failure-detection quorum logic needs it), and for real high availability, each master should have at least one replica — a six-node cluster (3 masters + 3 replicas) is the smallest sensible production topology.

Syntax

Cluster introspection and administration all live under the CLUSTER command family:

CLUSTER <subcommand> [arguments...]
CLUSTER KEYSLOT key
CLUSTER COUNTKEYSINSLOT slot
CLUSTER MEET ip port [cluster-bus-port]
CLUSTER ADDSLOTS slot [slot ...]
Subcommand Purpose Time complexity
CLUSTER INFO Cluster-wide state: enabled/disabled, size, slot coverage O(1)
CLUSTER MYID This node’s unique 40-character node ID O(1)
CLUSTER NODES Raw table of every known node and the slots it owns O(N), N = number of cluster nodes
CLUSTER SHARDS Slot ranges grouped by shard (master + its replicas) O(N), N = number of cluster shards
CLUSTER KEYSLOT key Which of the 16384 slots a given key hashes to O(N), N = key length
CLUSTER COUNTKEYSINSLOT slot How many keys the local node holds in a slot O(1)
CLUSTER ADDSLOTS / SETSLOT Cluster administration: slot assignment and migration O(N)

The commands that actually reshape a cluster (CLUSTER MEET, ADDSLOTS, SETSLOT, FAILOVER, RESET) require the target instance to be running with cluster mode enabled; on a standalone instance they return an error, which is why the examples below stick to the read-only inspection commands that work everywhere.

Examples

Example 1: Checking whether cluster mode is active. Even on a plain standalone server, CLUSTER INFO is always available and tells you the current cluster state:

CLUSTER INFO

Output:

cluster_enabled:0
cluster_state:ok
cluster_slots_assigned:0
cluster_slots_ok:0
cluster_slots_pfail:0
cluster_slots_fail:0
cluster_known_nodes:1
cluster_size:0
cluster_current_epoch:0
cluster_my_epoch:0
cluster_stats_messages_sent:0
cluster_stats_messages_received:0
total_cluster_links_buffer_limit_exceeded:0

cluster_enabled:0 means this particular instance is running in standalone mode — no slots are assigned and there’s only one known node (itself). On an actual cluster node, cluster_enabled would be 1, cluster_slots_assigned would climb toward 16384, and cluster_size would reflect the number of masters serving slots.

Example 2: Seeing how keys map to slots. CLUSTER KEYSLOT works regardless of whether cluster mode is on — it just runs the hashing algorithm and tells you the result, which is exactly what happens internally every time a cluster node routes a command:

CLUSTER KEYSLOT user:1000
CLUSTER KEYSLOT order:2000
CLUSTER KEYSLOT {user:1000}.profile
CLUSTER KEYSLOT {user:1000}.orders

Output:

(integer) 11695
(integer) 9438
(integer) 5474
(integer) 5474

(Your exact numbers may differ slightly depending on the CRC16 implementation details, but the pattern is what matters.) user:1000 and order:2000 land in different slots — on a real cluster they could easily live on different nodes. But {user:1000}.profile and {user:1000}.orders land in the same slot, because the curly braces mark a hash tag: when a key contains {...}, Redis hashes only the substring inside the braces, ignoring the rest of the key. This is the standard technique for guaranteeing that related keys for the same entity co-locate on one node, which is required for multi-key commands to work against them in a cluster.

Example 3 (illustrative — shown as reference output, not run against this test server): why cross-slot multi-key commands fail in a real cluster.

SET user:1000 "Ada Lovelace"
SET order:2000 "Widget"
MGET user:1000 order:2000

Output on an actual multi-node cluster:

OK
OK
(error) CROSSSLOT Keys in request don't hash to the same slot

Both SETs succeed individually — each is a single-key command routed to whichever node owns that key’s slot. But MGET asks for two keys in one command, and since user:1000 and order:2000 hash to different slots (as Example 2 showed), a cluster node refuses the request outright rather than silently fetching from two different nodes. The fix, if these two values genuinely need to be fetched together, is to give them a shared hash tag: {user:1000}.profile and {user:1000}.orders, so both are guaranteed to land in the same slot on the same node.

How it works step by step

  1. A client sends a command, e.g. GET user:1000, to any node it’s connected to.
  2. That node computes CRC16("user:1000") mod 16384 to determine the slot the key belongs to.
  3. The node checks its own slot-ownership table (kept up to date via gossip with every other node). If it owns that slot, it executes the command locally and replies as normal.
  4. If another node owns that slot, it replies with MOVED <slot> <ip>:<port>. A cluster-aware client follows the redirect, updates its local slot cache, and next time sends the command directly to the correct node.
  5. During a live resharding operation, the slot may be mid-migration between two nodes; the owning-so-far node can reply ASK to say “try the other node, but only for this one request” until migration completes.
  6. If a master stops responding to heartbeats, other masters gossip about the suspected failure; once a majority agrees, one of that master’s replicas is promoted automatically and the new topology propagates through the cluster via gossip.

Common Mistakes

Mistake 1 — running multi-key commands on unrelated keys and hitting CROSSSLOT. As shown above, MGET, MSET, transactions (MULTI/EXEC), and Lua scripts all require every key involved to share a slot in cluster mode. Wrong: designing keys like profile:1000 and orders:1000 and then trying to MGET them together. Fixed: use a shared hash tag, e.g. {1000}.profile and {1000}.orders, so CLUSTER KEYSLOT maps both to the same slot.

Mistake 2 — treating a cluster with no replicas as highly available. A cluster can technically run with only masters and zero replicas — it will pass the minimum-node check as long as there are at least three masters. But if a master with no replica goes down, its slots become completely unavailable (by default the whole cluster stops accepting writes until that’s resolved) and any data on it is lost until it recovers. Always pair every master with at least one replica in a real deployment.

Mistake 3 — using KEYS * or assuming a single DBSIZE reflects the whole cluster. Each node only knows about the slots (and therefore keys) it owns. Running KEYS * or DBSIZE against one node in a cluster only shows that node’s slice of the data, not the full dataset — and KEYS is still the blocking O(N) scan you should avoid in production regardless of cluster mode. Use SCAN per-node (cluster-aware tooling will iterate every node for you) instead.

Best Practices

  • Use hash tags ({tag}) deliberately to co-locate keys that must be accessed together with multi-key commands or transactions.
  • Always provision at least one replica per master shard; a masters-only cluster has no automatic failover for that shard’s data.
  • Use a cluster-aware client library (covered in the client libraries section) rather than hand-rolling MOVED/ASK redirect handling.
  • Monitor cluster_state from CLUSTER INFO — it must be ok; fail means some slots are currently unassigned or unreachable and the cluster may reject writes.
  • Plan slot ranges and resharding during low-traffic windows; migrating slots involves moving keys between nodes and adds latency to affected requests mid-migration.
  • Avoid designing workloads that need arbitrary cross-entity multi-key operations — Redis Cluster trades that flexibility for horizontal scale, so keep multi-key access patterns scoped to a single logical entity via hash tags.

Practice Exercises

  • Exercise 1: Using CLUSTER KEYSLOT, check whether cart:5001 and cart:5002 hash to the same slot. Then redesign the key names with a hash tag so that a future MGET across both would succeed in a real cluster.
  • Exercise 2: Run CLUSTER INFO against your local instance and identify from the output alone whether it is running in standalone or cluster mode, and how many nodes it currently knows about.
  • Exercise 3 (design, no commands needed): You’re planning a 3-master cluster for a workload that needs zero data loss on a single node failure. Decide how many total nodes you need and explain, from what this lesson covered about failover, what happens if one master’s replica is also down at the same time.

Summary

  • Redis Cluster shards the keyspace into 16384 fixed hash slots, distributed across master nodes.
  • A key’s slot is CRC16(key) mod 16384, or CRC16(hash tag) mod 16384 when the key contains a {hash tag}.
  • Nodes gossip over a separate cluster-bus port to share slot ownership and detect failures, triggering automatic replica promotion — no separate Sentinel needed.
  • Clients get redirected to the right node via MOVED (permanent) or ASK (mid-migration) replies.
  • Multi-key commands only work when every key involved shares a slot — use hash tags to guarantee that, or expect a CROSSSLOT error.
  • A production-ready cluster needs at least 3 masters, and every master should have at least one replica for real high availability.