Mastering Redis Clustering: A Comprehensive Guide

Redis, short for Remote Dictionary Server, is an open-source, in-memory data structure store that is used as a database, cache, and message broker. It supports a wide range of data structures, including strings, hashes, lists, sets, sorted sets, bitmaps, and others. One of the most important features of Redis is its ability to scale horizontally using clustering. This blog post will serve as a comprehensive guide to help you master Redis clustering, covering everything from the basics to advanced concepts, all while providing clear explanations and code examples to make the process beginner-friendly.

Introduction to Redis Clustering

Redis clustering is a distributed implementation of Redis that allows you to automatically partition your data across multiple Redis nodes. This feature not only improves the performance and fault tolerance of your Redis setup but also enables you to scale out your data storage horizontally. In this section, we'll discuss the fundamentals of Redis clustering, including its key components, architecture, and partitioning.

Redis Clustering Components

A Redis cluster consists of the following components:

  1. Nodes: These are individual Redis instances that store your data and participate in the cluster.
  2. Slots: Redis Cluster divides the key space into 16,384 slots (0-16,383). Each key is assigned to a slot based on its hash, and each slot is assigned to a specific node.
  3. Master nodes: Master nodes store the data and are responsible for serving read and write requests for their assigned slots.
  4. Replica nodes: Replica nodes store copies of the data from their associated master node and can serve read requests, providing fault tolerance and load balancing.

Redis Cluster Architecture

In a Redis cluster, each node is connected to every other node in the cluster using a TCP connection, and they all communicate using the Redis Cluster protocol. This protocol is used to propagate information about the cluster's state, detect failures, and rebalance the key space.

Nodes in a Redis cluster can take on two roles: master and replica. Master nodes hold a portion of the key space and are responsible for serving read and write requests for their assigned slots. Replica nodes, on the other hand, store copies of the data from their associated master node and can serve read requests, providing fault tolerance and load balancing.

Data Partitioning

Redis Cluster uses a hash slot-based partitioning scheme to distribute data evenly across the nodes. Each key is assigned to one of the 16,384 slots based on its hash, and each slot is assigned to a specific node. When a client wants to read or write a key, it first calculates the hash slot for the key and then sends the request to the node responsible for that slot.

Setting Up a Redis Cluster

Now that we have a basic understanding of Redis clustering, let's set up a simple Redis cluster with three master nodes and three replica nodes. We'll assume you already have Redis installed on your system. If not, please follow the official Redis installation guide to get started.

Configuring Redis Nodes

First, create six directories for the Redis nodes, three for the master nodes and three for the replica nodes:

$ mkdir -p redis-cluster/{master,replica}/{1,2,3}

Next, create a Redis configuration file for each node. In each directory, create a redis.conf file with the following content:

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

Replace the port 7000 line with the appropriate port number for each node, e.g., 7001, 7002, etc.

Starting Redis Nodes

Now, start each Redis nodeusing the respective configuration file:

$ redis-server ./redis-cluster/master/1/redis.conf $ redis-server ./redis-cluster/master/2/redis.conf $ redis-server ./redis-cluster/master/3/redis.conf $ redis-server ./redis-cluster/replica/1/redis.conf $ redis-server ./redis-cluster/replica/2/redis.conf $ redis-server ./redis-cluster/replica/3/redis.conf

Creating the Cluster

Once all nodes are up and running, use the redis-cli command-line tool to create the cluster:

$ redis-cli --cluster create --cluster-replicas 1

This command will create a cluster with the specified nodes, assigning one replica to each master node.

Working with Redis Cluster

Now that our Redis cluster is up and running, let's see how to interact with it using the redis-cli tool and a Python client library called redis-py-cluster.

Using redis-cli

To interact with the cluster using redis-cli, simply pass the --cluster option followed by the address of any node in the cluster:

$ redis-cli -c -h -p 7000

Now you can use Redis commands as usual. The redis-cli tool will automatically handle cluster redirections:

> set foo "bar" -> Redirected to slot [12182] located at OK > get foo -> Redirected to slot [12182] located at "bar"

Using redis-py-cluster

To interact with the Redis cluster using Python, you'll need to install the redis-py-cluster library:

$ pip install redis-py-cluster

Then you can use the StrictRedisCluster class to connect to the cluster and execute Redis commands:

from rediscluster import StrictRedisCluster startup_nodes = [{"host": "", "port": "7000"}] rc = StrictRedisCluster(startup_nodes=startup_nodes, decode_responses=True) rc.set("foo", "bar") print(rc.get("foo"))

This will output:


Cluster Resharding and Failover

Redis Cluster provides built-in support for resharding and automatic failover. In this section, we'll discuss how to perform these operations.


Resharding is the process of redistributing hash slots among the nodes in the cluster. You can use the redis-cli tool to perform resharding.

First, let's list the nodes in the cluster:

$ redis-cli -c -h -p 7000 cluster nodes

Note the node IDs of the nodes you want to move hash slots between. Then, use the redis-cli --cluster reshard command to initiate the resharding process:

$ redis-cli --cluster reshard

Follow the prompts to specify the source and target nodes and the number of hash slots to move.


Redis Cluster automatically detects node failures and promotes a replica to a masternode if a master node becomes unavailable. This process is called failover. In addition to automatic failover, you can also perform manual failover using the redis-cli tool.

To perform a manual failover, first connect to the replica node that you want to promote to a master:

$ redis-cli -h -p 7003

Then, use the CLUSTER FAILOVER command to initiate the failover process:


Once the failover is complete, the replica node will be promoted to a master node, and the original master node will be demoted to a replica. The cluster will then update its configuration to reflect the new node roles.


Q: Can I use Redis Cluster with a single node?

A: Yes, you can set up a Redis Cluster with a single node, which will act as both the master and replica. This configuration is not recommended for production environments, as it does not provide fault tolerance or horizontal scaling benefits.

Q: How does Redis Cluster handle network partitions?

A: Redis Cluster uses a majority-based approach to handle network partitions. If a majority of master nodes are reachable, the cluster continues to operate. If a majority is not reachable, the cluster stops accepting write requests to ensure data consistency.

Q: Can I use Redis Cluster with a client that does not support clustering?

A: Yes, you can use a proxy like Redis Cluster Proxy to translate requests from non-cluster-aware clients to Redis Cluster commands. The proxy will handle key hashing, redirections, and retries on behalf of the client.

Q: How do I monitor a Redis Cluster?

A: You can use the redis-cli tool or any other Redis monitoring solution to monitor individual nodes in the cluster. In addition, you can use the CLUSTER INFO and CLUSTER NODES commands to get information about the cluster's state and configuration.

Q: How do I back up a Redis Cluster?

A: To back up a Redis Cluster, you'll need to back up the RDB or AOF files from each node in the cluster. You can use the SAVE or BGSAVE commands to create RDB snapshots, or you can enable AOF persistence in the Redis configuration.

Sharing is caring

Did you like what Mehul Mohan wrote? Thank them for their work by sharing it on social media.


No comments so far

Leave a question/feedback and someone will get back to you