Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 42 ยท High Availability and Scaling

Redis Cluster and Sharding

Learn Redis Cluster: 16384 hash slots, CRC16 key hashing, hash tags, MOVED and ASK redirects, multi-key limits, resharding and client-side sharding.

Sentinel keeps one dataset available, but that dataset still has to fit in the memory of a single machine, and a single master still executes every write. When you outgrow that, you shard: split the keys over several masters so that each one owns a part of the data and handles a part of the traffic. Redis Cluster is the built-in way to do it, and it combines sharding with replication and automatic failover in one system, with no separate supervisor.

The design question is simple: given a key, which node holds it? Redis Cluster answers with a fixed, deterministic function that every client and every node can compute, so no central lookup service is needed. This lesson explains that function, the redirects that handle changes, the restrictions that sharding imposes, and when to avoid Cluster altogether.

Redis Cluster cannot run on this page, so the redis-cli and config snippets are read-only. The runnable examples are plain JavaScript stand-ins: the CRC16 and slot calculation is the real algorithm (so the numbers match a real cluster), while the router that follows redirects is a small model of the behaviour.

Keys map to slots

Key Example: user:1000.
CRC16 A checksum of the key name.
Slot CRC16 mod 16384, 0 to 16383.
1 / 2

Hash slots

The key space is divided into exactly 16384 hash slots. A key's slot is CRC16(key) mod 16384, where CRC16 is the XMODEM variant (polynomial 0x1021, start value 0). Each master node owns a set of slots, and a three-master cluster typically splits them into three consecutive ranges. A slot, not a key, is the unit that moves between nodes, which is what makes resharding manageable: moving slot 866 moves every key that hashes to 866.

Why 16384 and not more? The nodes gossip their slot ownership to each other as a bitmap, and 16384 bits are 2 KB per message, which keeps the cluster bus small, while still being plenty to balance a cluster of up to about 1000 masters.

You can ask a real cluster directly:

Text
127.0.0.1:7000> CLUSTER KEYSLOT foo
(integer) 12182
127.0.0.1:7000> CLUSTER NODES
127.0.0.1:7000> CLUSTER SHARDS

The first TryIt implements the algorithm itself. It also supports hash tags, explained next.

Hash tags and the multi-key limit

