Skip to main content

lessons

# Scaling with Redis Cluster

## Introduction

As the demands on your Redis deployment grow—whether due to increased data volume, higher throughput, or a need for greater fault tolerance—sharding your data across multiple Redis servers becomes essential. **Redis Cluster** is the native solution for horizontal scaling, enabling automatic partitioning and high availability without the need for external tools or proxy layers. In this lesson, you'll learn how Redis Cluster works, how to set it up, and how to use it effectively in production environments.

---

## What is Redis Cluster?

Redis Cluster is a distributed implementation of Redis that:

- Automatically splits your dataset among multiple nodes (shards)
- Provides built-in replication and failover
- Supports horizontal scaling (add/remove nodes as needed)
- Allows the system to remain available during certain failure scenarios

### Key Features

- **Sharding**: Data is automatically partitioned across nodes using hash slots.
- **Replication**: Each shard can have replicas for redundancy.
- **High Availability**: Automatic failover if a master node goes down.
- **No Single Point of Failure**: Cluster continues to operate with partial node failures (with limitations).

---

## Cluster Architecture & Hash Slots

### The Hash Slot Mechanism

Redis Cluster divides the keyspace into **16,384 hash slots**. Each master node in the cluster is responsible for a subset of these slots. When a client sends a command, the key is hashed to a slot, and the request is routed to the corresponding node.

#### How it Works

- **Key Hashing**: `HASH_SLOT = CRC16(key) % 16384`
- **Slot Assignment**: Each master node is assigned one or more slot ranges.
- **Data Routing**: Clients must be cluster-aware to route requests correctly.

**Example:**

Suppose you have 3 master nodes:

- Node A: slots 0–5460
- Node B: slots 5461–10922
- Node C: slots 10923–16383

A key hashed to slot 8000 would be stored on Node B.

---

## Setting Up a Redis Cluster

### Requirements

- Redis 3.0 or higher (Cluster support introduced in 3.0)
- At least **3 master nodes** (recommended minimum)
- For high availability: at least **3 replicas** (one per master)

### Example: Creating a 3-Node Cluster Locally

#### 1. Prepare Configuration Files

Each node needs a unique port and config file. Example for `redis-7000.conf`:

```ini
port 7000
cluster-enabled yes
cluster-config-file nodes-7000.conf
cluster-node-timeout 5000
appendonly yes

Copy and modify for ports 7001 and 7002.

2. Start Redis Servers​

redis-server redis-7000.conf
redis-server redis-7001.conf
redis-server redis-7002.conf

3. Create the Cluster​

Using the redis-cli cluster creation tool:

redis-cli --cluster create 127.0.0.1:7000 127.0.0.1:7001 127.0.0.1:7002 --cluster-replicas 0

You will be prompted to confirm. After confirmation, the cluster will be initialized.

Working with a Redis Cluster​

Connecting as a Client​

To interact with a cluster, clients must support cluster mode (e.g., redis-cli --cluster, Python's redis-py with RedisCluster).

Python Example:

from redis.cluster import RedisCluster

rc = RedisCluster(
    startup_nodes=[{"host": "127.0.0.1", "port": "7000"}],
    decode_responses=True
)

rc.set("user:1001", "alice")
print(rc.get("user:1001"))

Slot-Aware Operations​

Most commands work as usual, but multi-key commands must be restricted to keys in the same slot.

Incorrect:

MGET user:1001 user:2001
# Error: CROSSSLOT Keys in request don't hash to the same slot

Correct:

If you must do multi-key ops, use hash tags:

SET user:{group1}:1001 "alice"
SET user:{group1}:1002 "bob"
MGET user:{group1}:1001 user:{group1}:1002

All keys inside {group1} will hash to the same slot.

Adding and Removing Nodes​

Scaling Out: Adding a New Node​

Suppose you want to add a new master node (e.g., 127.0.0.1:7003):

  1. Start the new Redis server with cluster enabled.

  2. Add the node to the cluster:

    redis-cli --cluster add-node 127.0.0.1:7003 127.0.0.1:7000

  3. Rebalance slots:

    redis-cli --cluster rebalance 127.0.0.1:7000

Scaling In: Removing a Node​

  1. Migrate slots away from the node to be removed:

    redis-cli --cluster reshard 127.0.0.1:7000

  2. Remove the node:

    redis-cli --cluster del-node 127.0.0.1:7000 <node_id>

Use Cases for Redis Cluster​

  • High-traffic web applications: Distribute session/cache data across multiple servers to handle higher loads.
  • Large-scale analytics: Store and process massive datasets in-memory.
  • Gaming leaderboards: Support millions of users with low latency.
  • IoT data ingestion: Partition influx of sensor data by device or region.

Common Pitfalls and Best Practices​

Common Mistakes​

  • Non-Cluster-Aware Clients: Using a client that does not support cluster mode leads to errors.
  • Multi-Key Commands Across Slots: Attempting multi-key operations on keys in different slots causes CROSSSLOT errors.
  • Insufficient Masters/Replicas: Running with fewer than 3 masters or without replicas increases risk of data loss.
  • Manual Slot Assignment Errors: Incorrect slot assignment can lead to data unavailability.

Best Practices​

  • Always use cluster-aware clients.
  • Use hash tags ({}) for related multi-key operations.
  • Monitor cluster health regularly.
  • Plan for at least 3 master nodes and 1 replica per master.
  • Automate failover testing and disaster recovery drills.

Summary​

Redis Cluster enables Redis to scale horizontally by partitioning data across multiple nodes and providing high availability through built-in replication and failover. Proper understanding of hash slots, cluster-aware clients, and operational procedures is essential for running scalable and resilient Redis deployments.

Quiz​

  1. How many hash slots does Redis Cluster use, and why are they important?
    Answer: Redis Cluster uses 16,384 hash slots. They determine how keys are distributed (sharded) across the cluster nodes.

  2. What happens if you attempt a multi-key operation on keys that do not hash to the same slot?
    Answer: The operation fails with a CROSSSLOT error.

  3. What is a hash tag in Redis Cluster, and how is it used?
    Answer: A hash tag is a substring enclosed in curly braces (e.g., {group1}) within a key name. All keys with the same hash tag are mapped to the same slot, enabling multi-key operations.

  4. List one common pitfall when working with Redis Cluster.
    Answer: Using a non-cluster-aware client, which cannot properly route requests or handle redirections.

  5. How do you add a new master node to an existing Redis Cluster?
    Answer: Start the new Redis server with cluster enabled, use redis-cli --cluster add-node, and rebalance slots among the nodes.