Skip to content

OSS Cluster Support

Jump to bottom
Brian Sam-Bodden edited this page Aug 15, 2025 · 1 revision

Redis OM Spring Cluster Support Research

Issue #48 Overview

Users have requested Redis Cluster support for Redis OM Spring to enable use with clustered Redis deployments. Currently, the library only supports single Redis instances and Sentinel configurations.

Key Findings

1. RediSearch and Redis OSS Cluster Incompatibility

Critical Limitation: RediSearch (the core search module used by Redis OM Spring) is fundamentally incompatible with Redis OSS Cluster mode.

Evidence and References

  1. Redis Official Documentation (Redis.io - OSS Cluster API):

    "OSS clustering policy can't be used with the RediSearch module"

  2. GitHub Issue #4588 (RediSearch Repository, April 2024):

    "Please Help Fix RSCoordinator So that Redis Search (RediSearch) Can Be Used Across Redis Cluster - module-oss.so initialization failed"

  3. Redis Community Forum (2023-2024):

    "How can I handle redis-cluster with Redis Stack (RediSearch)?"

    • Official response confirms RediSearch cannot work with standard Redis Cluster
    • Users report: "cannot import data across nodes and can only access data within the same node"
    • Source: Redis Community Forum Discussion

  4. Azure Managed Redis Documentation (Microsoft, 2024):

    "OSS clustering policy can't be used with the RediSearch module. The Enterprise clustering policy is the only one that can be used with the RediSearch module."

  5. Stack Overflow Discussions (2024):

Technical Reasons

  • RediSearch operations often require cross-slot operations that conflict with how Redis OSS Cluster distributes data across shards
  • Search indexes need to span multiple keys which may be distributed across different cluster nodes
  • Aggregation and full-text search queries cannot be efficiently executed across cluster boundaries
  • This is an architectural limitation, not a simple configuration issue

2. Spring Data Redis Cluster Support

Spring Data Redis provides robust cluster support through:

  • RedisClusterConnection for cluster-aware connections
  • ClusterOperations interface via RedisTemplate.opsForCluster()
  • Automatic routing of commands to correct nodes
  • Support for cross-slot operations (with performance penalties)

Key features:

  • Automatic sharding across 16,384 slots
  • Commands routed to appropriate nodes automatically
  • Multi-key operations supported (but less performant when keys map to different slots)

3. Current Redis OM Spring Implementation

The codebase shows minimal cluster preparation:

  • RedisModulesClient has a getJedisCluster() method that returns empty Optional (not implemented)
  • IdAsHashTag utility exists for hash tag support (useful for ensuring related keys map to same slot)
  • getUnifiedJedis() only handles Standalone and Sentinel modes, not Cluster

4. Alternative Clustering Solutions

A. Redis Enterprise Clustering

  • Uses proxy-based architecture that makes cluster appear as single instance
  • Supports RediSearch through RSCoordinator
  • All requests route through proxy that internally handles distribution
  • This is the only proven way to use RediSearch with clustering

B. RSCoordinator

  • Distributed coordinator for RediSearch in clustered environments
  • Available in Redis Enterprise (full version)
  • Open source gets "RSCoordinatorLight" with limited functionality
  • Has not been actively maintained (last meaningful updates 9+ months ago as of 2024)

References:

  • RSCoordinator GitHub Repository: "RSCoordinator runs alongside RediSearch and distributes search commands across the cluster"
  • Stack Overflow Discussion (2024): "The redis-stack-server images do NOT include the latest RSCoordinator"
  • Community reports indicate RSCoordinator hasn't been updated recently and may have been rolled into RediSearch itself

C. Application-Level Sharding

  • Manually partition data across multiple Redis instances
  • Each instance runs RediSearch independently
  • Application handles routing logic
  • Complex but possible for specific use cases

5. Java Client Library Support

Jedis

  • Supports cluster mode via JedisCluster
  • Can execute module commands on cluster
  • Limitations: No transactions or pipelines in cluster mode

Lettuce

  • Advanced cluster support with reactive/async capabilities
  • Dedicated "lettusearch" library for RediSearch
  • Better suited for reactive applications

Potential Implementation Approaches

Option 1: Limited Cluster Support (Recommended for Initial Implementation)

Provide cluster support for basic Redis operations while clearly documenting RediSearch limitations:

public class RedisModulesClient {
    private UnifiedJedis getUnifiedJedis() {
        var clusterConfiguration = jedisConnectionFactory.getClusterConfiguration();

        if (clusterConfiguration != null) {
            // Cluster mode - with limitations
            logger.warn("Cluster mode detected. RediSearch operations will be limited to single-slot operations.");

            var nodes = clusterConfiguration.getClusterNodes().stream()
                .map(node -> new HostAndPort(node.getHost(), node.getPort()))
                .collect(Collectors.toSet());

            return new JedisCluster(nodes, jedisClientConfig);
        }
        // ... existing sentinel and standalone logic
    }
}

