Configure Redis clustering for a Premium Azure Cache for Redis instance

Azure Cache for Redis offers Redis cluster as implemented in Redis. With Redis Cluster, you get the following benefits:

  • The ability to automatically split your dataset among multiple nodes.
  • The ability to continue operations when a subset of the nodes is experiencing failures or are unable to communicate with the rest of the cluster.
  • More throughput: Throughput increases linearly as you increase the number of shards.
  • More memory size: Increases linearly as you increase the number of shards.

Clustering doesn't increase the number of connections available for a clustered cache. For more information about size, throughput, and bandwidth with premium caches, see Choosing the right tier

In Azure, Redis cluster is offered as a primary/replica model where each shard has a primary/replica pair with replication, where the replication is managed by Azure Cache for Redis service.

Set up clustering

Clustering is enabled New Azure Cache for Redis on the left during cache creation.

  1. To create a premium cache, sign in to the Azure portal and select Create a resource. Besides creating caches in the Azure portal, you can also create them using Resource Manager templates, PowerShell, or Azure CLI. For more information about creating an Azure Cache for Redis, see Create a cache.

    Create resource.

  2. On the New page, select Databases and then select Azure Cache for Redis.

    Select Azure Cache for Redis.

  3. On the New Redis Cache page, configure the settings for your new premium cache.

    Setting Suggested value Description
    DNS name Enter a globally unique name. The cache name must be a string between 1 and 63 characters. The string can only contain numbers, letters, or hyphens. The name must start and end with a number or letter, and can't contain consecutive hyphens. Your cache instance's host name will be <DNS name>.redis.cache.windows.net.
    Subscription Drop-down and select your subscription. The subscription under which to create this new Azure Cache for Redis instance.
    Resource group Drop-down and select a resource group, or select Create new and enter a new resource group name. Name for the resource group in which to create your cache and other resources. By putting all your app resources in one resource group, you can easily manage or delete them together.
    Location Drop-down and select a location. Select a region near other services that will use your cache.
    Cache type Drop-down and select a premium cache to configure premium features. For details, see Azure Cache for Redis pricing. The pricing tier determines the size, performance, and features that are available for the cache. For more information, see Azure Cache for Redis Overview.
  4. Select the Networking tab or select the Networking button at the bottom of the page.

  5. In the Networking tab, select your connectivity method. For premium cache instances, you can connect either publicly, via Public IP addresses or service endpoints, or privately, using a private endpoint.

  6. Select the Next: Advanced tab or select the Next: Advanced button on the bottom of the page.

  7. In the Advanced tab for a premium cache instance, configure the settings for non-TLS port, clustering, and data persistence. To enable clustering, select Enable.

    Clustering toggle.

    You can have up to 10 shards in the cluster. After selecting Enable, slide the slider or type a number between 1 and 10 for Shard count and select OK.

    Each shard is a primary/replica cache pair managed by Azure, and the total size of the cache is calculated by multiplying the number of shards by the cache size selected in the pricing tier.

    Clustering toggle selected.

    Once the cache is created, you connect to it and use it just like a non-clustered cache. Redis distributes the data throughout the Cache shards. If diagnostics is enabled, metrics are captured separately for each shard and can be viewed in Azure Cache for Redis on the left.

  8. Select the Next: Tags tab or select the Next: Tags button at the bottom of the page.

  9. Optionally, in the Tags tab, enter the name and value if you wish to categorize the resource.

  10. Select Review + create. You're taken to the Review + create tab where Azure validates your configuration.

  11. After the green Validation passed message appears, select Create.

It takes a while for the cache to create. You can monitor progress on the Azure Cache for Redis Overview page. When Status shows as Running, the cache is ready to use.

Note

There are some minor differences required in your client application when clustering is configured. For more information, see Do I need to make any changes to my client application to use clustering?

For sample code on working with clustering with the StackExchange.Redis client, see the clustering.cs portion of the Hello World sample.

Change the cluster size on a running premium cache

To change the cluster size on a running premium cache with clustering enabled, select Cluster Size from the Resource menu.

Redis cluster size

To change the cluster size, use the slider or type a number between 1 and 10 in the Shard count text box. Then, select OK to save.

Increasing the cluster size increases max throughput and cache size. Increasing the cluster size doesn't increase the max. connections available to clients.

Note

Scaling a cluster runs the MIGRATE command, which is an expensive command, so for minimal impact, consider running this operation during non-peak hours. During the migration process, you will see a spike in server load. Scaling a cluster is a long running process and the amount of time taken depends on the number of keys and size of the values associated with those keys.

Clustering FAQ

The following list contains answers to commonly asked questions about Azure Cache for Redis clustering.

Do I need to make any changes to my client application to use clustering?

How are keys distributed in a cluster?

Per the Redis Keys distribution model documentation: The key space is split into 16384 slots. Each key is hashed and assigned to one of these slots, which are distributed across the nodes of the cluster. You can configure which part of the key is hashed to ensure that multiple keys are located in the same shard using hash tags.

  • Keys with a hash tag - if any part of the key is enclosed in { and }, only that part of the key is hashed for the purposes of determining the hash slot of a key. For example, the following three keys would be located in the same shard: {key}1, {key}2, and {key}3 since only the key part of the name is hashed. For a complete list of keys hash tag specifications, see Keys hash tags.
  • Keys without a hash tag - the entire key name is used for hashing, resulting in a statistically even distribution across the shards of the cache.

For best performance and throughput, we recommend distributing the keys evenly. If you're using keys with a hash tag, it's the application's responsibility to ensure the keys are distributed evenly.

For more information, see Keys distribution model, Redis Cluster data sharding, and Keys hash tags.

For sample code about working with clustering and locating keys in the same shard with the StackExchange.Redis client, see the clustering.cs portion of the Hello World sample.

What is the largest cache size I can create?

The largest cache size you can have is 1.2 TB. This will be a clustered P5 cache with 10 shards. For more information, see Azure Cache for Redis Pricing.

Do all Redis clients support clustering?

Many clients support Redis clustering but not all. Check the documentation for the library you're using to verify you're using a library and version that support clustering. StackExchange.Redis is one library that does support clustering, in its newer versions. For more information on other clients, see the Playing with the cluster section of the Redis cluster tutorial.

The Redis clustering protocol requires each client to connect to each shard directly in clustering mode, and also defines new error responses such as 'MOVED' na 'CROSSSLOTS'. When you attempt to use a client, which doesn't support clustering, with a cluster mode cache, the result can be many MOVED redirection exceptions, or just break your application, if you're doing cross-slot multi-key requests.

Note

If you're using StackExchange.Redis as your client, ensure you're using the latest version of StackExchange.Redis 1.0.481 or later for clustering to work correctly. For more information on any issues with move exceptions, see move exceptions.

How do I connect to my cache when clustering is enabled?

You can connect to your cache using the same endpoints, ports, and keys that you use when connecting to a cache that doesn't have clustering enabled. Redis manages the clustering on the backend so you don't have to manage it from your client.

Can I directly connect to the individual shards of my cache?

The clustering protocol requires the client to make the correct shard connections, so the client should make share connections for you. With that said, each shard consists of a primary/replica cache pair, collectively known as a cache instance. You can connect to these cache instances using the redis-cli utility in the unstable branch of the Redis repository at GitHub. This version implements basic support when started with the -c switch. For more information, see Playing with the cluster on https://redis.io in the Redis cluster tutorial.

For non-TLS, use the following commands.

Redis-cli.exe –h <<cachename>> -p 13000 (to connect to instance 0)
Redis-cli.exe –h <<cachename>> -p 13001 (to connect to instance 1)
Redis-cli.exe –h <<cachename>> -p 13002 (to connect to instance 2)
...
Redis-cli.exe –h <<cachename>> -p 1300N (to connect to instance N)

For TLS, replace 1300N with 1500N.

Can I configure clustering for a previously created cache?

Yes. First, ensure that your cache is premium by scaling it up. Next, you can see the cluster configuration options, including an option to enable cluster. Change the cluster size after the cache is created, or after you have enabled clustering for the first time.

Important

You can't undo enabling clustering. And a cache with clustering enabled and only one shard behaves differently than a cache of the same size with no clustering.

Can I configure clustering for a basic or standard cache?

Clustering is only available for premium caches.

Can I use clustering with the Redis ASP.NET Session State and Output Caching providers?

I'm getting MOVE exceptions when using StackExchange.Redis and clustering, what should I do?

If you're using StackExchange.Redis and receive MOVE exceptions when using clustering, ensure that you're using StackExchange.Redis 1.1.603 or later. For instructions on configuring your .NET applications to use StackExchange.Redis, see Configure the cache clients.

Next steps

Learn more about Azure Cache for Redis features.