Skip to content

Orleans Clustering - Redis

Overview

Redis clustering enables Orleans silos to discover each other and form a cluster using Redis as the membership table. This provides high-performance membership operations with fast failover detection, making it ideal for scenarios requiring low-latency cluster management.

Configuration

Basic Configuration

{
  "Orleans": {
    "ClusteringSettings": {
      "ProviderType": "Redis",
      "Redis": {
        "ConnectionString": "localhost:6379",
        "Database": 0
      }
    }
  }
}

Redis Cluster Configuration

{
  "Orleans": {
    "ClusteringSettings": {
      "ProviderType": "Redis",
      "Redis": {
        "ConnectionString": "localhost:6379,localhost:6380,localhost:6381",
        "Database": 0
      }
    }
  }
}

Redis with Password

{
  "Orleans": {
    "ClusteringSettings": {
      "ProviderType": "Redis",
      "Redis": {
        "ConnectionString": "localhost:6379,password=YourPassword",
        "Database": 0
      }
    }
  }
}

Setup Instructions

1. Install and Configure Redis

Docker (Recommended for Development):

docker run -d -p 6379:6379 redis:latest

Docker Compose:

The template includes Redis in docker-compose.yml:

redis:
  image: redis:latest
  ports:
    - "6379:6379"

Local Installation:

  • Windows: Download from Redis for Windows
  • Linux: sudo apt-get install redis-server (Ubuntu/Debian) or sudo yum install redis (RHEL/CentOS)
  • macOS: brew install redis

2. Verify Redis Connectivity

redis-cli ping
# Should return: PONG

3. Configure Connection String

Update appsettings.json with your Redis connection string:

{
  "Orleans": {
    "ClusteringSettings": {
      "ProviderType": "Redis",
      "Redis": {
        "ConnectionString": "localhost:6379",
        "Database": 0
      }
    }
  }
}

Configuration Options

Property Type Required Default Description
ConnectionString string Yes - Redis connection string (host:port or comma-separated for cluster)
Database int No 0 Redis database number (0-15)

Connection String Format

The connection string supports multiple formats:

  • Simple: localhost:6379
  • With Password: localhost:6379,password=YourPassword
  • Cluster: localhost:6379,localhost:6380,localhost:6381
  • Full: localhost:6379,password=YourPassword,abortConnect=false,connectTimeout=5000

Validation

The configuration is validated at startup: - ConnectionString must be provided - Database must be greater than or equal to 0

Health Checks

The template includes OrleansRedisClusteringHealthCheck which verifies: - Redis connectivity - Database accessibility - Ping response time

Troubleshooting

Common Issues

  1. Connection Failed
  2. Verify Redis server is running: redis-cli ping
  3. Check the connection string format
  4. Verify network connectivity and firewall rules

  5. Ensure Redis is accessible from the application host

  6. Authentication Failed

  7. Verify password is correct in connection string
  8. Check Redis AUTH configuration

  9. Ensure the connection string includes the password parameter

  10. Timeout Errors

  11. Increase connection timeout in connection string
  12. Check network latency between application and Redis

  13. Verify Redis server performance and load

  14. Database Not Found

  15. Redis databases are numbered 0-15 (default: 16 databases)
  16. Ensure the specified database number is valid
  17. Verify no other application is using the same database

Production Considerations

Redis High Availability

For production deployments, consider:

  1. Redis Sentinel - For high availability and automatic failover
  2. Redis Cluster - For horizontal scaling and sharding
  3. Azure Redis Cache - Managed Redis service on Azure
  4. AWS ElastiCache - Managed Redis service on AWS

Connection String for Production

{
  "Redis": {
    "ConnectionString": "your-redis-host:6379,password=YourSecurePassword,abortConnect=false,connectTimeout=5000,syncTimeout=5000",
    "Database": 0
  }
}

Performance Optimization

  1. Use dedicated Redis instances for Orleans clustering
  2. Configure appropriate memory limits and eviction policies
  3. Monitor Redis performance metrics
  4. Use connection pooling (handled automatically by StackExchange.Redis)
  5. Consider using Redis Cluster for large-scale deployments

Docker Compose Integration

The template includes Redis in the Docker Compose configuration. Ensure the Redis service is properly networked:

services:
  redis:
    image: redis:latest
    ports:
      - "6379:6379"
    networks:
      - microservice-network

  microservice:
    depends_on:
      - redis
    environment:
      - Orleans__Clustering__Redis__ConnectionString=redis:6379

Best Practices

  1. Use separate Redis databases for different environments
  2. Configure Redis persistence (RDB or AOF) for production
  3. Monitor Redis memory usage and set appropriate eviction policies
  4. Use Redis Sentinel or Cluster for high availability
  5. Secure Redis with authentication and network isolation
  6. Regularly backup Redis data in production

References