Redis Cluster

In this guide, we will walk you through setting up your first database cluster running on Redis Cluster using ClusterControl. By the end of this tutorial, you will have a fully operational database cluster that you can monitor, manage, and scale using ClusterControl.

Redis is a high-performance, in-memory data store used for caching, key-value storage, messaging, and real-time data processing. It delivers microsecond-level speed because all data is stored in RAM. Redis supports flexible data structures such as strings, lists, hashes, sets, sorted sets, streams, and JSON (via modules), making it useful for workloads like session storage, API rate limiting, leaderboards, and real-time analytics.

In standalone mode, Redis runs with a single primary node (and optional replicas). This setup is simple but has limitations: write operations cannot scale beyond a single server, all data resides on one machine, and failover requires external tooling like Sentinel.

Redis Cluster addresses these limitations by distributing data across multiple nodes using hash-slot sharding, enabling horizontal scaling and higher throughput. It also provides built-in high availability through automatic failover, where replicas can promote themselves when a primary fails. With its decentralized architecture, Redis Cluster eliminates single points of failure and is suitable for large, production-grade deployments.

See also

• Redis Community Edition - Getting Started
• Redis Cluster Specification

Prerequisites

Ensure the following requirements are met before proceeding:

• ClusterControl should be installed and running. If not, follow the installation instructions in Quickstart or use the Installer Script.
• You need at least three hosts (bare-metal or virtual machines) installed with the supported operating system. See Operating System.
• SSH access to all servers involved.
• All nodes must have internet access during the deployment stage.
• NTP is configured and running on all hosts to ensure that all nodes in the cluster maintain synchronized time.

Architecture

Below is a simplified diagram of the final architecture:

flowchart TD
    A{{**Users/<br>clients/<br>apps**}} --> |RW| B[**192.168.40.191**<br>Redis Primary] & D[**192.168.40.193**<br>Redis Primary] & F[**192.168.40.195**<br>Redis Primary]
    A --> |RO| C[**192.168.40.192**<br>Redis Replica]
    A --> |RO| E[**192.168.40.194**<br>Redis Replica]
    A --> |RO| G[**192.168.40.196**<br>Redis Replica]
    B -.-> |replication| C
    D -.-> |replication| E
    F -.-> |replication| G
    B & C & D & E & F & G -.- | manages | X[/**ClusterControl<br>192.168.40.8**/]
    subgraph **Redis Cluster**
        subgraph **Shard 1**
            B
            C
        end
        subgraph **Shard 2**
            D
            E
        end
        subgraph **Shard 3**
            F
            G
        end
    end

Step 1: Set up SSH key-based authentication

1. On the ClusterControl server, generate a new SSH key:

ssh-keygen -t rsa

2. Copy the SSH key to all Redis nodes:

ssh-copy-id -i ~/.ssh/id_rsa [email protected]  # Primary 1
ssh-copy-id -i ~/.ssh/id_rsa [email protected]  # Replica 1
ssh-copy-id -i ~/.ssh/id_rsa [email protected]  # Primary 2
ssh-copy-id -i ~/.ssh/id_rsa [email protected]  # Replica 2
ssh-copy-id -i ~/.ssh/id_rsa [email protected]  # Primary 3
ssh-copy-id -i ~/.ssh/id_rsa [email protected]  # Replica 3

3. Test the connection:

ssh [email protected] "ls /root"
ssh [email protected] "ls /root"
ssh [email protected] "ls /root"
ssh [email protected] "ls /root"
ssh [email protected] "ls /root"
ssh [email protected] "ls /root"

Step 2: Deploy a Redis Cluster

1. Open your browser and navigate to your ClusterControl server’s IP or domain name.

2. From the ClusterControl dashboard, click on Deploy a cluster in the top-right corner and choose Create a database cluster.

3. Choose Redis Cluster from the Database dropdown and the Vendor and Version (e.g., "Redis" and "8") from the wizard. Click Continue.

