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