Set up Redis Cluster on VPS with horizontal sharding

Set Up Redis Cluster on VPS (Horizontal Sharding)

November 2026 · 10 min read

Redis Cluster is Redis's built-in distributed mode that automatically shards data across multiple nodes. Unlike Redis Sentinel, which provides high availability for a single dataset, Cluster performs true horizontal sharding — it divides the keyspace into 16,384 hash slots distributed evenly among master nodes. This lets you store datasets larger than the RAM of any single server.

The minimum Redis Cluster setup is 3 masters + 3 replicas (6 nodes). This configuration ensures automatic failover: when a master fails, its replica is promoted automatically. This guide walks through deploying a full 6-node cluster on a single VPS using different ports — ideal for development and testing — and covers the path to multi-server production clusters.

Prerequisites: a VPS with at least 2 GB RAM, Redis 5.0 or later installed, and firewall rules allowing ports 7000–7005 and the cluster bus ports 17000–17005.

Install Redis

# Ubuntu/Debian
sudo apt update && sudo apt install -y redis-server

# Verify version (must be >= 5.0)
redis-server --version

# Disable the default service — the cluster will use its own configs
sudo systemctl disable --now redis-server

Create Directories and Config Files for 6 Nodes

for port in 7000 7001 7002 7003 7004 7005; do
  sudo mkdir -p /etc/redis/cluster/${port}
  sudo tee /etc/redis/cluster/${port}/redis.conf > /dev/null <<EOF
port ${port}
bind 127.0.0.1
daemonize yes
logfile /var/log/redis/cluster-${port}.log
dir /var/lib/redis/cluster/${port}
cluster-enabled yes
cluster-config-file /etc/redis/cluster/${port}/nodes.conf
cluster-node-timeout 5000
appendonly yes
appendfilename "appendonly.aof"
EOF
  sudo mkdir -p /var/lib/redis/cluster/${port}
  sudo chown -R redis:redis /var/lib/redis/cluster/
done

sudo mkdir -p /var/log/redis
sudo chown redis:redis /var/log/redis

Start All 6 Redis Nodes

for port in 7000 7001 7002 7003 7004 7005; do
  redis-server /etc/redis/cluster/${port}/redis.conf
  echo "Started Redis on port ${port}"
done

# Verify all processes are running
ps aux | grep redis-server | grep -v grep

Bootstrap the Cluster

# --cluster-replicas 1 means 1 replica per master
# 3 masters + 3 replicas = 6 nodes total
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 --cluster-yes
Multi-server: For production, replace 127.0.0.1 with the actual IP of each server, e.g. 192.168.1.10:7000 192.168.1.11:7000 192.168.1.12:7000 .... Ensure ports 7000 and 17000 are reachable between servers in your firewall.

Open Firewall Ports

# UFW (for multi-server, replace 'any' with specific source IPs)
for port in 7000 7001 7002 7003 7004 7005; do
  sudo ufw allow ${port}/tcp
  sudo ufw allow $((port + 10000))/tcp   # cluster bus
done
sudo ufw reload

Test Read/Write Across Nodes

# Connect with -c flag to enable cluster mode (auto-follow MOVED redirects)
redis-cli -c -p 7000

# Write keys — Redis automatically redirects to the correct slot
SET user:1 "alice"
SET user:2 "bob"
SET session:abc "data"
GET user:1
GET session:abc

Verify Redis Cluster is Working Correctly

# 1. Check overall cluster health
redis-cli -p 7000 cluster info

# 2. List all nodes with their roles
redis-cli -p 7000 cluster nodes

# 3. Check slot distribution and consistency
redis-cli --cluster check 127.0.0.1:7000

# 4. Count keys across all nodes
for port in 7000 7001 7002 7003 7004 7005; do
  echo -n "Port ${port}: "
  redis-cli -p ${port} dbsize
done

# 5. Simulate failover (debug mode)
redis-cli -p 7000 debug sleep 30 &
sleep 2
redis-cli -p 7000 cluster info | grep cluster_state
Tip: A healthy cluster shows cluster_state:ok and cluster_slots_assigned:16384. If slots assigned is less than 16,384, some nodes haven't received their slot allocation yet.

Troubleshooting Common Issues

ERR This instance has cluster support disabled

Redis started without cluster-enabled yes in its config file, so cluster commands are rejected.

# Confirm the directive is present
grep "cluster-enabled" /etc/redis/cluster/7000/redis.conf

# If missing, add it and restart the node
echo "cluster-enabled yes" | sudo tee -a /etc/redis/cluster/7000/redis.conf
redis-cli -p 7000 shutdown nosave
redis-server /etc/redis/cluster/7000/redis.conf

CLUSTERDOWN Hash slot not served

A master node has gone down and no replica is available to take over, leaving some hash slots without an owner.

# See which nodes are marked as failed
redis-cli -p 7000 cluster nodes | grep fail

# Force a replica to take over as master
redis-cli -p 7003 cluster failover force

# Repair orphaned slots automatically
redis-cli --cluster fix 127.0.0.1:7000

MOVED errors with a non-cluster-aware client

Standard Redis clients that don't understand the cluster protocol receive MOVED redirects and fail silently or raise errors.

# Always use -c with redis-cli to follow redirects
redis-cli -c -p 7000 SET mykey "value"

# Python: use redis-py v4+ with RedisCluster
pip install "redis[hiredis]"
# from redis.cluster import RedisCluster
# rc = RedisCluster(host="127.0.0.1", port=7000)

Node cannot join cluster — connection refused on bus port

The cluster bus runs on port + 10000 and must be reachable between all nodes. A firewall blocking these ports prevents the cluster from forming.

# Check open ports
ss -tlnp | grep redis

# Test cluster bus connectivity
telnet 127.0.0.1 17000

# For multi-server: add announce settings to each node config
# cluster-announce-ip 1.2.3.4
# cluster-announce-port 7000
# cluster-announce-bus-port 17000

Uneven load — all keys landing on one node

When all keys share the same hash tag {...}, they map to the same slot and overload a single master.

# Check and rebalance slot distribution
redis-cli --cluster rebalance 127.0.0.1:7000

# Avoid hash tags unless you need keys co-located for MGET/transactions
# Without {}: each key hashes independently and distributes evenly
redis-cli -c -p 7000 SET "user:1:name" "alice"
redis-cli -c -p 7000 SET "user:2:name" "bob"

Frequently Asked Questions

How is Redis Cluster different from Redis Sentinel?

Sentinel provides high availability for a single Redis instance — it monitors master health, triggers failover, and notifies clients, but all data still lives on one master. Cluster provides horizontal sharding across multiple masters, each owning a subset of hash slots, with built-in replica failover. Use Sentinel when your dataset fits in one machine's RAM and you need HA; use Cluster when you need to scale beyond a single machine's RAM.

What is the minimum number of nodes required?

The absolute minimum is 3 master nodes (no replicas), but production clusters should use 3 masters + 3 replicas (6 nodes). Without replicas, any master failure makes its hash slots unavailable until the node is restored manually. Redis Cluster requires at least 3 masters because the cluster bus uses a quorum of more than half of all masters to detect failures.

Which clients support Redis Cluster natively?

All major Redis clients support cluster mode: Python uses redis-py v4+ with RedisCluster; Node.js uses ioredis; Go uses go-redis; Java uses Lettuce or Jedis. Always verify that you are using the cluster-aware class rather than the standard single-node class, as the APIs look identical but the standard class will not follow MOVED redirects.