4. In the Deploy Redis Cluster cluster wizard, configure the cluster as follows:

   (1) Cluster details(2) SSH configuration(3) Node configuration(4) Shard 1(5) Shard 2(6) Shard 3(7) Preview

   • Name: My Redis Cluster
   • Tags: redis, first-deployment

   • SSH user: root
   • SSH user key path: /root/.ssh/id_rsa
   • SSH port: 22
   • SSH sudo / OS elevation command: Choose either uses sudo(default) or doas or pbrun
   • Install software: Enabled
   • Disable firewall: Checked
   • Disable SELinux/AppArmor: Checked

   • Redis Port: 6379 (default)
   • Cluster bus port : 16379 (default)
   • Node timeout (ms): 15000 (default)
   • Replica validity factor: 10 (default)
   • Configuration template: redis8-tls.conf (default)
   • Repository: Use vendor repositories (default)
   • Username: Specify the Redis admin username. ClusterControl will create this user if not exists.
   • Password: Specify the password for the Redis admin user.

   • Primary node:
     • Specify "192.168.40.191" as the primary node and press Enter.
   • Replica node:
     • Specify "192.168.40.192" as replica and press Enter.
   • Wait until everything is green. If a red warning appears, inspect the error and fix it.
   • Click on Add another shard. This will add another step to add the second shard.

   • Primary node:
     • Specify "192.168.40.193" as the primary node and press Enter.
   • Replica node:
     • Specify "192.168.40.194" as replica and press Enter.
   • Wait until everything is green. If a red warning appears, inspect the error and fix it.
   • Click on Add another shard. This will add another step to add the third shard.

   • Primary node:
     • Specify "192.168.40.195" as the primary node and press Enter.
   • Replica node:
     • Specify "192.168.40.196" as replica and press Enter.
   • Wait until everything is green. If a red warning appears, inspect the error and fix it.
   • Click Continue.

   • Review the summary of your deployment. You can always go back to any previous section to modify your configurations if you wish. The deployment settings will be kept until you exit the deployment wizard.

5. Click Finish to begin the deployment.

6. ClusterControl will start to provision the hosts, install Redis, and configure replication. Monitor the progress from Activity Center → Jobs.

Step 3: Monitor your cluster

After the cluster has been deployed, you will be redirected to the Home page. This page provides an at-a-glance view of your cluster's status and important aspects of a database, including:

• Cluster health: The Home page provides the cluster state
• Node health: Rollover on the honeycomb diagram and get a more detailed view of a particular node. You can also see more detailed histograms under ClusterControl GUI → Clusters → choose the cluster → Dashboards.
• Recent alarms: View most recent alarms of your cluster.
• Automatic recovery status: Green means ClusterControl will raise an alarm and perform recovery procedures if it detects the database service is down. Red means ClusterControl will raise an alarm but the recovery procedures will be skipped.
• Topology viewer: Roll over on each cluster entry to see the summary of the cluster visualized in topology view to better understand your overall database state. Also available under ClusterControl GUI → Clusters → choose the cluster → Nodes → Topology.

Step 4: Connecting to the database cluster

At this point, your application should be able to access the database cluster via the following endpoints:

• Any primary Redis server (192.168.40.191, 192.168.40.193 or 192.168.40.195) on port 6379 for read-write workloads. In cluster-mode, the connection will be transparently follow redirects, even though the particular Redis node does not own the cluster slot.
• For read-only workloads, you may send the database connections to the replica nodes (192.168.40.192, 192.168.40.194 or 192.168.40.196) on port 6379.
• Since by default ClusterControl enforces Redis instance with TLS and authentication, you need to get the key and certificate (commonly under /var/lib/redis of the database node) and use the password specified during the deployment.

Note

Most of the Redis drivers and application connectors come with a built-in support for Redis replication, clusters and Sentinel. Check your application connector's documentation for details.

Tip

You can use popular Redis database management clients like phpRedisAdmin or Redis Insight to perform database administration tasks.

Step 5: Enable automatic backups

To ensure your cluster data is protected, you should schedule an automatic backup. For Redis Cluster, ClusterControl supports both RDB and AOF backups. To schedule a backup:

1. Go to ClusterControl GUI → choose the cluster → Backups to open the backup overview page of the cluster.
2. Go to Create Backup → Schedule a Backup to schedule an automated backup. It will open a backup wizard to follow.

3. In the Create a backup schedule wizard, configure the backup as below:

   (1) Configuration(2) Advanced settings(3) Storage(4) Schedule(5) Preview

   • Schedule name: Daily full backup - Redis
   • Cluster: (leave as it is)
   • Backup method: (leave as it is)
   • Upload backup to cloud: Off

   • Compression: On (default)
   • Compression level: 6
   • Use PIGZ for parallel gzip: Off
   • Enable encryption: On
   • Retention: On (default)

   • Storage location: Store on controller (default). You can choose the storage host from the drop down list.
   • Storage directory: /root/backups (default)
   • Backup subdirectory: BACKUP-%I (default)

   • Set backup schedule: Simple
   • Every: day at 2:00
   • Select timezone: Use your preferred timezone

   • Review the summary of the backup configuration. You can always go back to any previous section to modify your configurations if you wish. The backup configuration settings will be kept until you exit the wizard.

4. Click Create to schedule the backup.

Once configured, ClusterControl will take care of the automated backups, ensuring your data is safe. All successful backups will be listed in the Backups → All Backups page, where you can see the backup logs, size and perform restoration if necessary.

Step 6: Configure alerts

To keep track of any issues or incidents in your cluster, it's important to set up alerting. ClusterControl supports sending alarms and alerts to email, web hooks and third-party notification services like Slack or Telegram. In this example, we are going to use email.

Firstly, configure the mail server. Go to ClusterControl GUI → Settings → You don't have a mail server configured. Configure now → SMTP Server. Fill up all necessary information about the SMTP server. You can also opt for Sendmail, however a mail transfer agent (sendmail, postfix or exim) must be installed on the ClusterControl server.

Once configured, we can configure the alert and recipients as below:

1. Go to ClusterControl GUI → choose the cluster → Settings → Email Notifications.
2. Choose a user group where you are belong to from the User group dropdown.
3. Choose your email address to from the Users in the selected group dropdown.
4. Click Enable.
5. Set the Digest delivery time when you want a digested (summarized events) to be sent to you every day.
6. Set all Critical events to "Deliver" (default), all Warning events to "Digest" and you may ignore the Info events.

This ensures you are always notified when critical issues arise and can act quickly to resolve them. You will also get an email with summarized warning events every day at the configured delivery time.

Tip

You can also configure alarms to be sent to third-party notification systems (Slack, Telegram), incident management systems (PagerDuty, ServiceNow, OpsGenie) or web hooks. See Integration → Notification Services.

Step 7: Manage your cluster

ClusterControl provides many other features for managing your cluster, including:

• Database upgrades and patching: Perform rolling upgrades to keep your cluster up to date without downtime. This feature is available at ClusterControl GUI → choose the cluster → Actions → Upgrades.
• Database node management: Perform start/stop/restart node, reboot host, bootstrap cluster, activate/deactivate read-only, resync node, change primary source and rebuild replica. These features are available at ClusterControl GUI → choose the cluster → Nodes → Actions.
• Configuration management: Perform database configuration changes globally or on individual database node. This feature is available at ClusterControl GUI → choose the cluster → Manage 🡒 Configuration.
• Database user and access control management: Manage database users and privileges globally. This feature is available at ClusterControl GUI → choose the cluster → Manage → Access control.
• Backup management: Create, schedule, restore, upload backup to cloud, and set retention period. These features are available at ClusterControl GUI → choose the cluster → Backups → Actions and ClusterControl GUI → choose the cluster → Backups → More.
• Maintenance management: Activate, deactivate, remark and schedule maintenance mode for all nodes. This feature is available at ClusterControl GUI → choose the cluster → Nodes → Actions → Schedule maintenance.
• SSH console: Access your nodes directly from ClusterControl GUI via web SSH console. This feature is available at ClusterControl GUI → choose the cluster → Nodes → Actions → SSH Console.

Step 8: Scale your cluster

One of the key benefits of using ClusterControl is the ease of scaling your cluster. For Redis Cluster, you can scale out the cluster with another replica. Common use cases are to use the replica node for to scale out the read-only workloads, backups, reporting or analytics purposes.

Adding a new replica node is an online and non-blocking operation. It shall not cause downtime to the running cluster however expect increasing load on the source node due to initial RDB syncing from the primary.

ClusterControl assumes that the new node that you want to add meets the requirements as decribed under Prerequisites and configured with a proper SSH key-based authentication as shown under Step 1: Set up SSH key-based authentication.

1. To add a new replica, go to ClusterControl GUI → choose the cluster → Actions → Add new → Replica node.

2. In the Create a replica node wizard, configure the following:

   (1) Node Configuration(2) Add node(3) Preview

   • Port: 6379
   • Install software: On (default)
   • Disable firewall: Checked (default)
   • Disable SELinux/AppArmor: Checked (default)

   • Primary node: Choose one of the primary node from the dropdown.
   • Node: Specify the IP address or hostname of the node that you want to add and press Enter.

   • Review the summary of the deploymnent. You can always go back to any previous section to modify your configurations if you wish. The deployment configuration settings will be kept until you exit the wizard.

3. Click Finish to trigger the deployment job.

4. ClusterControl will start provisioning the new replica node. You can monitor the progress from Activity center, where you will see detailed logs of the deployment. This process can take a few minutes. Once the deployment is complete, the node will appear in the Nodes page.

Conclusion

Congratulations! You’ve successfully deployed, monitored, managed and scaled your first Redis Cluster using ClusterControl. From here, you can explore additional features such as failover management, access control list (ACL) rules, advanced monitoring, advanced backup management, database restore and many more. As you grow, ClusterControl will help ensure that your database infrastructure remains highly available and performant.