How do I connect to ElastiCache Serverless or self-managed clusters that run on ElastiCache for Valkey, Redis OSS, or Memcached engines?

Short description

Note: The following resolution tests a connection only for unplanned use. For a list of supported clients, see Connect with Redis client API libraries on the Redis website and Client libraries on the Valkey website.

Based on your ElastiCache cluster configuration, complete the steps in the following section to test your connectivity:

• Connect to an unencrypted ElastiCache for Valkey or ElastiCache for Redis OSS cluster. This includes (cluster mode disabled) and (cluster mode enabled) clusters.
• Connect to an encrypted ElastiCache for Valkey or ElastiCache for Redis OSS cluster. This includes (cluster mode disabled) and (cluster mode enabled) clusters.
• Use telnet or OpenSSL to connect to a (cluster mode disabled) cluster.
• Connect to an ElastiCache for Memcached cluster. This includes unencrypted and encrypted clusters.
• Connect to an ElastiCache Serverless cache.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Connect to an unencrypted ElastiCache for Valkey or ElastiCache for Redis OSS cluster

ElastiCache supports both (cluster mode disabled) and (cluster mode enabled) in Valkey and Redis OSS clusters. To test a connection to the clusters, use the valkey-cli or the redis6-cli. For more information, see the Valkey CLI on the Valkey website, and the Redis CLI on the Redis website.

Note: To install valkey-cli, see Encrypted connection with Linux. If your cluster is unencrypted, then don't include the BUILD_TLS parameter. To test with Amazon Linux 2023, install the redis6 package. This package includes redis6-cli with default encryption support.

For information on how to find Redis endpoints, see Finding connection endpoints in ElastiCache.

Connect to a (cluster mode disabled) Valkey or Redis OSS cluster

To connect to a (cluster mode disabled) cluster, run the following command:

Amazon Linux 2023:

redis6-cli -h yourEndpoint -p 6379

Amazon Linux and Amazon Linux 2:

src/valkey-cli -h yourEndpoint -p 6379

Note: Replace yourEndpoint with the endpoint of your cluster, and 6379 with your port number.

The preceding commands return a Valkey command prompt that's similar to the following example:

yourEndpoint:6379>

Connect to a (cluster mode enabled) Valkey or Redis OSS cluster

To connect to a (cluster mode enabled) cluster, run the following command:

Amazon Linux 2023:

redis6-cli -c -h yourConfigEndpoint -p 6379

Amazon Linux and Amazon Linux 2:

src/valkey-cli -c -h yourConfigEndpoint -p 6379

Note: Replace yourConfigEndpoint with the endpoint of your cluster, and 6379 with your port number. The -c parameter turns on cluster mode after -ASK and -MOVED redirections occur. If you don't turn on redirection, then the command returns the MOVED error.

The preceding commands return a Valkey command prompt that's similar to the following example:

yourConfigEndpoint:>

Connect to an encrypted ElastiCache for Valkey or ElastiCache for Redis OSS cluster

To connect to either a (cluster mode enabled) or (cluster mode disabled) encrypted cluster, use the --tls parameter in the valkey-cli. The --tls parameter turns on encryption in-transit for the cluster. If there's an AUTH token set on the cluster, then use the -a parameter to provide an AUTH password. Or, use the AUTH command to authenticate, as seen in the following example commands.

After you turn on encryption in-transit, update your client configuration to use the new TLS-specific endpoints. For more information, see Best practices when enabling in-transit encryption.

Note: In clusters with Valkey or Redis OSS versions 7 and later, you can turn on encryption in-transit for existing ElastiCache clusters. You don't have to rebuild your cluster to change the TLS configuration for your Valkey or Redis OSS cluster.

Connect to a (cluster mode disabled) encrypted cluster

To connect to a (cluster mode disabled) cluster with encryption and authentication turned on, run the following command:

Amazon Linux 2023:

redis6-cli -h yourEndpoint -p 6379 --tls

AUTH <username> <password>

Amazon Linux and Amazon Linux 2:

src/valkey-cli -h yourEndpoint -p 6379 –tls

AUTH <username> <password>

Note: Replace yourEndpoint with the endpoint of your cluster, and 6379 with your port number. When you use AUTH with a single argument form of the command and specify only the password, Valkey CLI assumes that the username is default. For more information, see the AUTH command on the Valkey website.

Connect to a (cluster mode enabled) encrypted cluster

To connect to a (cluster mode enabled) cluster with encryption and authentication turned on, run the following command:

