Note:

Migrate Redis Cluster to Oracle Cloud Infrastructure Cache

Introduction

This tutorial provides a step-by-step process for migrating sharded Redis Cluster cache using the pyredis-dump tool. pyredis-dump is a Python-based tool designed to simplify the dumping and restoration of Redis data. The procedure applies to either of the following migration scenarios:

While this tutorial primarily focuses on migrating an on-premises Redis Cluster to OCI without a master-slave architecture, the same approach can also be applied to environments that use a Redis master-slave setup.

What is Redis?

What is Redis Cluster?

Redis Cluster provides high availability and horizontal scaling. It divides the data into shards, distributed across multiple nodes. Each shard has a primary node and replicas for fault tolerance. This allows Redis Cluster to handle larger datasets and higher write throughput.

The following image shows a 3-node cluster containing 3 nodes as primary (M1, M2 and M3) with each node having slave as (S1, S2 and S3). Slave configuration is optional to provide more high availability.

image

Redis Cluster does not use consistent hashing, but a different form of sharding where every key is conceptually part of what we call a hash slot. There are 16384 hash slots in Redis Cluster. Every node in a Redis Cluster is responsible for a subset of the hash slots, so for example you may have a cluster with 3 nodes, where:

What is OCI Cache?

image

Objectives

Prerequisites

Task 1: Set up Source Redis Cluster in an On-Premises Setup

  1. Configure on-premises hosts. Create three on-premises virtual machine (VM) or physical host using RHEL8.

    • Redis_Node1: 10.0.0.151
    • Redis_Node2: 10.0.0.164
    • Redis_Node3: 10.0.0.205

  2. Open port on all the nodes.

    Every Redis Cluster node requires 1 to 3 TCP connections open based on configuration. The normal Redis TCP port used to serve clients, for example 6379, plus the port obtained by adding 10000 to the data port, so 16379 for cluster and 26379 for Sentinel. Make sure you open all ports in your firewall, otherwise Redis cluster nodes will not be able to communicate. Run the following commands.

    $firewall-cmd --permanent --add-port=6379/tcp  ( For master/slave replication and clint connection)
$firewall-cmd --permanent --add-port=16379/tcp ( For Redis Cluster )
$firewall-cmd --reload

  3. Install Redis software on all the nodes. Run the following command to download latest Redis Community Edition 7.4 for RHEL8. Install the Redis software on all three nodes using root user.

    $mkdir /redis
$wget http://download.redis.io/redis-stable.tar.gz
$tar xvzf redis-stable.tar.gz
$cd redis-stable
$make redis-cli
$make BUILD_TLS=yes
$cp src/redis-cli /usr/local/bin/
$cp redis-server /usr/local/bin/
$redis-cli -v

  4. Prepare Redis configuration file on all the nodes.

    It is recommendeded to set up a three node Redis Cluster with at least one replica (slave) per master and Sentinel for high availability. In this example, we have created three node cluster without replicas. To configure a Redis Cluster, we have to prepare the cluster config file named redis.conf on all three nodes under /redis folder.

    $cd /redis

$vi redis.conf
port 6379
timeout 0
protected-mode no
tcp-keepalive 300
pidfile "/redis/redis-server.pid"
logfile "/redis/redis-server.log"
requirepass "pass123"
dbfilename "dump.rdb"
appendonly no
masterauth "pass123"
cluster-enabled yes
cluster-config-file /redis/nodes.conf
cluster-node-timeout 5000

  5. Start Redis server on all the nodes. Run the following command to start Redis server on all the three nodes.

    [root@instance-20250224-0709 redis]# redis-server
