Connecting to a Cluster

OCI Cache 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

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

  • 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 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 Redis client libraries that you use to connect to a sharded cluster must support 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:

  • 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). 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. Open the navigation menu and click Databases. Under OCI Cache, 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 checkbox cleared.
  • Source Type: CIDR
  • IP Protocol: TCP
  • Source Port Range: All
  • Destination Port Range: 6379

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:

When creating and configuring the ingress rule for the NSG, you need to specify the following configuration:
  • Stateless: Leave the checkbox 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 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.

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

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.

Important

You must include the -c switch for connections to sharded clusters. This specifies you're connecting with the CLI in cluster mode. See 4.2 Using Redis-CLI with a Redis Cluster for more information.

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

Important

Lua scripts aren't supported for sharded clusters.

Troubleshooting the Connection to a 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 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, OCI Cache 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 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.