Amazon Linux 2023:

redis6-cli -c -h yourConfigEndpoint -p 6379 –tls

AUTH <username> <password>

Amazon Linux and Amazon Linux 2:

src/valkey-cli -c -h yourConfigEndpoint -p 6379 –tls

AUTH <username> <password>

Note: Replace yourConfigEndpoint with the endpoint of your cluster, and 6379 with your port number. When you use AUTH with a single argument form of the command and specify only the password, Valkey CLI assumes that the username is default. For more information, see the AUTH command on the Valkey website.

Use telnet of OpenSSL to connect to a (cluster mode disabled) cluster

To run a short test without the valkey-cli configuration, use telnet or OpenSSL to connect to a (cluster mode disabled) cluster. After you use telnet or OpenSSL to connect, you can run Valkey commands.

The following example command connects to an encrypted or authenticated (cluster mode disabled) cluster:

openssl s_client -connect master.valkeycmdencrypted.dcba18.use1.cache.amazonaws.com:6379

If you set a password for the cluster, then connect to the cluster and run the following command to authenticate the cluster. Then, press Enter:

AUTH <username> <password>

Note: Replace username and password with your user credentials.

The following example command connects to a (cluster mode disabled) cluster that doesn't have encryption or authentication turned on:

telnet yourEndpoint 6379

Connect to an ElastiCache for Memcached cluster

To connect to an ElastiCache for Memcached cluster, complete the following steps based on your cluster.

Connect to an unencrypted Memcached cluster

To connect to an unencrypted Memcached cluster, use the telnet utility. Complete the following steps:

1. Install the telnet utility on the instance that you want to test a connection from.

   For CentOS-based systems, run the following command:

   sudo yum install telnet

   For Debian-based systems (Ubuntu), run the following command:

   sudo apt-get install telnet

   For more information, see Connect to your EC2 instance.

2. To connect to the endpoint, run the following command:

   telnet yourEndpoint 11211

   Note: Replace yourendpoint with your cluster endpoint, and 11211 with your node's port.

   Example output:

   Trying 128.0.0.1...
   Connected to mycachecluster.dcba18.0001.usw2.cache.amazonaws.com.
   Escape character is '^]'.>

Connect to an encrypted Memcached cluster

Clusters that run Memcached versions 1.6.12 and later support encryption in-transit. Because telnet doesn't support encryption, use OpenSSL to connect to a Memcached cluster that has encryption turned on.

Note: You can turn on in-transit encryption on a cluster only when you create the cluster. You can't modify the cluster to turn on or turn off in-transit encryption. For more information, see ElastiCache in-transit encryption (TLS).

To connect to the endpoint, run the following command:

openssl s_client -quiet -crlf -connect yourEndpoint:11211

Note: Replace yourEndpoint with your endpoint, and 11211 with your node's port.

Example output:

depth=2 C = US, O = Amazon, CN = Amazon Root CA 1  verify return:1  depth=1 C = US, O = Amazon, CN = Amazon RSA 2048 M02  verify return:1  
depth=0 CN = *.testwithtls.qtyxq7.apse2.cache.amazonaws.com  
verify return:1

Connect to an ElastiCache Serverless cache

By default, ElastiCache Serverless launches all clusters with encryption in-transit turned on by default. You can't turn off this option. For the client libraries that you select, the libraries must support the ability to establish TLS connections.

For ElastiCache Serverless for Valkey and Redis OSS, the caches advertise two ports with the same hostname: Primary port: 6379 and Read port: 6380. The primary port allows read and write, and the read port uses the READONLY command to allow lower-latency, eventually consistent reads.

For ElastiCache Serverless for Memcached caches, the caches also advertise two ports with the same hostname: Primary port: 11211 and Read port: 11212. To allow resource access to these ports, update your security groups and network access control lists (network ACLs).

To connect to an ElastiCache Serverless cache, run the following command based on your engine and ports:

Valkey or Redis OSS (Amazon Linux 2023):

redis6-cli -c -h yourEndpoint -p 6379 –tls

Valkey or Redis OSS (Amazon Linux or Amazon Linux 2):

src/valkey-cli -c -h yourEndpoint -p 6379 –tls

Memcached:

openssl s_client -connect yourEndpoint:11212 -crlf

Note: Replace yourEndpoint with the endpoint of your cluster.

Related information

Command reference on the Valkey website

ElastiCache in-transit encryption (TLS)

How do I troubleshoot connectivity issues with my ElastiCache for Redis self-designed cluster?