Commands that touch several keys (MGET, SINTER, transactions with MULTI, Lua scripts) can only run on one node, so all keys they touch must live in the same slot. A cluster refuses anything else with a CROSSSLOT error. Redis lets you control placement with a hash tag: if a key contains a {...} section, only the text between the first { and the first } after it is hashed, and only if that text is not empty. So {user:1000}:profile and {user:1000}:cart land in the same slot, while {}user or user{ are hashed as whole strings.

Hash tags are a trade-off. Putting too many keys under one tag creates a hot slot that one node must carry alone, and it can grow too big to move. Use a tag per entity (per user, per order), never one global tag.

JS CRC16, slots and hash tags

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The first number is the standard CRC16 test value, and foo landing in slot 12182 is the same number CLUSTER KEYSLOT foo returns on a real cluster. The two {user:1000} keys share one slot, which is what makes multi-key operations between them legal, and the last line shows that CRC16 spreads ordinary keys evenly.

MOVED, ASK and smart clients

A node that receives a command for a key it does not own does not forward it. It answers with a redirect and the client retries on the right node:

Text
127.0.0.1:7000> GET foo
(error) MOVED 12182 127.0.0.1:7002

MOVED slot host:port means "this slot permanently belongs to that node". A cluster-aware client (redis-cli -c, ioredis Cluster, redis-py RedisCluster, Lettuce, Jedis) reacts by updating its own slot table and retrying. After the first few redirects it sends each command straight to the right node, so redirects are rare in steady state. See Using Redis from Node.js, Python, PHP and Java for the driver side.

Moving slots between nodes, resharding, happens while the cluster serves traffic. While slot S moves from node A to node B, A is migrating and B is importing:

  • Keys of slot S that still live on A are answered normally by A.
  • For a key that has already been moved, A replies ASK S host:port (a one-time redirect). The client sends ASKING and then the command to B, which accepts it only because it is importing S. The client does not update its slot table, because the slot still officially belongs to A.
  • When every key has moved, ownership is switched, and from then on A answers MOVED.

You normally drive this with redis-cli --cluster reshard or --cluster rebalance, which run the CLUSTER SETSLOT and MIGRATE steps for you.

sequenceDiagram
    participant C as Client
    participant A as Node A (migrating)
    participant B as Node B (importing)
    C->>A: GET {hello}.a
    A-->>C: ASK 866 B
    C->>B: ASKING
    C->>B: GET {hello}.a
    B-->>C: value
    C->>A: GET {hello}.b
    A-->>C: value (not moved yet)

During migration, ASK is a one-time detour; the client keeps asking A first.

The second TryIt models three nodes, a client that caches slots, a MOVED after a slot has changed hands, an ASK during a migration and a CROSSSLOT error.

JS A cluster router with MOVED, ASK and CROSSSLOT

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Follow the trail of the first GET {hello}.a: A answers ASK, the client repeats it on B with ASKING, and B serves it. After the switch, the client's cached table is wrong for that slot, so one MOVED corrects it and the next call goes straight to B.

What changes when you shard

  • Only database 0. SELECT is not available in cluster mode.
  • Multi-key commands, transactions and scripts need one slot. Use hash tags to co-locate keys that must be used together, and accept that you cannot easily SUNION any two keys any more.
  • Replicas and failover are built in. Give every master at least one replica; a cluster needs a majority of masters to agree before it fails over, so use at least three masters. If a slot has no reachable owner, the cluster stops answering for it (cluster-require-full-coverage yes makes the whole cluster stop).
  • Two ports per node. The client port (for example 7000) and the cluster bus port, by default client port plus 10000, which must be open between nodes.
  • Creation: with cluster-enabled yes on each node, redis-cli --cluster create host1:7000 host2:7000 host3:7000 host4:7001 host5:7001 host6:7001 --cluster-replicas 1 assigns the slots and wires the replicas.

Client-side sharding as an alternative

You do not have to use Redis Cluster to shard. With client-side sharding, the application (or a proxy such as Envoy or Twemproxy) hashes the key and picks one of N independent Redis servers, often with consistent hashing so that adding a server remaps only a fraction of the keys. It is simple, works with any Redis, and each shard can be its own Sentinel group. The costs: the client owns the topology, resharding is manual (data has to be moved and keys remapped), and there is no built-in failover or rebalancing. Choose Cluster when you want those handled for you, client-side sharding when you need full control or a data model that Cluster's limits would break.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. How does Redis Cluster decide which node stores the key user:7?

    The slot is computed as CRC16(key) mod 16384, and the cluster maps slots to masters. Nobody needs a central lookup.
  2. 2. Which keys are guaranteed to be in the same slot?

    Only the text inside the first non-empty {...} is hashed, so both keys hash 'user:9'. An empty {} is ignored, so the whole key is hashed.
  3. 3. What is the difference between MOVED and ASK?

    After MOVED the client should remember the new owner. ASK only applies to this request, because the slot has not changed owners yet, and it must be preceded by ASKING.
  4. 4. What happens when MGET touches keys in two different slots on a cluster?

    A command executes on one node, so a multi-key command must target a single slot. Use hash tags to co-locate related keys.
  5. 5. Which is a real drawback of sharding with Redis Cluster?

    Cluster supports replication and has failover built in, but it has a single database and restricts multi-key commands, transactions and scripts to one slot.

Summary

  • Redis Cluster splits the key space into 16384 slots; the slot of a key is CRC16(key) mod 16384, and each master owns a range of slots.
  • Hash tags ({...}) make related keys share a slot, which multi-key commands, transactions and scripts require; do not put everything under one tag.
  • MOVED is a permanent redirect, ASK a one-time detour during resharding; cluster-aware clients cache the slot table and follow both.
  • Cluster has only database 0, needs at least three masters, and a second (bus) port per node.
  • Resharding moves slots with redis-cli --cluster reshard while the cluster stays online.
  • Client-side sharding is a simpler alternative when you want full control and can live without built-in failover.

Next, keeping all of this safe from attackers: Securing Redis.