How to configure Redis clustering for a Premium Azure Cache for Redis

Azure Cache for Redis has different cache offerings, which provide flexibility in the choice of cache size and features, including Premium tier features such as clustering, persistence, and virtual network support. This article describes how to configure clustering in a premium Azure Cache for Redis instance.

What is Redis Cluster?

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 does not 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.

Clustering

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

  1. To create a premium cache, sign in to the Azure portal and select Create a resource. In addition to 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 that contains only 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 click 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 click 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, click Enable.

    Clustering toggle.

    You can have up to 10 shards in the cluster. After clicking Enable, slide the slider or type a number between 1 and 10 for Shard count and click 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, and Redis distributes the data throughout the Cache shards. If diagnostics is enabled, metrics are captured separately for each shard and can be viewed in the Azure Cache for Redis blade.

  8. Select the Next: Tags tab or click 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, click 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 and click 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 3 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. This results in a statistically even distribution across the shards of the cache.

For best performance and throughput, we recommend distributing the keys evenly. If you are using keys with a hash tag it is 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 on 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 premium cache size is 120 GB. You can create up to 10 shards giving you a maximum size of 1.2TB GB. If you need a larger size you can request more. For more information, see Azure Cache for Redis Pricing.

Do all Redis clients support clustering?

Not all clients support Redis clustering! Please check the documentation for the library you are using, to verify you are using a library and version which 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'. Attempting to use a client that doesn't support clustering with a cluster mode cache can result in a lot of MOVED redirection exceptions, or just break your application, if you are doing cross-slot multi-key requests.

Note

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

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 does not 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 that the client make the correct shard connections. So the client should do this correctly 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 if is not. Next, you should be able to see the cluster configuration options, including an option to enable cluster. You can 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 am getting MOVE exceptions when using StackExchange.Redis and clustering, what should I do?

If you are using StackExchange.Redis and receive MOVE exceptions when using clustering, ensure that you are 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.