Enable OSS Cluster API

Redis OSS Cluster API reduces access times and latency with near-linear scalability. The Redis OSS Cluster API provides a simple mechanism for Redis clients to know the cluster topology.

Clients must first connect to the master node to get the cluster topology, and then they connect directly to the Redis proxy on each node that hosts a master shard.

Prerequisites

The Redis OSS Cluster API is supported only when a database meets specific criteria.

The database must:

• Use the standard hashing policy.
• Have the proxy policy set to either all-master-shards or all-nodes.

In addition, the database must not:

• Use node include or exclude in the proxy policy.
• Use RediSearch, RedisTimeSeries, or RedisGears modules.

The OSS Cluster API setting applies to individual databases, as opposed to the overall cluster.

Enable OSS Cluster API support

You can use the admin console or the rladmin utility to enable OSS Cluster API support for a database.

Admin console

To enable the OSS Cluster API from the admin console for an existing database:

1. From the database’s Configuration tab, select Edit.

2. Expand the Clustering section.

3. Turn on the OSS Cluster API toggle.

   

4. Select Save.

You can also use the admin console to enable the setting when creating a new database.

Command line (rladmin)

You can use the rladmin utility to enable the OSS Cluster API for Redis Enterprise Software databases, including Replica Of (Active-Passive) databases.

For Active-Active (CRDB) databases, use the crdb-cli utility.

To enable the OSS Cluster API for a Redis database from the command line:

$ rladmin tune db <database name or ID> oss_cluster enabled

To determine the current setting for a database from the command line, use rladmin info db to return the value of the oss_cluster setting.

$ rladmin info db test | grep oss_cluster:
  oss_cluster: enabled

The Redis OSS Cluster API setting applies to the specified database only; it does not apply to the cluster.

Active-Active databases

Use the crdb-cli utility to enable the OSS Cluster API for Active-Active databases:

$ crdb-cli crdb update --crdb-guid <GUID> --oss-cluster true

For best results, you should do this when you first create the database.

Here’s the basic process:

1. Create the Active-Active database:

   $ crdb-cli crdb create --name <name> \
      --memory-size 10g --port <port> \
      --sharding true --shards-count 2  \
      --replication true --oss-cluster true \
      --instance fqdn=<fqdn>,username=<user>,password=<pass> \
      --instance fqdn=<fqdn>,username=<user>,password=<pass> \
      --instance fqdn=<fqdn>,username=<user>,password=<pass>
   

2. Obtain the CRDB-GUID ID for the new database:

   $ crdb-cli crdb list
   CRDB-GUID    NAME   REPL-ID  CLUSTER-FQDN
   <CRDB-GUID>  Test   4        cluster1.local
   

3. Use the CRDB-GUID ID to enable the OSS Cluster API:

   $ crdb-cli crdb update --crdb-guid <CRDB-GUID> \
       --oss-cluster true
   

The Redis OSS Cluster API setting applies to all of the instances of the Active-Active database.

Turn off OSS Cluster API support

To deactivate OSS Cluster API support for a database, either:

• Use the admin console to turn off the OSS Cluster API toggle from the database Configuration settings.

• Use the appropriate utility to deactivate the OSS cluster setting.

  For standard databases, including Replica Of (Active-Passive), use rladmin:

  $ rladmin tune db <Name or ID> oss_cluster disable
  

  For Active-Active databases, use crdb-cli:

  $ crdb-cli crdb update --crdb-guid <CRDB-GUID> \
      --oss-cluster false
  

Multi-key command support

When you enable the Redis OSS Cluster API for a database, multi-key commands are only allowed when all keys are mapped to the same slot.

To verify that your database meets this requirement, make sure that the CLUSTER KEYSLOT reply is the same for all keys affected by the multi-key command. To learn more, see multi-key operations.