Migrating from

Redis to
Amazon ElastiCache
A step-by-step guide for migrating a Redis
instance to a fully managed Amazon
ElastiCache cluster

Steps:
1. Create a source Redis database in Amazon EC2 (Optional) 2

2. Create an ElastiCache database cluster 10

3. Migrate from an existing Redis instance to your ElastiCache instance 17

4. Complete the migration and clean up resources 24

1. Create a source Redis database in Amazon EC2 (Optional)

In this step, you will create a self-managed Redis database in Amazon EC2. This serves
as a source database for performing a migration to ElastiCache. You can use it to walk
through the steps required to perform a migration to ElastiCache.

If you already have a source Redis database that you want to migrate, you can skip
this step and move on to the next step. However, ensure your source Redis database is
ready for an online migration.

Specifically, check the following configurations:

• Redis cluster mode is disabled.

• Redis AUTH is disabled.

• Redis protected mode is set to no.

• Any bind configuration allows traffic from ElastiCache nodes.

• Redis commands have not been renamed.

• There is sufficient CPU and memory headroom to allow for the migration
process.

For additional details about preparing your source Redis instance for migration, see
the migration preparation documentation.

If you do need to create a source Redis database for the migration walkthrough,
navigate to the Amazon EC2 console. Choose Launch instance to start the Amazon
EC2 instance creation wizard.

Page 2
The first step in the Amazon EC2 instance creation wizard is to choose your Amazon
Machine Image, or AMI. Use the Amazon Linux 2 AMI with the default x86 architecture
by choosing Select.

On the next page, choose the instance type for your Amazon EC2 instance. For this
walkthrough, you can use the default t2.micro instance type, which falls in the
Amazon Web Services (AWS) Free Tier. Choose Review and Launch to continue.

Page 3
The next page shows the default options for the rest of your Amazon EC2 settings.
The default options are fine for this use case. Choose Launch to continue.

Page 4
After you choose Launch, choose a key pair to allow SSH access to your new Amazon
EC2 instance. From the dropdown, choose Create a new key pair to create a new key
pair for this walkthrough. Then name your key pair elasticache-migration and choose
Download Key Pair to download the key pair to your computer. Finally, choose
Launch Instances to create your instance.

Page 5
You should see a page confirming that your instance is launching. Choose View
Instances to see your Amazon EC2 instances.

Page 6
As your instance is initialized, it shows an Instance State of pending. Wait until the
Instance State shows running.

When the Instance State is running, you can SSH into your instance.

Page 7
Copy the IPv4 Public IP value for your instance, and then run the following
commands in your terminal to SSH into your instance.

chmod 600 /path/to/elasticache-migration.pem

ssh -i /path/to/elasticache-migration.pem ec2-user@<IPv4PublicIP>

Be sure to use the proper values for the path to your

elasticache-migration.pem file that you downloaded and use the correct IPv4
Public IP for your instance.

If you have difficulty connecting to your Amazon EC2 instance, see

Connecting to your Linux instance using SSH.

If you connected successfully, your terminal should look like the following.

To install Redis, run the following commands in your terminal.

sudo yum -y install gcc make

wget http://download.redis.io/releases/redis-5.0.6.tar.gz
tar xvzf redis-5.0.6.tar.gz
cd redis-5.0.6
make
sudo make install

Installing Redis takes a few minutes because the system downloads the Redis source
and compiles Redis for your machine.

After Redis has been compiled, start your Redis instance by running the following
command in your terminal.

Page 8
redis-server --daemonize yes --protected-mode no

Note: This is running with protected mode disabled only because it is for a
demonstration. In a production use case, you should not disable protected mode.

You should see output indicating that the Redis server is starting. You can test your
Redis server by running a ping command in your terminal.

redis-cli PING

This command should return a response of PONG.

If you get the PONG response, you have started your Redis server on your Amazon
EC2 instance.

Finally, load some sample data into your Redis instance to test the migration. In your
terminal, run the following command to insert 10 keys into Redis.

redis-cli DEBUG POPULATE 10 test 10000

