Enable OSS Cluster API

Redis Software

This documentation applies to version 7.22.

Review OSS Cluster API to determine if you should enable this feature for your database.

Prerequisites

The 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 primary 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 instead of the entire cluster.

Warning:

Kubernetes limitation: OSS Cluster API can only be used by clients running within the same Kubernetes cluster as the Redis Enterprise pods. External clients cannot use OSS Cluster API due to pod IP address accessibility limitations.

Enable OSS Cluster API support

You can use the Cluster Manager UI, the rladmin utility, or the REST API to enable OSS Cluster API support for a database.

When you enable OSS Cluster API support for an existing database, the change applies to new connections but does not affect existing connections. Clients must close existing connections and reconnect to apply the change.

Cluster Manager UI rladmin REST API

When you use the Cluster Manager UI to enable the OSS Cluster API, it automatically configures the prerequisites.

To enable the OSS Cluster API for an existing database in the Cluster Manager UI:

From the database's Configuration tab, click Edit.
Expand the Clustering section.
Enable Sharding.
Select OSS Cluster API.
Click Save.

You can also use the Cluster Manager UI to enable the setting when creating a new database.

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

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

Ensure the prerequisites have been configured. Then, 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 OSS Cluster API setting applies to the specified database only; it does not apply to the cluster.

You can enable the OSS Cluster API when you create a database using the REST API:

POST /v1/bdbs
{ 
  "oss_cluster": true,
  // Other database configuration parameters
}

To enable the OSS Cluster API for an existing database, you can use an update database configuration REST API request:

PUT /v1/bdbs/<database-id>
{ "oss_cluster": true }

Active-Active databases

The OSS Cluster API setting applies to all instances of the Active-Active database across participating clusters. To enable the OSS Cluster API for Active-Active databases, use the Cluster Manager UI or the crdb-cli utility.

Cluster Manager UI crdb-cli

When you use the Cluster Manager UI to enable the OSS Cluster API, it automatically configures the prerequisites.

To enable the OSS Cluster API for an existing Active-Active database in the Cluster Manager UI:

From the database's Configuration tab, click Edit.
Expand the Clustering section.
Sharding must be enabled during Active-Active database creation.
Select OSS Cluster API.
Click Save.

You can also use the Cluster Manager UI to enable the setting when creating a new database.

To create an Active-Active database and enable the OSS Cluster API with crdb-cli:

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

See the crdb-cli crdb create reference for more options.

To enable the OSS Cluster API for an existing Active-Active database with crdb-cli:

Obtain the CRDB-GUID for the new database:

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

Use the CRDB-GUID to enable the OSS Cluster API:

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

Change preferred IP type

By default, using CLUSTER SLOTS and CLUSTER SHARDS in a Redis Enterprise Software cluster exposes the internal IP addresses for databases with the OSS Cluster API enabled.

To use external IP addresses instead of internal IP addresses, run the following rladmin tune db command for each affected database:

$ rladmin tune db db:<database-id> oss_cluster_api_preferred_ip_type external

Turn off OSS Cluster API support

To deactivate OSS Cluster API support for a database, use one of the following methods:

Cluster Manager UI rladmin crdb-cli

To turn off the OSS Cluster API for standard databases or Active-Active databases in the Cluster Manager UI:

From the database's Configuration tab, click Edit.
Expand the Clustering section.
Clear the OSS Cluster API checkbox.
Click Save.

When you turn off OSS Cluster API support for an existing database, the change applies to new connections but does not affect existing connections. Clients must close existing connections and reconnect to apply the change.

Multi-key command support

When you enable the 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.

Products

Tools

Get Redis

Connect

Learn

Latest

See how it works