How to Set Up a Redis Cluster with Hash Slot Sharding and Automatic Failover on Ubuntu Server

ByAkensai

Learning how to set up a Redis Cluster with hash slot sharding and automatic failover on Ubuntu Server is one of the most valuable skills for any system administrator managing high-traffic applications. Redis Cluster distributes your data across multiple nodes using 16,384 hash slots. Each node owns a portion of those slots. When one node fails, a replica automatically takes over. This means your application stays online without manual intervention. In this tutorial, you’ll configure a six-node Redis Cluster , three primary nodes and three replicas , on Ubuntu Server 22.04. You’ll assign hash slot ranges, enable cluster mode, and verify automatic failover works correctly. By the end, you’ll have a production-ready Redis setup that handles both data sharding and node failures gracefully. This guide suits developers and server admins who want reliable, distributed caching or session storage at scale.

Prerequisites and Requirements for Your Redis Cluster Setup

Before you begin, make sure you have the following in place.

Hardware and software requirements:

  • Six Ubuntu Server 22.04 instances (or six separate ports on one server for testing)
  • Redis 7.x installed on each node
  • Root or sudo access on all nodes
  • Ports 6379–6384 and 16379–16384 open in your firewall
  • Basic familiarity with Linux terminal commands

Assumed knowledge: You should understand basic Redis concepts like keys, values, and persistence. You don’t need prior cluster experience.

Estimated time: 45–60 minutes.

For this tutorial, all six nodes run on a single Ubuntu server using ports 6379 through 6384. This mirrors a real multi-server cluster closely enough for learning. In production, spread nodes across separate physical or virtual machines. Check the official Redis Cluster documentation for production topology recommendations.

How to Set Up a Redis Cluster with Hash Slot Sharding on Ubuntu Server

See also: How to Configure Tls 1.3 with Strong Ciphers on Nginx for Production

Follow these steps carefully. Each step builds on the previous one.

Step 1: Install Redis on Ubuntu Server

Update your package list and install Redis.

sudo apt update
sudo apt install redis-server -y

Confirm the installation worked.

redis-server --version

You should see Redis 7.x or higher listed.

Step 2: Create Configuration Directories for Each Node

Create a separate directory for each of the six nodes.

sudo mkdir -p /etc/redis/cluster/{6379,6380,6381,6382,6383,6384}
sudo mkdir -p /var/lib/redis/cluster/{6379,6380,6381,6382,6383,6384}

Each node needs its own config file and data directory. Mixing them causes cluster errors.

Step 3: Write the Node Configuration Files

Create a config file for the first node. Then repeat for each port.

sudo nano /etc/redis/cluster/6379/redis.conf

Paste the following into that file:

port 6379
bind 127.0.0.1
cluster-enabled yes
cluster-config-file /etc/redis/cluster/6379/nodes.conf
cluster-node-timeout 5000
appendonly yes
appendfilename "appendonly.aof"
dir /var/lib/redis/cluster/6379
logfile /var/log/redis/cluster-6379.log
daemonize yes
pidfile /var/run/redis/redis-6379.pid

Now repeat this for ports 6380 through 6384. Replace every instance of 6379 with the correct port number in each file. You can use a quick loop to speed this up:

for port in 6380 6381 6382 6383 6384; do
  sudo cp /etc/redis/cluster/6379/redis.conf /etc/redis/cluster/$port/redis.conf
  sudo sed -i "s/6379/$port/g" /etc/redis/cluster/$port/redis.conf
done

Step 4: Start All Six Redis Nodes

Start each node using its config file.

for port in 6379 6380 6381 6382 6383 6384; do
  sudo redis-server /etc/redis/cluster/$port/redis.conf
done

Verify all nodes are running.

ps aux | grep redis-server

You should see six separate Redis processes listed.

Step 5: Create the Redis Cluster

Now create the cluster. This command assigns hash slots and links replicas to primaries.

redis-cli --cluster create 
  127.0.0.1:6379 127.0.0.1:6380 127.0.0.1:6381 
  127.0.0.1:6382 127.0.0.1:6383 127.0.0.1:6384 
  --cluster-replicas 1

Redis will propose a slot assignment. The first three nodes become primaries. Each gets roughly 5,461 hash slots. The last three become replicas. Type yes and press Enter to confirm.

Step 6: Verify the Cluster Status

Connect to any node and check the cluster info.

redis-cli -p 6379 cluster info

Look for cluster_state:ok and cluster_slots_assigned:16384. Both confirm your hash slot sharding is active and complete.

Check node roles with:

redis-cli -p 6379 cluster nodes

This lists all six nodes, their IDs, roles, and assigned slot ranges.

Step 7: Test Automatic Failover

Kill one primary node to trigger failover.

sudo kill $(cat /var/run/redis/redis-6379.pid)

Wait five seconds. Then check which node took over.

redis-cli -p 6380 cluster nodes

You’ll see the replica that was linked to port 6379 now shows as master. Automatic failover worked. Your cluster stayed online without any manual action.

Troubleshooting Common Redis Cluster Issues

Even with careful setup, problems come up. Here are the most common ones.

Problem: “CLUSTERDOWN” error when connecting
This means not enough nodes are reachable. Check that all six Redis processes are running with ps aux | grep redis. Restart any stopped nodes using their config files.

Problem: Cluster won’t form , “Waiting for the cluster to join”
This usually means firewall rules are blocking the cluster bus ports (16379–16384). Open them with:

sudo ufw allow 6379:6384/tcp
sudo ufw allow 16379:16384/tcp

Problem: Keys returning MOVED errors
This is normal behavior. Redis Cluster redirects requests to the correct node. Use redis-cli -c (cluster mode) instead of plain redis-cli. The -c flag handles redirects automatically.

Problem: Nodes show as “fail” after restart
Run redis-cli --cluster fix 127.0.0.1:6379 to repair the cluster state. This command re-evaluates slot ownership and clears stale failure flags.

Warning: Never run FLUSHALL on a cluster node in production. It only clears that node’s data. Your application will get inconsistent results across the cluster.

For deeper reference on cluster internals, visit the Redis Cluster specification page.

Conclusion: Your Redis Cluster Is Ready

You now know how to set up a Redis Cluster with hash slot sharding and automatic failover on Ubuntu Server. You installed Redis, configured six nodes, distributed hash slots across three primaries, and confirmed that replicas take over when a primary fails. That’s a solid foundation for any high-availability caching layer.

From here, consider adding Redis AUTH passwords to each node config for security. You should also look into monitoring your cluster with Redis Sentinel or Prometheus exporters. If you’re running WordPress, you can connect it to your cluster using the W3 Total Cache or Redis Object Cache plugin.

This setup scales well. Add more primary and replica pairs as your traffic grows. The hash slot model makes expansion straightforward without full data migrations.

Similar Posts