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.
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.
-
Open the navigation menu and click Databases. Under OCI Cache, click Clusters.
-
Under List scope, select the compartment that contains the cluster.
-
In the Clusters list, click the name of the cluster that you're interested in.
- Under Cluster information, for Subnet, click the name of the subnet. The Subnet Details page opens.
- Under Resources, click Security Lists.
- Click the security list named redis-security-list.
- 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.
- 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:
- 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
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.
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.
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.
Troubleshooting the Connection to a Cluster
Test Basic Connectivity with dig Tool
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.