Oracle Cloud Infrastructure Documentation

Connecting to a Redis Cluster

Cache with Redis provides access to a cluster over a private endpoint.

With private endpoints, traffic doesn't go over the internet. You can only connect to the cluster from a client within the same VCN as the cluster or another VCN with appropriate gateways and route rules configured.

Warning

The KEYS command isn't supported for regular use in production environments, it's intended for debugging and special operations only. When you send the KEYS command to a cluster, the cluster might experience a crash or performance degradation.

To find keys in a subset of the keyspace, use the SCAN command or a sets data type instead.

Limitations and Considerations

  • Cache with Redis only supports TLS connections with Redis clusters, regardless of the client you're connecting from.

  • Redis CLI version 6 or newer is required, Redis CLI version 7 is recommended, see Connecting with the Redis CLI.

  • When connecting to databases such as Redis, you should use connection pooling as a good development practice. If the number of connections to the Redis cluster exceeds 1024, it might cause excessive load on the Redis process and slow down responses. Consult the documentation for the framework or library that you're using for recommended coding practices with Redis.

Cluster Connection Information

The cluster's connection information includes the following endpoints that you use to connect to the cluster:

  • Primary endpoint: This is the endpoint for the cluster's primary node. This endpoint always connects to the node configured as the primary, even if the underlying instance configured as the primary node has changed.

  • Replicas endpoint: This is the endpoint for the cluster's replica nodes. This endpoint always connects to a node configured as a replica, though for clusters with multiple replica nodes, it might not be the same replica each time.

  • Node endpoints: These are the direct endpoints to each node instance. You should only use these endpoints for connections if you have verified that you're connecting to the type of node that you expect to connect to. In some cases the primary node's underlying instance might have changed. To guarantee that you're connecting to the primary node, use the primary endpoint instead.

See Getting a Redis Cluster's Connection Details for how to view this information.

Security Rule for Connecting to Redis Clusters

To enable connections to a Redis cluster, the cluster's VCN must have an ingress security rule configured with the following values:

  • Stateless: No
  • IP Protocol: TCP
  • Source Port Range: All
  • Destination Port Range: 6379
  • Allows: TCP traffic for ports: 6379

The Networking service provides two features that you can use to apply a security rule to a VCN, security lists and network security groups (NSGs). Cache with Redis supports both features, for more information see Security List for Redis Clusters and Using an NSG for Redis Clusters.

With security lists, the security rule applies to all VCNs within a subnet. If you want the security rule to only apply to subset of VCNs, use an NSG instead. For more information about the differences between security groups and NSGs, see Comparison of Security Lists and Network Security Groups.

Security List for Redis Clusters

When a Redis cluster is created, to make the data accessible from the cluster, Cache with Redis creates a security list with a stateful ingress security rule for TCP traffic on destination port 6379 for the cluster's VCN.

You can verify the security list for this rule using the following steps:

  1. Open the navigation menu and click Databases. Under Redis, click Clusters.

  2. Under List scope, select the compartment that contains the cluster.

  3. In the Clusters list, click the name of the cluster that you're interested in.

  4. Under Cluster information, for Subnet, click the name of the subnet. The Subnet Details page opens.
  5. Under Resources, click Security Lists.
  6. Click the security list named redis-security-list.
  7. Under Ingress Rules, you should see one rule listed, with the following values:
    • Stateless: No
    • IP Protocol: TCP
    • Source Port Range: All
    • Destination Port Range: 6379
    • Allows: TCP traffic for ports: 6379

If you don't see the security list or the rule isn't configured as required, you can create a new security list and add the rule, or you can add the rule to the default security list for the VCN. For more information, see Security Lists and Creating a Security List.

When creating and configuring the rule, you need to specify the following options in the Add Ingress Rules page:
  • Stateless: Leave the check box cleared.
  • Source Type: CIDR
  • IP Protocol: TCP
  • Source Port Range: All
  • Destination Port Range: 6379

Using an NSG for Redis Clusters

To use an NSG instead of a security list, you need to add an ingress security rule to the NSG with the required configuration for connecting to a Redis cluster. For more information about creating and managing NSGs, see the following:

When creating and configuring the ingress rule for the NSG, you need to specify the following configuration:
  • Stateless: Leave the check box cleared.
  • Source Type: CIDR
  • IP Protocol: TCP
  • Source Port Range: All
  • Destination Port Range: 6379

You can configure one to five NSGs for a cluster. You can specify NSGs for a cluster when you create the cluster. You can also configure NSGs for an existing cluster, see Configure a Redis Cluster's NSGs.

Create a VM Instance

You can connect to the cluster using the Redis CLI from a VM instance within the same subnet as the cluster. See one of the following topics for how to create an instance:

After the instance is created, connect to the instance. For more information, see the following:

Connecting with the Redis CLI

Tip

Redis CLI version 6 or newer is required, Redis CLI version 7 is recommended.

Download and install the Redis CLI, redis-cli, on the VM instance. Run the following command to connect to the cluster's primary node:

redis-cli --tls -h <ID>-p.redis.<region>.oci.oraclecloud.com

If you don't include --tls, the error Error: connection reset by peer occurs for any Redis CLI commands.

The error Unrecognized option or bad number of args for: '--tls' occurs if the version of the Redis CLI you're using is older than version 6. To check the Redis CLI version, run the following command:

redis-cli -v

Troubleshooting the Connection to a Redis Cluster

Test Basic Connectivity with dig Tool

Use the dig tool to test basic network connectivity to the cluster, for example to connect to the primary node:
dig <primary_endpoint>

See Getting a Redis Cluster's Connection Details for how to get the primary node endpoint.

If you run the dig command from within the same VCN as the cluster, and the connection fails to resolve, verify that the subnet has security list with a stateful ingress security rule for TCP traffic on destination port 6379. When you create cluster, Cache with Redis creates a security list with the required configuration, however if this is removed or updated, you need to add this configuration. For details, see Security List for Redis Clusters.

If you run the dig command from a different VCN as the cluster, and the connection fails to resolve, check that you have the correct route table configuration for the VCNs, see VCN Route Tables.

Network Path Analyzer

You can also use Network Path Analyzer to test connectivity to the cluster. With this tool, you can troubleshoot and identify routing and other network configuration issues with the setup, whether you're connecting from within the same VCN or a different VCN.