Connecting to a Cluster

Limitations and Considerations

• You can only connect to a cluster's nodes using the Fully Qualified Domain Names (FQDNs) provided by the service. For non-sharded clusters, the FQDNs are for the private endpoints to the cluster's primary or replica nodes, see Getting a Cluster's Connection Details. For sharded clusters, the FQDNs are for the private endpoints to each shard's node, see Getting a Sharded Cluster's Connection Details.

  Important
  
  Don't use IP addresses to resolve nodes in the topology.

• By default, OCI Cache only supports TLS connections with clusters, regardless of the client you're connecting from. If your scenario requires connecting without TLS, contact support.

• If the cache engine version for the cluster is REDIS_7_0, Redis CLI version 6 or newer is required, Redis CLI version 7 is recommended. If the cache engine version is VALKEY_7_2, Valkey CLI version 7.2 is required. For more information, see Connecting with the Valkey CLI or Redis CLI.

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

• When you create a cluster, OCI Cache creates and manages the set of Compute instances that comprise the cluster's nodes. These instances are the only instances that are supported as cluster nodes; you can't attach any instances that you created separately as a node for the cluster. Attempting to attach additional instances to the cluster causes the cluster to enter a FAILED lifecycle state.

• Any Valkey or Redis client libraries that you use to connect to a sharded cluster must support Valkey or Redis CLUSTER MODE with hostname support.

Non-Sharded 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. 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. Sometimes 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 Cluster's Connection Details for how to view this information.

Sharded Cluster Connection Information

Sharded clusters don't have primary or replica endpoints at the cluster level that you use to connect to the cluster. Instead, you use the private endpoints for the primary nodes of a cluster's shards, see Getting a Sharded Cluster's Connection Details for how to get this information. We recommend that you specify the private endpoints for the first three shards of the cluster in your application's connection information.

Security Rule for Connecting to Clusters

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

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). OCI Cache supports both features, for more information see Security List for Clusters and Using an NSG for 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 Clusters

When you create a cluster, to make the data accessible from the cluster, OCI Cache 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. On the Clusters list page, select the cluster that you want to work with. If you need help finding the list page or the cluster, see Listing Clusters.

2. On the details page, select the Subnet link in the Cluster information tab.

3. On the subnet's list page, select Security.

4. On the Security Lists page, select redis-security-list.

5. On the redis-security-list details page, select Security rules.

6. 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.

Using an NSG for 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 cluster. For more information about creating and managing NSGs, see the following:

• Creating an NSG

• Managing Security Rules for an NSG

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 Cluster's NSGs.

Create a VM Instance

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

• Tutorial - Launching Your First Linux Instance

• Creating an Instance

Connecting with the Valkey CLI or Redis CLI

Download and install the Redis CLI or the Valkey CLI on the VM instance.

To connect to a non-sharded cluster, run the following command to connect to the cluster's primary node:

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

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

To connect to a sharded cluster, run the following command to connect to one of the cluster's shards:

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

See Getting a Sharded Cluster's Connection Details for how to get the connection string for the shard.

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

Lua Scripts

Lua scripts run on the server, enabling efficient reading and writing of cluster data, for more information see Scripting with Lua. The following example shows calling the EVAL command from the Valkey CLI or Redis CLI to set a key value, and then retrieve the key value.

To set the key value:

redis-cli --tls -h <IP_address> EVAL "return redis.call('SET', 'mykey', 'helloworld')" 0

To retrieve the key value you just set:

redis-cli --tls -h <IP_address> EVAL "return redis.call('GET', 'mykey')" 0

We don't recommend using long-running Lua scripts. When a Lua script runs, other commands are blocked from running until the Lua script has completed. The maximum run time for a script is set by the busy-reply-threshold value. By default, the busy-reply-threshold value is five seconds. When a Lua script runs longer than the five second default run time, there's an increased chance that failovers are triggered for the cluster, and that the cluster enters an unhealthy state. If you have a cluster that requires Lua scripts that take longer than five seconds to run, contact support to request that the busy-reply-threshold value for the cluster is increased.