So you want to build a Redis cluster

In this tutorial we will setup, configure, and test a redis cluster using redis 5.0.6 on CentOS7.

We are working under the impression that our redis cluster will be spread across three separate regions (let’s call those us-west, us-central, and us-east),
and we want to ensure high availability and data redundancy.

For a redis cluster we need a minimum of three nodes. To provide failover and redundancy, each node needs a replica. For our cluster we’ll have a total of six individual nodes, with three primary-replica pairs, distributed across three regions. To ensure resiliency, replica nodes should be in different regions than the primary nodes.

Here’s what our cluster will look like:

In our example, placement of the nodes are regionally significant. For this reason we define the replicas manually. The redis-cli command can create the entire cluster automatically, but won’t know our primary-replica preference of having a each replica in a different region than its primary.

We’ll break down the cluster creation to a few simple steps.

Step 1: install redis on all nodes

On Centos, redis can be installed with a simple yum command. If necessary, install epel-release and update yum. Execute the following:

sudo yum install epel-release
sudo yum update
sudo yum install redis

Step 2: create your redis configuration

The redis configuration file will define parameters used by redis, including the port, log file location, daemon mode, among others. Our configuration will live at /var/redis/redis.conf. The contents will include the following:

port 6379
cluster-enabled yes
cluster-config-file nodes.conf
cluster-node-timeout 5000
appendonly yes
protected-mode no
daemonize yes
supervised systemd
pidfile /var/run/redis.pid
loglevel notice
logfile /var/log/redis.log
dir  /var/redis/

Step 3: update systemd service file

For your redis systemd service file, make sure the ExecStart entry under [Service] points to the desired redis.config file. The systemd config should be located in /usr/lib/systemd/system/redis.service. Here’s how our looks:

[Service]
ExecStart=/usr/bin/redis-server /var/redis/redis.conf — supervised systemd

Step 4: start redis as a service

You can start redis with the following command:

sudo systemctl start redis

Let’s verify redis is running. We can do this with a redis-cli command. When running, a redis-cli ping will return a pong.

>redis-cli ping
PONG

Step 5: add your primary nodes

Once the redis service is running an all nodes, we’re ready to build the cluster. We do this with a redis-cli command. This command will build the cluster and define the hash slots for the nodes. Note, this only needs to be executed on one node. We have to specify the IP address and port for each node. For our cluster we’re using the default port of 6379 for all nodes. Here is what the command looks like:

>redis-cli --cluster create 192.168.2.1:6379 192.168.2.3:6379 192.168.2.5:6379

We can view the cluster with the redis-cli cluster nodes command. This will show all nodes, their role, and hash slot range. The output should similar to this example:

>redis-cli cluster nodes
1f723262064d6fba9806bf87fa26504c37404078 198.168.2.1:6379@16379 myself,master - 0 1570645338000 1 connected 0-5460
b9be273099b6a6e4142ede8f34b4a284206d6405 192.168.2.3:6379@16379 master - 0 1570645337922 2 connected 5461-10922
8bd97a21bc8a30e6ecda106db8dc647d59a49105 192.168.2.5:6379@16379 master - 0 1570645338920 3 connected 10923-16383

Step 6: add your replica nodes

Now that we have our primary nodes ready, we want to add the replicas, one per primary. We add these one at a time to ensure proper primary-replica paring. To add a replicate node, we use the redis-cli command and specify the master is it a replica of. See the example commands below:

>redis-cli -a <password> --cluster add-node 192.168.2.2:6379 192.168.2.1:6379 --cluster-slave --cluster-master-id 1f723262064d6fba9806bf87fa26504c37404078
>redis-cli -a <password> --cluster add-node 192.168.2.4:6379 192.168.2.3:6379 --cluster-slave --cluster-master-id b9be273099b6a6e4142ede8f34b4a284206d6405
>redis-cli -a <password> --cluster add-node 192.168.2.6:6379 192.168.2.5:6379 --cluster-slave --cluster-master-id 8bd97a21bc8a30e6ecda106db8dc647d59a49105

With the replicas now added, let’s check the cluster stats. We should see all six nodes listed in the command output.

>redis-cli cluster nodes
265eb2a03e57e871f99d4cb9898453fe1f2c29b2 192.168.2.4:6379@16379 slave b9be273099b6a6e4142ede8f34b4a284206d6405 0 1570650946074 2 connected
8bd97a21bc8a30e6ecda106db8dc647d59a49105 192.168.2.5:6379@16379 master - 0 1570650947681 3 connected 10923-16383
b9be273099b6a6e4142ede8f34b4a284206d6405 192.168.2.3:6379@16379 master - 0 1570650947085 2 connected 5461-10922
7c7b2dbf079f5c8a782c5fb2b02cbc1af7927a41 192.168.2.2:6379@16379 slave 1f723262064d6fba9806bf87fa26504c37404078 0 1570650948072 1 connected
1f723262064d6fba9806bf87fa26504c37404078 192.168.2.1:6379@16379 myself,master - 0 1570650946000 1 connected 0-5460
b16c319c49b75839cd27304ef82be34ff8ac8e91 192.168.2.6:6379@16379 slave 8bd97a21bc8a30e6ecda106db8dc647d59a49105 0 1570650947972 3 connected

The cluster is ready!

Step 7: test your cluster

The cluster can be tested via redis-cli commands. On any node, simply execute redis-cli -c to enter the redis cli. (be sure to use the -c option to set cluster mode for the cli) A key/value can be set with the set command. On another node, enter the cli and use the get command to retrieve the value set on the first node.