OSS Cluster API Configuration Guide

The OSS Cluster API in Redis Software enables client applications to connect directly to cluster nodes and shards using the native Redis Cluster protocol. This reduces proxy bottlenecks, improves scalability, and ensures compatibility with cluster-aware clients such as JedisCluster, redis-py-cluster, and go-redis. By exposing the cluster topology, the OSS Cluster API is best suited for high-throughput, latency-sensitive workloads where client-side routing is required.

This guide explains introduction and use cases, prerequisites and limitations, step-by-step configuration, client connectivity, proxy policies and shard placement, advanced options and API reference, and troubleshooting common issues.

Introduction & Use Cases

Enable the OSS Cluster API when:

• Clients need to route requests efficiently without relying on proxies.

• Applications require near-linear scalability in high-throughput workloads.

• Native Redis Cluster client compatibility is needed (for example, when migrating from OSS to Redis Software).

• Applications benefit from client-side awareness of cluster topology for load balancing.

Common use cases: Feature stores, vector databases, high-throughput caches, and real-time pipelines.

Prerequisites & Limitations

Prerequisites

• Database uses the standard hashing policy.

• Proxy policy set to All primary shards or All nodes.

• Redis Search, RedisTimeSeries, and RedisGears modules are not enabled.

• Kubernetes deployments are only supported for clients inside the same Kubernetes cluster as Redis Enterprise.

• Proxy policies can not use include/exclude rules.

Limitations

• Multi-key operations are only supported if all keys map to the same slot (via hash tags).

• Only cluster-aware clients are supported.

• Internal IPs are exposed by default in topology responses; use preferred IP type for external access.

• Restrictions apply when combined with CRDB or Replica Of configurations.

• Only a subset of cluster commands are supported: CLUSTER SLOTS, CLUSTER NODES, CLUSTER INFO, and CLUSTER KEYSLOT.

Step-by-Step Configuration

1. Prepare the Database

• Confirm hashing policy is standard.

• Confirm proxy policy is All primary shards or All nodes.

• Verify that the application client supports Redis Cluster mode.

2. Enable OSS Cluster API

• Cluster Manager UI:

  • Go to Database → Configuration → Edit → Clustering.

  • Enable Sharding and OSS Cluster API.

  • Save changes.

• CLI (rladmin):

  rladmin tune db <db-id> oss_cluster enabled
  rladmin info db <db-id> | grep oss_cluster

• REST API:

  curl -X PUT -u <ADMIN_EMAIL>:<PASSWORD> \
    -H 'Content-Type: application/json' \
    -d '{"oss_cluster": true}' \
    https://localhost:9443/v1/bdbs/<DB_ID>

3. Configure Preferred IP Type (external access)

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

REST API:

curl -X PUT -u <ADMIN_EMAIL>:<PASSWORD> \
  -H 'Content-Type: application/json' \
  -d '{"oss_cluster_api_preferred_ip_type":"external","endpoint":"<endpoint-id>"}' \
  https://localhost:9443/v1/bdbs/<DB_ID>

Note: Switching between internal and external IPs replaces all topology replies; both cannot be used simultaneously.

4. Configure for Active-Active (CRDB)

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>

To update an existing CRDB:

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

5. Apply Changes

• Restart clients to pick up updated topology and settings.

Client Connectivity

• Use cluster-aware client libraries: JedisCluster, redis-py-cluster, go-redis, node-redis cluster mode.

• Provide multiple node addresses at startup for discovery.

Example (Python, redis-py-cluster):

from redis.cluster import RedisCluster

startup_nodes = [
    {"host": "node1.example.com", "port": 12000},
    {"host": "node2.example.com", "port": 12000},
    {"host": "node3.example.com", "port": 12000}
]

rc = RedisCluster(startup_nodes=startup_nodes, decode_responses=True)
rc.set("foo", "bar")
print(rc.get("foo"))

Proxy Policies & Shard Placement

• Proxy Policy

  • All primary shards: One proxy per node with a primary shard (recommended).

  • All nodes: Proxy per node, for advanced load balancing use cases.

• Shard Placement

  • Placement defaults to Sparse when OSS Cluster API is enabled to maximize distribution.

Advanced Options & API Reference

• Preferred Endpoint Type: Configure whether topology replies return hostnames or IPs using the oss_cluster_api_preferred_endpoint_type setting.

• Cluster Command Compatibility: Only a subset of cluster commands is supported. See the Cluster command compatibility chart.

Troubleshooting

Quick Fix Table

Kubernetes-specific

• Only supported for in-cluster clients; Pod IPs are not routable externally.

Modules

• OSS Cluster API is not supported with Redis Search, Time series, or Gears until future releases add compatibility.