Getting started with MemoryDB
This exercise leads you through the steps to create, grant access to, connect to, and finally delete a MemoryDB cluster using the MemoryDB Management Console.
Note
For the purposes of this exercise, we recommend you use the Easy create option when creating a cluster and return to the other two options once you have further explored MemoryDB's features.
Topics
Step 1: Setting up
Following, you can find topics that describe the one-time actions you must take to start using MemoryDB.
Sign up for an Amazon Web Services account
If you do not have an Amazon Web Services account, use the following procedure to create one.
To sign up for Amazon Web Services
Open http://www.amazonaws.cn/
and choose Sign Up. Follow the on-screen instructions.
Amazon sends you a confirmation email after the sign-up process is
complete. At any time, you can view your current account activity and manage your account by
going to http://www.amazonaws.cn/
Secure IAM users
After you sign up for an Amazon Web Services account, safeguard your administrative user by turning on multi-factor authentication (MFA). For instructions, see Enable a virtual MFA device for an IAM user (console) in the IAM User Guide.
To give other users access to your Amazon Web Services account resources, create IAM users. To secure your IAM users, turn on MFA and only give the IAM users the permissions needed to perform their tasks.
For more information about creating and securing IAM users, see the following topics in the IAM User Guide:
Grant programmatic access
Users need programmatic access if they want to interact with Amazon outside of the Amazon Web Services Management Console. The Amazon APIs and the Amazon Command Line Interface require access keys. Whenever possible, create temporary credentials that consist of an access key ID, a secret access key, and a security token that indicates when the credentials expire.
To grant users programmatic access, choose one of the following options.
Which user needs programmatic access? | To | By |
---|---|---|
IAM | Use short-term credentials to sign programmatic requests to the Amazon CLI or Amazon APIs (directly or by using the Amazon SDKs). | Following the instructions in Using temporary credentials with Amazon resources in the IAM User Guide. |
IAM | (Not recommended) Use long-term credentials to sign programmatic requests to the Amazon CLI or Amazon APIs (directly or by using the Amazon SDKs). |
Following the instructions in Managing access keys for IAM users in the IAM User Guide. |
Related topics:
What is IAM in the IAM User Guide.
Amazon Security Credentials in Amazon General Reference.
Set up your permissions (new MemoryDB users only)
To provide access, add permissions to your users, groups, or roles:
-
Users managed in IAM through an identity provider:
Create a role for identity federation. Follow the instructions in Create a role for a third-party identity provider (federation) in the IAM User Guide.
-
IAM users:
-
Create a role that your user can assume. Follow the instructions in Create a role for an IAM user in the IAM User Guide.
-
(Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in Adding permissions to a user (console) in the IAM User Guide.
-
MemoryDB creates and uses service-linked roles to provision resources and access other
Amazon resources and services on your behalf. For MemoryDB to create a service-linked role
for you, use the Amazon-managed policy named AmazonMemoryDBFullAccess
. This
role comes preprovisioned with permission that the service requires to create a
service-linked role on your behalf.
You might decide not to use the default policy and instead to use a custom-managed policy.
In this case, make sure that you have either permissions to call
iam:createServiceLinkedRole
or that you have created the MemoryDB
service-linked role.
For more information, see the following:
Downloading and Configuring the Amazon CLI
The Amazon CLI is available at http://aws.amazon.com/cli
Go to the Amazon Command Line Interface User Guide.
Follow the instructions for Installing the Amazon CLI and Configuring the Amazon CLI.
Step 2: Create a cluster
Before creating a cluster for production use, you obviously need to consider how you will configure the cluster to meet your business needs. Those issues are addressed in the Preparing a cluster section. For the purposes of this Getting Started exercise, you can accept the default configuration values where they apply.
The cluster you create will be live, and not running in a sandbox. You will
incur the standard MemoryDB usage fees for the instance until you delete it. The total
charges will be minimal (typically less than a dollar) if you complete the exercise
described here in one sitting and delete your cluster when you are finished. For more
information about MemoryDB usage rates, see MemoryDB
Your cluster is launched in a virtual private cloud (VPC) based on the Amazon VPC service.
Creating a MemoryDB cluster
The following examples show how to create a cluster using the Amazon Web Services Management Console, Amazon CLI and MemoryDB API.
To create a cluster using the MemoryDB console
-
Sign in to the Amazon Web Services Management Console and open the MemoryDB console at https://console.amazonaws.cn/memorydb/
. -
Choose Clusters In the left navigation pane and then choose Create.
To create a cluster using the Amazon CLI, see create-cluster
. The following is an example:
For Linux, OS X, or Unix:
aws memorydb create-cluster \ --cluster-name my-cluster \ --node-type db.r6g.large \ --acl-name my-acl \ --engine valkey \ --subnet-group my-sg
For Windows:
aws memorydb create-cluster ^ --cluster-name my-cluster ^ --node-type db.r6g.large ^ --acl-name my-acl ^ --engine valkey --subnet-group my-sg
You should get the following JSON response:
{ "Cluster": { "Name": "my-cluster", "Status": "creating", "NumberOfShards": 1, "AvailabilityMode": "MultiAZ", "ClusterEndpoint": { "Port": 6379 }, "NodeType": "db.r6g.large", "EngineVersion": "7.2", "EnginePatchVersion": "7.2.6", "ParameterGroupName": "default.memorydb-valkey7", "Engine": "valkey" "ParameterGroupStatus": "in-sync", "SubnetGroupName": "my-sg", "TLSEnabled": true, "ARN":
"arn:aws:memorydb:us-east-1:xxxxxxxxxxxxxx:cluster/my-cluster"
, "SnapshotRetentionLimit": 0, "MaintenanceWindow": "wed:03:00-wed:04:00", "SnapshotWindow": "04:30-05:30", "ACLName": "my-acl", "DataTiering": "false", "AutoMinorVersionUpgrade": true } }
You can begin using the cluster once its status changes to available
.
Important
As soon as your cluster becomes available, you're billed for each hour or partial hour that the cluster is active, even if you're not actively using it. To stop incurring charges for this cluster, you must delete it. See Step 5: Deleting a cluster.
To create a cluster using the MemoryDB API, use the CreateCluster action.
Important
As soon as your cluster becomes available, you're billed for each hour or partial hour that the cluster is active, even if you're not using it. To stop incurring charges for this cluster, you must delete it. See Step 5: Deleting a cluster.
Setting up authentication
For information about setting up authentication for your cluster, see Authenticating with IAM and Authenticating users with Access Control Lists (ACLs).
Step 3: Authorize access to the cluster
This section assumes that you are familiar with launching and connecting to Amazon EC2 instances. For more information, see the Amazon EC2 Getting Started Guide.
MemoryDB clusters are designed to be accessed from an Amazon EC2 instance. They can also be accessed by containerized or serverless applications running in Amazon Elastic Container Service or Amazon Lambda. The most common scenario is to access a MemoryDB cluster from an Amazon EC2 instance in the same Amazon Virtual Private Cloud (Amazon VPC), which will be the case for this exercise.
Before you can connect to a cluster from an EC2 instance, you must authorize the EC2 instance to access the cluster.
The most common use case is when an application deployed on an EC2 instance needs to connect to a cluster in the same VPC. The simplest way to manage access between EC2 instances and clusters in the same VPC is to do the following:
-
Create a VPC security group for your cluster. This security group can be used to restrict access to the clusters. For example, you can create a custom rule for this security group that allows TCP access using the port you assigned to the cluster when you created it and an IP address you will use to access the cluster.
The default port for MemoryDB clusters is
6379
. -
Create a VPC security group for your EC2 instances (web and application servers). This security group can, if needed, allow access to the EC2 instance from the Internet via the VPC's routing table. For example, you can set rules on this security group to allow TCP access to the EC2 instance over port 22.
-
Create custom rules in the security group for your cluster that allow connections from the security group you created for your EC2 instances. This would allow any member of the security group to access the clusters.
To create a rule in a VPC security group that allows connections from another security group
-
Sign in to the Amazon Management Console and open the Amazon VPC console at https://console.aws.amazon.com/vpc
. -
In the left navigation pane, choose Security Groups.
-
Select or create a security group that you will use for your clusters. Under Inbound Rules, select Edit Inbound Rules and then select Add Rule. This security group will allow access to members of another security group.
-
From Type choose Custom TCP Rule.
-
For Port Range, specify the port you used when you created your cluster.
The default port for MemoryDB clusters is
6379
. -
In the Source box, start typing the ID of the security group. From the list select the security group you will use for your Amazon EC2 instances.
-
-
Choose Save when you finish.
Once you have enabled access, you are now ready to connect to the cluster, as discussed in the next section.
For information on accessing your MemoryDB cluster from a different Amazon VPC, a different Amazon Region, or even your corporate network, see the following:
Step 4: Connect to the cluster
Before you continue, complete Step 3: Authorize access to the cluster.
This section assumes that you've created an Amazon EC2 instance and can connect to it. For instructions on how to do this, see the Amazon EC2 Getting Started Guide.
An Amazon EC2 instance can connect to a cluster only if you have authorized it to do so.
Find your cluster endpoint
When your cluster is in the available state and you've authorized access to it, you can log in to an Amazon EC2 instance and connect to the cluster. To do so, you must first determine the endpoint.
To further explore how to find your endpoints, see the following:
Connect to a MemoryDB cluster (Linux)
Now that you have the endpoint you need, you can log in to an EC2 instance and connect to the cluster. In the following example, you use the cli utility to connect to a cluster using Ubuntu 22. The latest version of cli also supports SSL/TLS for connecting encryption/authentication enabled clusters.
Connecting to MemoryDB nodes using redis-cli
To access data from MemoryDB nodes, you use clients that work with Secure Socket Layer (SSL). You can also use redis-cli with TLS/SSL on Amazon Linux and Amazon Linux 2.
To use redis-cli to connect to a MemoryDB cluster on Amazon Linux 2 or Amazon Linux
Download and compile the redis-cli utility. This utility is included in the Redis OSS software distribution.
At the command prompt of your EC2 instance, type the appropriate commands for the version of Linux you are using.
Amazon Linux 2023
If using Amazon Linux 2023, enter this:
sudo yum install redis6 -y
Then type the following command, substituting the endpoint of your cluster and port for what is shown in this example.
redis-cli -h
Primary or Configuration Endpoint
--tls -p 6379For more information on finding the endpoint, see Find your Node Endpoints.
Amazon Linux 2
If using Amazon Linux 2, enter this:
sudo yum -y install openssl-devel gcc wget https://download.redis.io/releases/redis-7.2.5.tar.gz tar xvzf redis-7.2.5.tar.gz cd redis-7.2.5 make distclean make redis-cli BUILD_TLS=yes sudo install -m 755 src/redis-cli /usr/local/bin/
Amazon Linux
If using Amazon Linux, enter this:
sudo yum install gcc jemalloc-devel openssl-devel tcl tcl-devel clang wget wget https://download.redis.io/releases/redis-7.2.5.tar.gz tar xvzf redis-7.2.5.tar.gz cd redis-7.2.5 make redis-cli CC=clang BUILD_TLS=yes sudo install -m 755 src/redis-cli /usr/local/bin/
On Amazon Linux, you may also need to run the following additional steps:
sudo yum install clang CC=clang make sudo make install
After you have downloaded and installed the redis-cli utility, it is recommended that you run the optional
make-test
command.-
To connect to a cluster with encryption and authentication enabled, enter this command:
redis-cli -h
Primary or Configuration Endpoint
--tls -a'your-password'
-p 6379Note
If you install redis6 on Amazon Linux 2023, you can now use the command
redis6-cli
instead ofredis-cli
:redis6-cli -h Primary or Configuration Endpoint --tls -p 6379
Step 5: Deleting a cluster
As long as a cluster is in the available state, you are being charged for it, whether or not you are actively using it. To stop incurring charges, delete the cluster.
Warning
When you delete a MemoryDB cluster, your manual snapshots are retained. You can also create a final snapshot before the cluster is deleted. Automatic snapshots are not retained. For more information, see Snapshot and restore .
CreateSnapshot
permission is required to create a final snapshot. Without this permission, the API call will fail with anAccess Denied
exception.
The following procedure deletes a single cluster from your deployment. To delete multiple clusters, repeat the procedure for each cluster that you want to delete. You do not need to wait for one cluster to finish deleting before starting the procedure to delete another cluster.
To delete a cluster
-
Sign in to the Amazon Web Services Management Console and open the MemoryDB console at https://console.amazonaws.cn/memorydb/
. -
To choose the cluster to delete, choose the radio button next to the cluster's name from the list of clusters. In this case, the name of the cluster you created at Step 2: Create a cluster.
-
For Actions, choose Delete.
-
First choose whether to create a snapshot of the cluster before deleting it and then enter
delete
in the confirmation box and Delete to delete the cluster, or choose Cancel to keep the cluster.If you chose Delete, the status of the cluster changes to deleting.
As soon as your cluster is no longer listed in the list of clusters, you stop incurring charges for it.
The following code deletes the cluster my-cluster
. In this case, substitute my-cluster
with the
name of the cluster you created at Step 2: Create a cluster.
aws memorydb delete-cluster --cluster-name
my-cluster
The delete-cluster
CLI operation only deletes one cluster. To delete
multiple clusters, call delete-cluster
for each cluster that you want to delete. You do not need to wait for one cluster to
finish deleting before deleting another.
For Linux, OS X, or Unix:
aws memorydb delete-cluster \ --cluster-name
my-cluster
\ --regionus-east-1
For Windows:
aws memorydb delete-cluster ^ --cluster-name
my-cluster
^ --regionus-east-1
For more information, see delete-cluster
.
The following code deletes the cluster my-cluster
. In this case, substitute my-cluster
with the
name of the cluster you created at Step 2: Create a cluster.
https://memory-db.us-east-1.amazonaws.com/ ?Action=DeleteCluster &ClusterName=my-cluster &Region=us-east-1 &SignatureVersion=4 &SignatureMethod=HmacSHA256 &Timestamp=20210802T220302Z &X-Amz-Algorithm=Amazon4-HMAC-SHA256 &X-Amz-Date=20210802T220302Z &X-Amz-SignedHeaders=Host &X-Amz-Expires=20210802T220302Z &X-Amz-Credential=<credential> &X-Amz-Signature=<signature>
The DeleteCluster
API operation only deletes one cluster. To delete
multiple clusters, call DeleteCluster
for each cluster
that you want to delete. You do not need to wait for one cluster to finish
deleting before deleting another.
For more information, see DeleteCluster.
Next steps
Now that you have tried the Getting Started exercise, you can explore the following sections to learn more about MemoryDB and available tools: