Choose a clustering policy for Azure Managed Redis

  • Applies to: ✅ Azure Managed Redis

Azure Managed Redis uses the Redis Enterprise architecture, which can run multiple Redis server processes, called shards, in parallel across its nodes. Sharding lets the service use more vCPUs at the same time, distribute primary and replica shards across nodes, and increase throughput as cache capacity grows. This design also supports capabilities such as self-healing and active geo-replication.

This architecture is a shift from the Basic, Standard, and Premium tiers of Azure Cache for Redis. Those tiers use the community edition of Redis and typically run one single-threaded Redis server process on each node. By using Azure Managed Redis, clustering and parallel shard execution are part of the default architecture rather than an optional scale-out feature. Smaller Azure Managed Redis instances might use only one shard, and the Non-clustered policy stores data without sharding, but all instances use the Redis Enterprise node architecture.

You choose which clustering policy the cache exposes to clients: OSS, Enterprise, or Non-clustered. The policy doesn't select the underlying Redis implementation. Instead, it determines whether clients connect directly to shards, connect through a managed proxy, or use an unsharded configuration. This choice affects client configuration, supported commands, performance, and whether you can change the policy later. Select the policy when you provision the cache, so make the decision before you create your instance.

This article compares the three policies at a conceptual level. It doesn't recommend a policy for a specific workload pattern, and it doesn't include performance numbers, because actual throughput and latency depend on your SKU, tier, and traffic profile.

What each policy changes

  • OSS clustering policy implements the Redis Cluster API. Clients that support the Cluster API connect directly to the shards that hold their data, instead of going through an intermediary. The client library is responsible for discovering shard locations and following redirections as data moves.
  • Enterprise clustering policy exposes a single endpoint for all client connections. A proxy process on the cache node routes each request to the correct shard internally. From the client's perspective, the cache looks like a single, nonclustered server.
  • Non-clustered policy stores data without sharding it across multiple Redis processes. It behaves like a traditional, single-process Redis server and only applies to smaller cache sizes.

For more information about the underlying architecture, see Clustering in Azure Managed Redis.

Compare the clustering policies

Aspect OSS Enterprise Non-clustered
Endpoint and routing model Client connects to shards directly, using the Cluster API to discover node locations. Client connects to a single endpoint; an internal proxy routes requests to shards. Client connects to a single, unsharded instance.
Client library requirement Requires a client library that supports the Redis Cluster API. Works with any standard Redis client library; no cluster-awareness required. Works with any standard Redis client library; no cluster-awareness required.
Performance characteristics Direct shard connections generally minimize latency and maximize throughput as shards and vCPUs increase. The single-node proxy can become a bottleneck for compute or network throughput compared to OSS. Can't take advantage of the multithreaded, multi-shard design of Redis Enterprise, so it's generally the least performant option.
Multikey commands and CROSSSLOT Keys in a multikey command must map to the same hash slot, or the command fails. Most multikey commands must target keys in the same slot; a small set of commands is allowed across slots. No slot-based restriction, because data isn't sharded.
RediSearch module Not supported. Required if you enable RediSearch. Not applicable; RediSearch isn't offered with Non-clustered caches.
Maximum cache size Available at all supported cache sizes. Available at all supported cache sizes. Limited to caches sized 25 GB and smaller.
Active geo-replication Supported. Supported. Supported.
Cluster-management commands Cluster-discovery commands required by cluster-aware clients, such as CLUSTER NODES, are available. Most commands that modify or directly manage cluster topology remain blocked because Azure manages the topology. Redis Cluster discovery and topology commands are blocked, including CLUSTER INFO, CLUSTER HELP, CLUSTER KEYSLOT, CLUSTER NODES, and CLUSTER SLOTS. Cluster-management commands aren't applicable because the cache isn't sharded.
Change the policy after creation No. Delete and re-create the cache to change to a different policy. No. Delete and re-create the cache to change to a different policy. Yes, you can move to a clustered policy after deployment, unless the cache is in an active geo-replication group.

Client library compatibility

All Redis client libraries can connect to an Azure Managed Redis instance that uses the Enterprise clustering policy, because the cache presents a single endpoint that looks nonclustered. If you choose the OSS clustering policy, confirm that your client library supports the Redis Cluster API, including following redirections as shards move. Most current versions of popular Redis client libraries support the Cluster API, but older or specialized libraries might not. For a list of commonly used client libraries, see Azure Managed Redis client libraries.

Azure manages cluster topology under every policy, so most commands that directly modify or manage the cluster remain blocked. The OSS clustering policy exposes the discovery commands that cluster-aware clients need to locate shards and route requests. The Enterprise policy doesn't expose the Redis Cluster API, so its cluster-discovery commands are also blocked. Because Microsoft manages cluster topology internally and the Enterprise policy presents the cache as if it were nonclustered, commands including CLUSTER INFO, CLUSTER HELP, CLUSTER KEYSLOT, CLUSTER NODES, and CLUSTER SLOTS are blocked when you use that policy. With the OSS clustering policy, cluster-aware client libraries use commands such as CLUSTER NODES to discover shard locations as a normal part of connecting to the cache; these aren't blocked. For the full list, see Blocked commands.

Client construction by library

The following examples show the high-level client API that selects a single-endpoint or cluster-aware topology. Select a client library name to open a complete Azure Managed Redis authentication example where one is available. Select a constructor to open the client's topology-specific connection guidance. A Non-clustered cache uses the same client form as the Enterprise policy because both present one endpoint to the client.

Client library Enterprise policy OSS policy Policy impact
StackExchange.Redis (.NET) ConnectionMultiplexer.ConnectAsync(options) ConnectionMultiplexer.ConnectAsync(options) Enterprise keeps a single-endpoint connection model. OSS requires no client-type change; ConnectionMultiplexer discovers the cluster topology and routes commands to shards.
Lettuce (Java) RedisClient.create(redisUri) RedisClusterClient.create(redisUri) Enterprise uses the standalone client and connection interfaces. OSS requires the cluster client and cluster connection interfaces.
Jedis (Java) RedisClient.builder().hostAndPort(host, 10000).build() RedisClusterClient.builder().nodes(nodes).build() Enterprise uses the single-endpoint client. OSS requires RedisClusterClient and the Azure Managed Redis endpoint as a seed node. Older Jedis versions use JedisCluster.
node-redis (Node.js) createClient({ url }) createCluster({ rootNodes: [{ url }] }) Enterprise uses the standard client. OSS requires the cluster constructor and the Azure Managed Redis endpoint as a root node.
ioredis (Node.js) new Redis(url) new Redis.Cluster([{ host, port: 10000 }]) Enterprise uses the standard client. OSS requires Redis.Cluster and the Azure Managed Redis endpoint as a startup node.
redis-py (Python) redis.Redis.from_url(url) RedisCluster.from_url(url) Enterprise uses the standard client. OSS requires RedisCluster to discover shards and handle redirections.
go-redis (Go) redis.NewClient(&redis.Options{Addr: endpoint}) redis.NewClusterClient(&redis.ClusterOptions{Addrs: []string{endpoint}}) Enterprise uses the standard client. OSS requires the cluster client and the Azure Managed Redis endpoint as a seed address.

The linked Azure Managed Redis examples for Lettuce, Jedis, node-redis, redis-py, and go-redis use cluster-aware clients. For Enterprise or Non-clustered, keep the authentication, TLS, and token-refresh configuration from the Azure Managed Redis example, but use the standard client shown in the Enterprise column. For OSS, combine that Azure Managed Redis configuration with the cluster guidance linked from the OSS column. The current Azure Managed Redis authentication samples don't include ioredis, so the ioredis links cover its generic connection and cluster setup.

For a production connection, also configure the hostname and port 10000, timeouts, retry behavior, and connection reuse or pooling. With OSS clustering, connect first to port 10000 and let the client discover the current shard ports. Don't hardcode the discovered ports in the 85XX range because they can change.

Endpoints and routing at a conceptual level

The comparison table summarizes the endpoint model for each policy. One operational detail to keep in mind: with the OSS clustering policy, node-level connection details can change as the service rebalances shards, so avoid hardcoding node addresses in your application. Instead, rely on your client library's cluster-discovery behavior, which uses commands such as CLUSTER NODES to find the current shard locations. With the Enterprise clustering policy, the proxy absorbs this complexity on the client's behalf, which is also why that policy blocks direct client use of cluster-topology commands.

Performance tradeoffs

The OSS clustering policy generally offers the best throughput and lowest latency, because clients connect directly to shards and avoid the extra network hop through a proxy. Throughput tends to scale as the number of shards and vCPUs increases. The Enterprise clustering policy trades some of that throughput ceiling for simplicity: because all requests funnel through a single proxy node, that node's compute and network capacity can become a limiting factor before the underlying shards do. The Non-clustered policy doesn't benefit from the multithreaded, multi-shard design that Redis Enterprise uses to parallelize work across vCPUs, so it's generally the least performant of the three options.

Exact throughput and latency depend on your SKU, performance tier, and traffic pattern. For guidance on benchmarking your own instance, see Performance testing with Azure Managed Redis.

Multikey commands and CROSSSLOT behavior

Because Azure Managed Redis instances use a clustered configuration internally, commands that operate on multiple keys can return a CROSSSLOT error depending on the clustering policy:

  • With the OSS clustering policy, all keys referenced in a multikey command must map to the same hash slot.
  • With the Enterprise clustering policy without active geo-replication, DEL, MSET, MGET, EXISTS, UNLINK, and TOUCH can operate across slots. Other multikey commands require keys to share a slot.
  • With the Enterprise clustering policy and active geo-replication, multikey write commands such as DEL, MSET, and UNLINK require keys to share a slot. Only MGET, EXISTS, and TOUCH can operate across slots.
  • With the Non-clustered policy, there's no slot-based restriction, because the data isn't sharded.

