Scaling Redis: Guide to Setting Up Redis Cluster

Redis Cluster helps when one Redis instance is no longer enough for your data size, traffic, or availability target. It shards keys across multiple primary nodes and can promote replicas when a primary fails.

This guide shows the current redis-cli --cluster workflow, a local six-node example, and the management commands you need after the cluster is running.

Understanding Redis Cluster Concepts

Redis Cluster is built around a few practical ideas:

• Sharding: Redis Cluster divides the keyspace into 16,384 hash slots. Each primary node owns a range of slots, and cluster-aware clients route commands to the node that owns the key's slot.
• Replication: Each primary can have one or more replicas. If a primary fails and the cluster can still reach quorum, a replica can be promoted.
• Cluster bus: Nodes talk to each other on the client port and a cluster bus port, usually the client port plus 10000. For port 7000, that means bus port 17000.
• Client support: Your application client must support Redis Cluster redirections such as MOVED and ASK. A non-cluster-aware client will behave badly once keys live on different nodes.

Prerequisites

For a production-style cluster, plan for at least six Redis nodes: three primaries and one replica for each primary. You can run the example below on one machine for practice, but production nodes should be spread across hosts or availability zones.

You also need Redis installed, redis-cli available, and network access between all nodes on both the Redis client ports and cluster bus ports. Use a currently supported Redis release when possible.

Setting Up a Redis Cluster Step by Step

This example uses six local Redis processes on ports 7000 through 7005.

1. Install Redis

On Debian or Ubuntu, the package install looks like this:

sudo apt update
sudo apt install redis-server

Package versions vary by distribution. If you need a newer Redis release, use the official Redis packages or your platform's managed Redis service.

2. Configure Redis Instances for Cluster Mode

Create one directory and configuration file per Redis process:

mkdir cluster
cd cluster

for port in 7000 7001 7002 7003 7004 7005; do
  mkdir "$port"
  cp /etc/redis/redis.conf "$port/redis.conf"
done

Edit each redis.conf and set the port-specific values. For 7000/redis.conf, use:

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

Repeat the same pattern for 7001 through 7005, changing both port and cluster-config-file. The nodes-7000.conf file is managed by Redis. Do not edit it by hand.

For remote servers, bind to the private network interface instead of 127.0.0.1, and secure access with firewalls, authentication, and TLS where supported by your Redis build or service.

3. Start Redis Instances

Start each instance with its own config:

for port in 7000 7001 7002 7003 7004 7005; do
  redis-server "$port/redis.conf"
done

If your package manager already runs a default Redis service on port 6379, keep it separate from this test cluster or stop it while you experiment.

4. Create the Cluster with redis-cli --cluster

Use redis-cli --cluster create to assign slots and replicas:

redis-cli --cluster create \
  127.0.0.1:7000 127.0.0.1:7001 127.0.0.1:7002 \
  127.0.0.1:7003 127.0.0.1:7004 127.0.0.1:7005 \
  --cluster-replicas 1

Redis will show the proposed slot layout and ask for confirmation. Type yes if the primary and replica placement looks right.

5. Verify the Cluster

Check the cluster from any node:

redis-cli -c -p 7000 CLUSTER INFO
redis-cli -c -p 7000 CLUSTER NODES
redis-cli --cluster check 127.0.0.1:7000

CLUSTER INFO should show cluster_state:ok. The -c flag tells redis-cli to follow cluster redirections, which is useful when you test commands against keys that belong to another node.

Try a basic write and read:

redis-cli -c -p 7000 SET user:1 "Ada"
redis-cli -c -p 7001 GET user:1

Even if the key belongs to a slot served by another node, a cluster-aware client can follow the redirect.

Adding Replicas to an Existing Cluster

If you already have a cluster and want to add a new replica, start a new Redis instance with cluster mode enabled. Then find the primary node ID:

redis-cli -p 7000 CLUSTER NODES

Add the new node as a replica of that primary:

redis-cli --cluster add-node \
  127.0.0.1:7006 127.0.0.1:7000 \
  --cluster-slave \
  --cluster-master-id <master_node_id>

The first address is the new node. The second address is any reachable node in the existing cluster. Replace <master_node_id> with the ID from CLUSTER NODES.

Managing the Cluster

Common management tasks include:

• Check health: redis-cli --cluster check 127.0.0.1:7000
• Add a primary: redis-cli --cluster add-node <new_host:port> <existing_host:port>
• Reshard slots: redis-cli --cluster reshard <existing_host:port>
• Remove a node: move slots away from the node first if it is a primary, then run redis-cli --cluster del-node <existing_host:port> <node_id>
• Manual failover test: run CLUSTER FAILOVER from a replica, not from the primary

Avoid moving slots manually with low-level commands unless you know the full migration sequence. The redis-cli --cluster helpers reduce the chance of leaving slots in an inconsistent state.

Best Practices for Redis Cluster

• Use at least six nodes: Three primaries and three replicas give the cluster room to tolerate a primary failure.
• Spread replicas across failure domains: Do not place a primary and its replica on the same host or availability zone when you can avoid it.
• Secure Redis: Do not expose Redis directly to untrusted networks. Use private networking, firewall rules, authentication, and TLS where available.
• Plan memory per primary: Redis Cluster shards keys, but each primary still needs enough memory for its assigned data, overhead, and growth.
• Use cluster-aware clients: Confirm your client library supports Redis Cluster before you cut traffic over.
• Monitor failover and slot balance: Track memory, latency, rejected connections, replication lag, and cluster state.

Takeaway

For a practical Redis Cluster, start with at least three primaries and one replica per primary, create the cluster with redis-cli --cluster create, and verify it with CLUSTER INFO plus redis-cli --cluster check. After that, your day-to-day work is monitoring memory, slot balance, failover behavior, and client compatibility.