Pros:

  • Enables basic Redis operations in cluster mode
  • Users can use JSON storage with limitations
  • Clear migration path when better solutions become available

Cons:

  • RediSearch features severely limited
  • Many operations will fail with cross-slot errors
  • Poor user experience for search operations

Option 2: Proxy-Based Solution

Implement or recommend a proxy layer that makes cluster appear as single instance:

  • Use Redis Enterprise (commercial solution)
  • Implement custom proxy using redis-cluster-proxy
  • Use third-party proxies like Twemproxy (with limitations)

Pros:

  • Full RediSearch functionality maintained
  • Transparent to application code

Cons:

  • Additional infrastructure complexity
  • Potential performance overhead
  • May require commercial Redis Enterprise license

Option 3: Application-Level Sharding

Implement sharding logic within Redis OM Spring:

public interface ShardingStrategy {
    String selectShard(String key);
    List<String> getAllShards();
}

public class ShardedRedisDocumentRepository {
    private Map<String, RedisModulesClient> shardClients;
    private ShardingStrategy shardingStrategy;

    public void save(T entity) {
        String shard = shardingStrategy.selectShard(entity.getId());
        shardClients.get(shard).save(entity);
    }

    // Aggregate search results across shards
    public List<T> search(Query query) {
        return shardClients.values().parallelStream()
            .flatMap(client -> client.search(query).stream())
            .collect(Collectors.toList());
    }
}

Pros:

  • Full control over sharding logic
  • Can optimize for specific use cases
  • No external dependencies

Cons:

  • Complex implementation
  • Maintenance burden
  • Performance implications for cross-shard queries

Recommendations

Short Term (v1.1)

  1. Document current limitations clearly

    • Add warning in README about cluster incompatibility
    • Provide guidance on alternatives (Sentinel, Redis Enterprise)

  2. Implement basic cluster detection

    • Detect cluster configuration
    • Throw informative exception with alternatives

  3. Add hash tag support for keys

    • Extend IdAsHashTag functionality
    • Document how to use for related entities

Medium Term (v1.2+)

  1. Investigate RSCoordinator integration

    • Test with open source RSCoordinatorLight
    • Document limitations vs Enterprise version

  2. Implement limited cluster support

    • Support JSON operations that don't require search
    • Provide clear errors for unsupported operations

  3. Create migration guide

    • From single instance to Sentinel
    • From OSS to Redis Enterprise

Long Term

  1. Consider alternative search solutions

    • Evaluate if RediSearch alternatives emerge with cluster support
    • Monitor RSCoordinator development

  2. Implement application-level sharding

    • If demand justifies complexity
    • As optional feature with clear documentation

Conclusion

Redis Cluster support for Redis OM Spring is severely limited by RediSearch's incompatibility with OSS clustering. The most viable short-term approach is to:

  1. Clearly document the limitation
  2. Recommend Redis Enterprise for users needing clustering
  3. Provide limited support for non-search operations
  4. Monitor the ecosystem for emerging solutions

Users requiring both clustering and search capabilities should consider:

  • Redis Enterprise (recommended)
  • Multiple Sentinel deployments with application-level routing
  • Alternative search solutions that support clustering

References and Sources

Official Documentation

  1. Redis OSS Cluster API Docs - Confirms RediSearch incompatibility with OSS Cluster
  2. Spring Data Redis - Cluster Support - Details on Spring's cluster implementation
  3. Azure Managed Redis Architecture - Enterprise clustering requirements for RediSearch
  4. Redis Cluster Specification - Technical details of Redis Cluster

GitHub Issues and Repositories

  1. redis/redis-om-spring#48 - Original cluster support request
  2. RediSearch/RediSearch#4588 - RSCoordinator and cluster compatibility issues
  3. RediSearch/RSCoordinator - Distributed coordinator for RediSearch
  4. redis/jedis - RediSearch Docs - Jedis support for RediSearch
  5. RediSearch/lettusearch - Lettuce-based client for RediSearch

Community Discussions

  1. Redis Community Forum - RediSearch Cluster - User experiences with cluster limitations
  2. Stack Overflow - RediSearch Cluster Issues - Technical discussions on incompatibility
  3. Stack Overflow - RSCoordinator Updates - Current state of RSCoordinator

Research Date

This research was conducted in August 2025, reflecting the state of Redis ecosystem and available solutions as of that time.

Clone this wiki locally