You should see a response of OK in your terminal. This loads 10 keys into your Redis
instance. Each key has a prefix of test.

In this step, you created a self-managed source Redis database from which you can
test performing a migration to ElastiCache. In the next step, you will create a fully
managed Redis instance in ElastiCache.

Page 9
2. Create an ElastiCache database cluster

In this step, you will create an ElastiCache database cluster. This cluster is used as your
primary database after you copy your existing data into it by using ElastiCache online
migration.

To get started, navigate to the ElastiCache console. On the Redis page, choose
Create to create a new cluster.

In the ElastiCache cluster creation wizard, choose Redis as your Cluster engine. Do
not enable Cluster Mode because online migration does not work with Cluster Mode.

Give your Redis cluster a name and description, and choose the instance type for your
cluster nodes.

Page 10
In the Advanced Redis settings, create a subnet group for your Redis cluster. A subnet
group refers to a set of network subnets in your Amazon Virtual Private Cloud, or
Amazon VPC, where your Redis cluster is placed.

Page 11
In the Security section, use the same security group that you used for your source
Redis database on Amazon EC2. Do not enable encryption at rest or encryption in
transit because these are not supported during online migrations.

The other default settings work for this migration. Scroll to the bottom and choose
Create.

Page 12
After you choose Create, you should see your cluster in the ElastiCache dashboard. It
shows a Status of creating while it is initializing.

While you are waiting for your ElastiCache cluster, navigate to the Security Groups
section of the Amazon EC2 console. Find the security group that you used for your
Amazon EC2 instance and ElastiCache instance, and choose it.

Page 13
When looking at your security group details, choose Edit inbound rules.

Page 14
Add an additional inbound rule to your security group that allows TCP traffic on port
6379 for all instances in your security group. This allows your ElastiCache cluster to
access your self-managed Amazon EC2 instance.

Your screen should look like the following.

After you have added the rule, choose Save rules to confirm your changes.

Navigate back to the ElastiCache console. You should see the Redis cluster you
created. When this cluster has a Status of available, you are ready to move on to the
next step.

In this step, you created a fully managed Redis cluster using ElastiCache. You also

Page 15
updated the inbound rules in your security group to allow your ElastiCache nodes to
access your self-managed Redis instance on Amazon EC2.

In the next step, you will use ElastiCache to perform an online migration of your
existing data.

If you are using ElastiCache in production, it is best to use AWS CloudFormation to

manage your resources using principles of infrastructure as code, or IaC. You can create
an ElastiCache cluster, an ElastiCache subnet group, a security group, and the related
networking infrastructure in an AWS CloudFormation stack by creating this stack.

Page 16
3. Migrate from an existing Redis instance to your ElastiCache instance

In this step, you will perform an online migration of your Redis data from your existing,
self-managed Redis instance to your fully managed Redis instance on ElastiCache.

Online migration configures one of your ElastiCache nodes to be a replica for your
self-managed Redis cluster. When the replication is complete, you can switch your
application to use the ElastiCache instance directly and stop the migration.

Before you start your migration, you need the private IP address of your self-managed
Redis instance on Amazon EC2. Navigate to the Amazon EC2 console and find the
instance that is hosting your Redis cluster. Copy the Private IPs value and save it for
the next step.

Navigate to the ElastiCache console to begin your online migration. Choose your
ElastiCache cluster, and then choose Migrate Data from Endpoint in the Actions
dropdown.

Page 17
In the configuration window that is displayed, enter the private IP address of your
Amazon EC2 instance as the Source Redis Endpoint. Then choose Start Migration.

If you prefer to use the AWS Command Line Interface, or AWS CLI, to initiate an online
migration, you can use the start-migration command.

Page 18
aws elasticache start-migration \
--replication-group-id <replicationGroupId> \
--customer-node-endpoint-list ‘[
{
“Address”: “<privateIPOfEC2Instance>”,
“Port”: 6379
}
]’

Be sure to replace <replicationGroupId> and <privateIPOfEC2Instance>

with the values for your configuration.