814355:C 16 Apr 2025 15:30:35.171 # WARNING Memory overcommit must be enabled! Without it, a background save or replication may fail under low memory condition. Being disabled, it can also cause failures without low memory condition, see https://github.com/jemalloc/jemalloc/issues/1328. To fix this issue add 'vm.overcommit_memory = 1' to /etc/sysctl.conf and then reboot or run the command 'sysctl vm.overcommit_memory=1' for this to take effect.
814355:C 16 Apr 2025 15:30:35.171 * oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo
814355:C 16 Apr 2025 15:30:35.171 * Redis version=7.4.2, bits=64, commit=00000000, modified=0, pid=814355, just started
814355:C 16 Apr 2025 15:30:35.171 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf
814355:M 16 Apr 2025 15:30:35.171 * Increased maximum number of open files to 10032 (it was originally set to 1024).
814355:M 16 Apr 2025 15:30:35.172 * monotonic clock: POSIX clock_gettime
               _._
         _.-``__ ''-._
      _.-``    `.  `_.  ''-._           Redis Community Edition
.-`` .-```.  ```\/    _.,_ ''-._     7.4.2 (00000000/0) 64 bit
(    '      ,       .-`  | `,    )     Running in standalone mode
|`-._`-...-` __...-.``-._|'` _.-'|     Port: 6379
|    `-._   `._    /     _.-'    |     PID: 814355
`-._    `-._  `-./  _.-'    _.-'
|`-._`-._    `-.__.-'    _.-'_.-'|
|    `-._`-._        _.-'_.-'    |           https://redis.io
`-._    `-._`-.__.-'_.-'    _.-'
|`-._`-._    `-.__.-'    _.-'_.-'|
|    `-._`-._        _.-'_.-'    |
`-._    `-._`-.__.-'_.-'    _.-'
      `-._    `-.__.-'    _.-'
         `-._        _.-'
            `-.__.-'

814355:M 16 Apr 2025 15:30:35.172 * Server initialized
814355:M 16 Apr 2025 15:30:35.173 * Loading RDB produced by version 7.4.2
814355:M 16 Apr 2025 15:30:35.173 * RDB age 9 seconds
814355:M 16 Apr 2025 15:30:35.173 * RDB memory usage when created 2.18 Mb
814355:M 16 Apr 2025 15:30:35.173 * Done loading RDB, keys loaded: 1, keys expired: 0.
814355:M 16 Apr 2025 15:30:35.173 * DB loaded from disk: 0.000 seconds
814355:M 16 Apr 2025 15:30:35.173 * Ready to accept connections tcp

    Starts Redis server using a specific configuration file, and runs it in the background.

    $redis-server /redis/redis.conf &

  6. Create Redis Cluster. To create a Redis Cluster from all three Redis servers started above, run the following command from Node1.

    # redis-cli --cluster create 10.0.0.151:6379 10.0.0.164:6379 10.0.0.205:6379 -a pass123

output:

>>> Performing hash slots allocation on 3 nodes...
Master[0] -> Slots 0 - 5460
Master[1] -> Slots 5461 - 10922
Master[2] -> Slots 10923 - 16383

M: a89cae61ea55xxxxxxxxxxx8ea31c70b0dc290 10.0.0.151:6379
   slots:[0-5460] (5461 slots) master
M: b914e2031ceaxxxxxxxxxxxa6d7d5d67fa748 10.0.0.164:6379
   slots:[5461-10922] (5462 slots) master
M: 9e71454df3f0cbexxxxxxxxxxx6ddc34177f7465 10.0.0.205:6379
   slots:[10923-16383] (5461 slots) master
[OK] All nodes agree about slots configuration.
>>> Check for open slots...
>>> Check slots coverage...
[OK] All 16384 slots covered.

    We can see the Shard Key for nodes:

    • Node-1 (10.0.0.151) 0-5460
    • Node-2 (10.0.0.164) 5461-10922
    • Node-3 (10.0.0.205) 10923-16383

  7. Connect to the Redis Cluster using Redis client utility and validate the cluster nodes.

    The Redis command line interface (also known as redis-cli) is a terminal program that sends commands to and reads replies from the Redis server. Redis-cli gets installed automatically as a part of the Redis installation.

    • Run the $redis-cli -a pass123 -p 6379 -c command to connect to local host.

    • Run the $redis-cli -a pass123 -p 6379 -h 10.0.0.151 -c command to connect from remote.

    127.0.0.1:6379> cluster nodes

b914e2031cea8bxxxxxxxxxxxe9a6d7d5d67fa748 10.0.0.164:6379@16379 master - 0 1740409776706 2 connected 5461-10922
a89cae61ea553420c7xxxxxxxxxxx8ea31c70b0dc290 10.0.0.151:6379@16379 myself,master - 0 1740409775000 1 connected 0-5460
9e71454df3f0cbvxxxxxxxxxxx46ddc34177f7465 10.0.0.205:6379@16379 master - 0 1740409776000 3 connected 10923-16383

127.0.0.1:6379>

  8. Perform Data Manipulation Language (DML) operation in the cluster.

    In a Redis Cluster environment, data (read/write operation) is automatically redirected to the appropriate node based on the hash slot derived from the shard key.

    $redis-cli -a pass123 -p 6379 -c

127.0.0.1:6379> ping
PONG

127.0.0.1:6379> set name Dharmesh
-> Redirected to slot [5798] located at 10.0.0.164:6379
OK

10.0.0.164:6379> set age 40
-> Redirected to slot [741] located at 10.0.0.151:6379
OK

10.0.0.151:6379> set gender M
-> Redirected to slot [15355] located at 10.0.0.205:6379
OK

127.0.0.1:6379> KEYS *
1) "name"
2) "age"
3) "gender"
>SAVE
10.0.0.205:6379> exit

    Save to ensure data persistence on a Redis Cluster under /redis/dump.rdb, you can use either Redis Database (RDB) snapshots or Append-Only Files (AOF). RDB creates snapshots of the in-memory database at specified intervals, while AOF records all write operations, allowing for reconstruction of the database in case of failure.

Task 2: Set up Target Redis Cluster in OCI Cache

  1. Log in to the OCI Console, navigate to Database, OCI Cache and click Clusters.

    image

  2. Select respective compartment and click Create Cluster.

  3. Select cluster Name, Create in compartment and OCI Cache engine version.

    image

  4. Select Cluster mode, Shard count, Node per Shard and Memory per node.

    image

  5. Select VCN and Subnet.

    image

  6. Review and click Create cluster.

    image

    Once OCI cluster provisioning is completed, it should look like the following image. We can see three cluster nodes and Private endpoint.

    image

Task 3: Create Connection to OCI Cache Cluster

OCI Cache is SaaS, there will not be a direct access to the Redis host. To connect to OCI Cache, we need to create a jump instance or OCI Bastion host on the public subnet for secure access to clusters within the same VCN and subnet.

image

Provision Bastion/Jump in OCI

  1. Go to the OCI Console, navigate to Identity & Security and click Bastions.

  2. Select compartment, VCN, subnet, CIDR block allowlist and click Create bastion.

    image

  3. Run the following command to install Redis on jump host.

    sudo su -
mkdir /redis
wget http://download.redis.io/redis-stable.tar.gz
tar xvzf redis-stable.tar.gz
cd redis-stable
make redis-cli
make BUILD_TLS=yes
cp src/redis-cli /usr/local/bin/
cp redis-server /usr/local/bin/
$redis-cli -v

  4. Connect to either of the cluster nodes from jump host and validate nodes.

    Connect Cluster Node1
$redis-cli -h aaantxkdlyarjuuzfc5qgic3xdbxxxxxxxxxxxo6aj65pokndqtnwa-1-1.redis.us-ashburn-1.oci.oraclecloud.com --tls -c

Connect Cluster Node2
$redis-cli -h aaantxkdlyarjuuzfc5qgic3xxxxxxxxxxxxa5vo6aj65pokndqtnwa-2-1.redis.us-ashburn-1.oci.oraclecloud.com --tls -c

Connect Cluster Node3
$redis-cli -h aaantxkdlyarjuuzfc5qgic3xxxxxxxxxxxfeaa5vo6aj65pokndqtnwa-3-1.redis.us-ashburn-1.oci.oraclecloud.com --tls -c


Validate OCI cluster Nodes:

> cluster nodes
b89bf86956a0ce19e6b4xxxxxxxxxxxcd41d0b78dd 10.0.15.21:6379@16379,aaantxkdlyarjuuzfc5qgicxxxxxxxxxxxvo6aj65pokndqtnwa-2-1.redis.us-ashburn-1.oci.oraclecloud.com master - 0 1740462307292 2 connected 5462-10922
ba2253bcdb56f2e5227xxxxxxxxxxx9672cb527eab 10.0.5.150:6379@16379,aaantxkdlyarjuuzfc5qgic3xdbxxxxxxxxxxxvo6aj65pokndqtnwa-3-1.redis.us-ashburn-1.oci.oraclecloud.com master - 0 1740462305276 0 connected 10923-16383
b59af7d22e86c5600xxxxxxxxxxxe17bf34ca5aab 10.0.61.100:6379@16379,aaantxkdlyarjuuzfc5qgicxxxxxxxxxxxa5vo6aj65pokndqtnwa-1-1.redis.us-ashburn-1.oci.oraclecloud.com myself,master - 0 1740462305000 1 connected 0-5461

    We can see the Shard Key:

    • Cluster-1 (1-1) 0-5461
    • Cluster-2 (2-1) 5462-10922
    • Cluster-3 (3-1) 5462-10922

Task 4: Migrate Data from On-Premises to OCI cluster using Pyredis-dump Utility

  1. Install pyredis-dump utility on the jump/bastion host.

    $cd /redis/
$yum install git
$git clone https://github.com/tkote/pyredis-dump.git
$cd /redis/pyredis-dump
$python -m pip install redis
$python3 pyredis-dump.py -h

  2. Check connection to the on-premises Redis cluster from jump/bastion host.

    [root@jump ~]# redis-cli -a pass123 -p 6379 -h 10.0.0.151 -c
Warning: Using a password with '-a' or '-u' option on the command line interface may not be safe.
10.0.0.151:6379>

[root@jump ~]# redis-cli -a pass123 -p 6379 -h 10.0.0.164 -c
Warning: Using a password with '-a' or '-u' option on the command line interface may not be safe.
10.0.0.164:6379>

[root@jump ~]# redis-cli -a pass123 -p 6379 -h 10.0.0.205 -c
Warning: Using a password with '-a' or '-u' option on the command line interface may not be safe.
10.0.0.205:6379>

  3. Export dump from the source cluster. Connect to each Redis master node from jump host and create a remote dump. Dump will be created on the jump host at the given location.

    1. Take dump from master Node1.

      # python3 pyredis-dump.py -H 10.0.0.151 dump -o /redis/dump/rdump1 -w pass123
dumping to '/redis/dump/rdump1'
connecting to {'db': 0, 'host': '10.0.0.151', 'port': 6379, 'ssl': None, 'password': 'pass123'}
1 keys, bulk_size: 1000, watch_keys: False
dumped 1 records
elapsed time: 0.399 seconds

    2. Take dump from master Node2.

      # python3 pyredis-dump.py -H 10.0.0.164 dump -o /redis/dump/rdump2 -w pass123
dumping to '/redis/dump/rdump2'
connecting to {'db': 0, 'host': '10.0.0.164', 'port': 6379, 'ssl': None, 'password': 'pass123'}
1 keys, bulk_size: 1000, watch_keys: False
dumped 1 records
elapsed time: 0.004 seconds

    3. Take dump from master Node3.

      # python3 pyredis-dump.py -H 10.0.0.205 dump -o /redis/dump/rdump3 -w pass123
dumping to '/redis/dump/rdump3'
connecting to {'db': 0, 'host': '10.0.0.205', 'port': 6379, 'ssl': None, 'password': 'pass123'}
1 keys, bulk_size: 1000, watch_keys: False
dumped 1 records
elapsed time: 0.006 seconds

  4. Before importing data, clean up the target cluster in OCI Cache and ensure there is no data in either of the cluster nodes.

    OCI Cluster Node1

# redis-cli -h aaantxkdlyarjuuzfc5qgic3xdbckjxxxxxxxxxxxaj65pokndqtnwa-1-1.redis.us-ashburn-1.oci.oraclecloud.com --tls
> flushall
OK

OCI Cluster Node2

# redis-cli -h aaantxkdlyarjuuzfc5qgic3xdbckjxxxxxxxxxxxj65pokndqtnwa-2-1.redis.us-ashburn-1.oci.oraclecloud.com --tls
> flushall
OK

OCI Cluster Node3

# redis-cli -h aaantxkdlyarjuuzfc5qgic3xdbckjkxxxxxxxxxxx6aj65pokndqtnwa-3-1.redis.us-ashburn-1.oci.oraclecloud.com --tls
> flushall
OK

  5. Import dump to target cluster in OCI Cache. Connect to each OCI cluster and import dump to respective cluster based on the shard Key of source and target. Export dump of master Node1 having shard key 0-5460 should be imported to master node1 of target cluster respectively.

    We need to import dump in the following steps, else it will fail.

    1. Import dump from Node1 to OCI Cluster1-1.

      # python3 pyredis-dump.py -S -H aaantxkdlyarjuuzfxxxxxxxxxxxk5bfeaa5vo6aj65pokndqtnwa-1-1.redis.us-ashburn-1.oci.oraclecloud.com restore -i /redis/dump/rdump1
restore from '/redis/dump/rdump1'
connecting to {'db': 0, 'host': 'aaantxkdlyarjuuzfcxxxxxxxxxxxkjk5bfeaa5vo6aj65pokndqtnwa-1-1.redis.us-ashburn-1.oci.oraclecloud.com', 'port': 6379, 'ssl': True}
restored 1 records
elapsed time: 0.023 seconds

    2. Import dump from Node2 to OCI Cluster2-1.

      # python3 pyredis-dump.py -S -H aaantxkdlyarjuuzfc5xxxxxxxxxxxfeaa5vo6aj65pokndqtnwa-2-1.redis.us-ashburn-1.oci.oraclecloud.com restore -i /redis/dump/rdump2
restore from '/redis/dump/rdump2'
connecting to {'db': 0, 'host': 'aaantxkdlyarjuuzfc5xxxxxxxxxxxk5bfeaa5vo6aj65pokndqtnwa-2-1.redis.us-ashburn-1.oci.oraclecloud.com', 'port': 6379, 'ssl': True}
restored 1 records
elapsed time: 0.024 seconds

    3. Import dump from Node3 to OCI Cluster3-1.

      # python3 pyredis-dump.py -S -H aaantxkdlyarjuuzfc5qgixxxxxxxxxxxfeaa5vo6aj65pokndqtnwa-3-1.redis.us-ashburn-1.oci.oraclecloud.com restore -i /redis/dump/rdump3
restore from '/redis/dump/rdump3'
connecting to {'db': 0, 'host': 'aaantxkdlyarjuuzfc5xxxxxxxxxxx5bfeaa5vo6aj65pokndqtnwa-3-1.redis.us-ashburn-1.oci.oraclecloud.com', 'port': 6379, 'ssl': True}
restored 1 records
elapsed time: 0.030 seconds
[root@instance-20250223-1032 pyredis-dump]#

  6. Validate data in OCI. After data is imported successfully on each cluster node, connect to any OCI cluster node and check data.

    Connect Cluster Node1
$redis-cli -h aaantxkdlyarjuuzfc5qgic3xdbckjk5bfxxxxxxxxxxx65pokndqtnwa-1-1.redis.us-ashburn-1.oci.oraclecloud.com --tls -c

6379> get name
-> Redirected to slot [5798] located at aaantxkdlyarjxxxxxxxxxxx3xdbckjk5bfeaa5vo6aj65pokndqtnwa-2-1.redis.us-ashburn-1.oci.oraclecloud.com:6379
"Dharmesh"

6379> get age
-> Redirected to slot [741] located at aaantxkdlyarjuuxxxxxxxxxxxbckjk5bfeaa5vo6aj65pokndqtnwa-1-1.redis.us-ashburn-1.oci.oraclecloud.com:6379
"40"

6379> get gender
-> Redirected to slot [15355] located at aaantxkdlyarjxxxxxxxxxxxxxdbckjk5bfeaa5vo6aj65pokndqtnwa-3-1.redis.us-ashburn-1.oci.oraclecloud.com:6379
"M"

6379>

Acknowledgments

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.