If your application issues multikey or transaction commands (such as MULTI) across arbitrary keys and can't guarantee those keys share a hash slot, factor that requirement into your clustering policy choice. For more information, see Multi-key commands.

RediSearch and module requirements

The RediSearch module, which underlies full-text search and vector search capabilities, requires the Enterprise clustering policy. You can't enable RediSearch with the OSS clustering policy or with a Non-clustered cache. RediSearch also requires the NoEviction eviction policy. If your workload needs search or vector search functionality, the clustering policy decision is effectively made for you. For more information, see Use Redis modules with Azure Managed Redis and Vector search in Azure Managed Redis.

Cache-size restrictions

As shown in the comparison table, the Non-clustered policy is capped at 25 GB. If you expect your data to grow beyond that size, either start with OSS or Enterprise, or plan to change the policy before you reach the limit. For more information, see Ability to change the policy later.

Active geo-replication considerations

Active geo-replication supports all three clustering policies, but every cache instance in a geo-replication group must share an identical configuration, including the clustering policy, SKU, capacity, eviction policy, and modules. This requirement exists because command consistency across the group, including avoiding CROSSSLOT failures, depends on all linked instances behaving the same way.

Because of this requirement, you can't change the clustering policy of a cache after it's added to a geo-replication group. If you're planning to use active geo-replication, confirm your clustering policy choice before you link any instances together. For more information, see Configure active geo-replication.

Migration compatibility

  • Migrating from Azure Cache for Redis Basic, Standard, or Premium tiers: these tiers are typically nonclustered. Move to the OSS clustering policy for better performance, but you might need to update your client library configuration to handle clustered responses. If your application can't tolerate a clustered topology, the Non-clustered policy is available for caches up to 25 GB.
  • Migrating from Azure Cache for Redis Enterprise: that service supports only the OSS and Enterprise clustering policies. Migrating to Azure Managed Redis with either of those policies preserves the equivalent clustering behavior. The Non-clustered policy has no equivalent on Azure Cache for Redis Enterprise.

For more information, see Understand differences before migrating from Basic, Standard, and Premium tiers and Understand differences before migrating from Azure Cache for Redis Enterprise.

Ability to change the policy later

Once you set the clustering policy to OSS or Enterprise at cache creation, you can't change it. To switch between OSS and Enterprise (or to move away from either of them), you must delete the cache and re-create it with the desired policy.

A cache created with the Non-clustered policy is the exception: you can update it to a clustered configuration after deployment, for example if you need to scale beyond the 25 GB Non-clustered size limit. This mutability doesn't apply if the Non-clustered cache is part of an active geo-replication group, because all instances in that group must keep an identical clustering configuration for as long as they're linked.

Decision flow

Use the following sequence to narrow down a clustering policy before you provision your cache:

  1. Does your workload require RediSearch (full-text search or vector search)? If yes, choose the Enterprise clustering policy. No other policy supports RediSearch.
  2. Do you expect the cache to grow beyond 25 GB, now or in the future? If yes, and RediSearch isn't required, choose OSS or Enterprise. The Non-clustered policy is capped at 25 GB.
  3. Does your client library support the Redis Cluster API, including cluster discovery and redirections? If yes, and your workload doesn't require RediSearch, the OSS clustering policy generally offers the best performance.
  4. Can your client library only connect as if to a single, nonclustered server? If so, choose the Enterprise clustering policy for broad compatibility without requiring cluster-aware client code.
  5. Does your application depend on multikey or transaction commands across arbitrary keys that can't be guaranteed to share a hash slot? If so, and your cache size will stay at or under 25 GB, consider the Non-clustered policy to avoid CROSSSLOT failures.
  6. Will this cache participate in active geo-replication? If so, confirm the clustering policy now. Every instance you plan to link into the geo-replication group must use the same policy, and you can't change it once instances are linked.

Pre-provisioning checklist

Before you create your Azure Managed Redis instance, confirm the following:

  • You identified whether you need RediSearch or vector search, because those features require the Enterprise clustering policy and the NoEviction eviction policy.
  • You confirmed whether your client library supports the Redis Cluster API, if you're considering the OSS clustering policy.
  • You estimated your cache size and confirmed it fits within the 25-GB limit if you're considering the Non-clustered policy, including headroom for future growth.
  • You reviewed whether your application issues multikey or transaction commands across keys that might not share a hash slot, and whether that's compatible with the OSS or Enterprise CROSSSLOT behavior.
  • You decided whether active geo-replication is part of your design, and if so, planned to use the same clustering policy, SKU, capacity, eviction policy, and modules across every instance in the group.
  • You understand that the OSS and Enterprise clustering policies are permanent for the life of the cache instance, while a Non-clustered cache (outside a geo-replication group) can later be updated to a clustered policy.
  • If you're migrating from Azure Cache for Redis, you reviewed the clustering behavior of your source tier to identify the closest equivalent policy in Azure Managed Redis.

Related content

  • Last updated on