Enable the OSS Cluster API (Requirements, Upgrade, and Activation)

The Redis OSS Cluster API allows cluster-aware clients to automatically discover hash slots and route requests directly to the shard that owns a given key. In Redis Software and Redis Cloud, this enables compatibility with open-source Redis Cluster clients and can improve throughput by reducing proxy routing hops.

This article covers plan requirements, product-specific prerequisites, activation steps for Redis Cloud, Redis Software, and Redis for Kubernetes, and important limitations that affect application design and feature compatibility.

Quick Decision Guide

Requirements by Product

Redis Cloud

Plan Requirement

• OSS Cluster API is available only on Redis Cloud Pro databases.

• Not supported on Essentials plans.

Upgrade Requirement

• Only subscription Owners or Admins can upgrade.

• Upgrade occurs at the subscription level.

Database Requirements

• Sharding must be enabled.

• Standard hashing policy must be used.

• Some clustering settings can only be set during database creation.

Redis Software (VM / Bare Metal)

The database must:

• Use standard hashing policy

• Have proxy policy set to:

  • All primary shards, or

  • All nodes

The database must not:

• Use node include/exclude proxy rules

• Use unsupported modules (for example RedisTimeSeries or RedisGears v1 in OSS cluster mode)

The OSS Cluster API setting is configured per database.

Redis for Kubernetes

Requirements include both cluster-level and database-level configuration.

Cluster-level (REC):

• Proxy policy must be all-master-shards or all-nodes

• REC version must support OSS cluster mode

• External access configuration required if clients are outside the cluster

spec:
  ossClusterSettings:
    externalAccessType: LoadBalancer
    # optional: podCIDRs for in‑cluster clients

Database-level (REDB):

• Enable OSS Cluster API in the REDB spec:

spec:
  ossCluster: true
  ossClusterSettings:
    enableExternalAccess: true  # required for external clients

• When enableExternalAccess: True, the operator provisions:

  • One LoadBalancer for the OSS cluster endpoint, and

  • One LoadBalancer per Redis node running a pod (cost impact).

Enable OSS Cluster API: Redis Cloud

Step 1: Confirm Plan

1. In the Redis Cloud Console, open the subscription that contains your database.

2. Verify the plan type is Pro.

If not Pro:

1. Navigate to the subscription Billing page.

2. Select Upgrade.

3. Choose a Pro plan.

4. Confirm and wait for upgrade completion.

Step 2: Enable on a New Database (Recommended)

1. Create a new database in your Pro subscription.

2. Enable sharding.

3. Select the option labeled similar to:

   • “Support OSS Cluster API”

   • “OSS cluster-compatible”

4. Complete creation.

5. Note the cluster-aware connection endpoint.

Step 3: Enable on an Existing Database

1. Open the database.

2. Select Edit.

3. Locate the OSS Cluster API toggle.

4. Enable and Save.

If the toggle is not available:

• The setting is creation-time only.

• Create a new database with OSS Cluster API enabled.

• Migrate data and cut over applications.

Enable OSS Cluster API: Redis Software

Using Cluster Manager UI

1. Navigate to Databases.

2. Create or edit a database.

3. In the Clustering section:

   • Ensure Sharding is enabled.

   • Enable OSS Cluster API.

4. Save changes.

Changes apply to new connections only.

Using rladmin

Enable:

rladmin tune db <db-name-or-id> oss_cluster enabled

Verify:

rladmin info db <db-name-or-id> | grep oss_cluster

Disable:

rladmin tune db <db-name-or-id> oss_cluster disabled

Existing client connections must reconnect for the change to take effect.

Enable OSS Cluster API: Kubernetes

Cluster-Level (REC)

Edit your RedisEnterpriseCluster resource:

spec:
  ossClusterSettings:
    externalAccessType: LoadBalancer

Apply:

kubectl apply -f rec.yaml

Database-Level (REDB)

spec:
  ossCluster: true
  ossClusterSettings:
    enableExternalAccess: true

Apply:

kubectl apply -f redb.yaml

Then verify services:

kubectl get svc

After Enabling

• Use a cluster-aware client library

• Provide multiple startup nodes where possible

• Update application configuration to use the OSS cluster endpoint

• If TLS is enabled, use rediss:// or client TLS configuration

• Test:

  • Slot migrations

  • MOVED/ASK redirects

  • Failover behavior

  • Multi-key command behavior

Critical Limitations

Search & Query Compatibility

OSS Cluster API does not support cross-shard Search & Query operations.
If you require:

• RediSearch

• JSON indexing

• Global indexing

• Cross-shard aggregation

Use default proxy routing instead.

Multi-Key Command Restrictions

Multi-key operations require all keys to hash to the same slot.

To align keys:

user:{123}:profile
user:{123}:settings

Verify:

CLUSTER KEYSLOT <key>

All keys must return the same slot number.

Internal vs External IP Exposure

If clients see internal IPs in CLUSTER SLOTS output:

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

Kubernetes Cost Considerations

Enabling external OSS cluster access creates:

• One LoadBalancer for the cluster endpoint

• One LoadBalancer per Redis node

Evaluate cost impact before enabling.

When to Use OSS Cluster API

Enable OSS Cluster API when:

• Migrating from Redis open-source cluster

• Needing maximum horizontal scalability

• Running high-throughput key-value workloads

• Using cluster-aware clients

Avoid enabling when:

• Using Search & Query features

• Application cannot use cluster-aware clients

• Simpler proxy-based routing is sufficient