As your Redis cluster starts the migration, it shows a Status of modifying to indicate it
is being added to your existing cluster.

After your ElastiCache cluster has successfully connected to your existing Redis
instance, you should see a Status of migrating.

There are a few ways you can check the status of your ElastiCache online migration.

First, you can look at the metrics for your primary node. Choose your ElastiCache
cluster, which should bring up the nodes for your cluster. Choose the primary node to
see the Amazon CloudWatch metrics for the node in the ElastiCache dashboard.

Page 19
Scroll to the Master Link Health Status chart. When the value for this chart is at 1,
your ElastiCache instance is caught up with replicating items from your self-managed
Redis instance.

A second way you can check the status of your ElastiCache online migration is to
connect to your ElastiCache instance itself.

Find the primary endpoint of your ElastiCache cluster in the ElastiCache console. Copy
the hostname but do not copy the port number at the end.

Page 20
If you are still connected to your self-managed Amazon EC2 instance via SSH, you can
use that instance to connect to your ElastiCache instance.

Type the following into your terminal while connected to that instance.

redis-cli -h <yourPrimaryEndpoint>

Be sure to replace <yourPrimaryEndpoint> with the hostname of your Redis

instance from the previous step. This connects you to your ElastiCache Redis instance.

Then run the following command while connected to the Redis instance.

KEYS *

You should see the 10 test keys you inserted into your self-managed Redis cluster.

The following is an image that shows the terminal output after you connect to your
Redis cluster and run the KEYS command.

If the online migration is not copying the keys to your fully managed ElastiCache
cluster, you can debug the process by choosing Events in the navigation pane.

Page 21
The Event page shows you information about your migration, including when it
started, when it completed, and if it failed. If your migration failed, this page includes
information about the failure.

Page 22
In this step, you started an online migration in ElastiCache to copy data from your
self-managed Redis instance in Amazon EC2 to your fully managed Redis cluster in
ElastiCache. This is a safe, reliable way to migrate your data to ElastiCache.

In the next step, you will complete the migration and clean up resources.

Page 23
4. Complete the migration and clean up resources

If you have followed all the steps in this lesson, you have created a new, fully
managed Redis cluster in ElastiCache and migrated your existing data from your
self-managed Redis instance to your new Redis cluster. In this final step, you will learn
the steps to complete your migration and clean up your resources.

When your initial migration is complete and all data is synced to your new Redis
cluster, you are ready to use your new Redis cluster in your application. In your
application, change the configuration to use your ElastiCache endpoint rather than
your existing Amazon EC2 instance.

You can find the Primary Endpoint for your ElastiCache cluster in the
ElastiCache console.

When you have switched the configuration to your new ElastiCache cluster and are
confident in the results, you can stop the migration from your existing Redis instance.

To do that, choose your ElastiCache cluster in the console, and then choose Stop Data
Migration in the Actions dropdown.

Page 24
This removes your ElastiCache node as a replica from your self-managed Redis cluster.

When your ElastiCache node has been removed as a replica, it shows a Status of
available.

Next, you can delete your Amazon EC2 instance that is hosting your self-managed
Redis instance. You should do this only when you are comfortable that the migration
has been successful and you no longer need your existing instance.

Navigate to the Amazon EC2 console. Choose your Amazon EC2 instance, and then
choose Instance State > Terminate from the Actions dropdown.

Page 25
If you were using the ElastiCache cluster only for this walkthrough, you can terminate
that also. Navigate to the ElastiCache console. Choose your ElastiCache cluster, and
then choose Delete in the Actions dropdown.

After a few minutes, your ElastiCache cluster should be deleted.

Page 26
In this step, you learned how to migrate your application to use your new, fully
managed Redis cluster. You also saw how to stop migration from your self-managed
Redis instance to your fully managed ElastiCache cluster, and how to delete your
self-managed Redis instance on Amazon EC2.

In this lesson, you migrated an existing, self-managed Redis instance running on

Amazon EC2 to a fully managed Redis cluster on ElastiCache. You used the
ElastiCache online migration operation to safely and reliably replicate your data to
your new cluster.

Page 27