MongoDB Sharded Cluster

This guide will lead you through deploying your first MongoDB Sharded Cluster using ClusterControl. By the end, you'll have a production-ready sharded setup that’s scalable, fault-tolerant, and fully managed through ClusterControl.

A MongoDB sharded cluster is designed to scale horizontally by partitioning data across multiple shard nodes. Each shard can be a replica set to ensure high availability. ClusterControl automates the deployment, configuration, and ongoing management of a sharded cluster.

See also

• MongoDB Sharding Docs

Prerequisites

Make sure you have the following before you begin:

• ClusterControl should be installed and running. If not, follow the installation instructions in Quickstart or use the Installer Script.
• At least six hosts (bare-metal or virtual machines):
  • Three hosts for MongoDB shard replica sets (at least 2 nodes per shard)
  • Two config server nodes
  • One mongos router node (can share with ClusterControl)
• All nodes must have internet access during deployment.
• SSH key-based access from ClusterControl to all target hosts.
• NTP service must be enabled and synchronized on all nodes.

Architecture

flowchart LR
    Users[Clients / Apps] --> Mongos[192.168.99.200<br>Mongos Router]
    Mongos --> Shard1Primary[192.168.99.101<br>Shard1 Primary]
    Mongos --> Shard2Primary[192.168.99.103<br>Shard2 Primary]
    Shard1Primary --> Shard1Secondary[192.168.99.102]
    Shard2Primary --> Shard2Secondary[192.168.99.104]
    Mongos --> Config1[192.168.99.105<br>Config Server 1]
    Mongos --> Config2[192.168.99.106<br>Config Server 2]
    Mongos & Shard1Primary & Shard2Primary & Shard1Secondary & Shard2Secondary & Config1 & Config2 -.- |manages| ClusterControl
    subgraph "MongoDB Config"
        Config1
        Config2
    end
    subgraph "MongoDB Shards"
        Shard1Primary
        Shard2Primary
        Shard1Secondary
        Shard2Secondary
    end

Step 1: Set up SSH key-based authentication

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

   ssh-keygen -t rsa
   

2. Copy the SSH public key to all target nodes:

   ssh-copy-id -i ~/.ssh/id_rsa [email protected]  # Mongos Router
   ssh-copy-id -i ~/.ssh/id_rsa [email protected]  # Shard 1 Primary
   ssh-copy-id -i ~/.ssh/id_rsa [email protected]  # Shard 1 Secondary
   ssh-copy-id -i ~/.ssh/id_rsa [email protected]  # Shard 2 Primary
   ssh-copy-id -i ~/.ssh/id_rsa [email protected]  # Shard 2 Secondary
   ssh-copy-id -i ~/.ssh/id_rsa [email protected]  # Config Server 1
   ssh-copy-id -i ~/.ssh/id_rsa [email protected]  # Config Server 2
   

3. Test connectivity from the ClusterControl server to each host:

   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 MongoDB Sharded 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 "MongoDB Shards" from the Database dropdown and the appropriate Vendor and Version (e.g., "MongoDB" and "7.0") from the wizard. Click Continue.

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

   (1) Cluster details(2) SSH configuration(3) Node configuration(4) Add Configuration Servers & Routers(5) Add Shard(6) Preview

   • Name: Enter a name for your cluster (e.g., My First MongoDB Shard Cluster).
   • Tags: Enter one or more tags, separated by pressing "Enter" (e.g., production, replication, dc1).

   • SSH user: root
   • SSH user key path: /root/.ssh/id_rsa
   • SSH port: 22
   • SSH sudo password: (leave blank if using key-based auth)
   • Install software: On (default)
   • Disable firewall: Checked (default)
   • Disable SELinux/AppArmor: Checked (default)

   • Server port: 5432 (default)
   • Server data directory: /var/lib/mongodb
   • User: Enter MongoDB admin user eg: mongoadm
   • Password: Enter a secure password for the MongoDB admin
   • Router Configuration template: mongodb.conf.7.0.percona (default)
   • Repository: Use vendor repositories (default)
   • Enable SSL encryption: On (default)

   • Configuration Servers:
     • Specify "192.168.99.105" and "192.168.99.106" as the Configuration Servers and press Enter.
   • Router/Mongos node:
     • Specify "192.168.99.200" as Mongo Router and press Enter.
   • Wait until everything is green. If a red warning appears, inspect the error and fix it.
   • Proceed only if all nodes are reachable (shown in green).

   • Define shard name:
     • Specify the shard name for the First Shard.
   • Nodes Shard:
     • Specify "192.168.99.101" as Primary Shard and press Enter.
     • Specify "192.168.99.102" as Secondary/Replica Shard and press Enter.
   • Wait until everything is green. If a red warning appears, inspect the error and fix it.

   • Proceed only if all nodes are reachable (shown in green).

   • Define another shard name:

     • Press Add another shard and specify the shard name for the Second Shard.
   • Nodes Shard:
     • Specify "192.168.99.103" as Primary Shard and press Enter.
     • Specify "192.168.99.104" as Secondary/Replica Shard and press Enter.
   • Wait until everything is green. If a red warning appears, inspect the error and fix it.
   • Proceed only if all nodes are reachable (shown in green).

   • Review the summary. You can go back to modify any configuration. The settings persist until you exit the wizard.

5. Click Finish to start the deployment.

6. ClusterControl will provision your MongoDB Sharded Cluster. Monitor progress from Activity center. This process can take a few minutes. Once complete, the cluster appears on the Home page.

Step 3: Monitor your cluster

After deployment, the Home page provides an overview of your cluster's health, node status, alarms, automatic recovery status, and topology visualization.

Step 4: Schedule automatic backups

ClusterControl uses Percona Backup for MongoDB as default backup method for MongoDB Sharded Cluster. Before installing Percona Backup for MongoDB and configuring the backup, ensure that the servers have mounted the shared storage on all data nodes and config servers. The articles will not cover how to set up the NFS server and client.

To protect your data, set up automatic backups:

1. Go to ClusterControl → Clusters → choose the cluster → Backups to open the backup overview.

2. Go to Create Backup → Schedule a Backup. The backup wizard appears.

3. In the Create a backup schedule wizard:

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

   • Schedule name: Enter the backup name, eg: DailyBackup
   • Cluster: Auto selected by default.
   • Backup method: percona-backup-mongodb.

   We must install the PBM (Percona Backup for MongoDB) for the first setup. just Continue and fill the shared storage path directory.

   • Retention: 31 Days (default)
   • Enable encryption: Off (default)

   • Set backup schedule: Simple
   • Every: Your preferred time
   • Timezone: Your preferred timezone

   • Review and click Create

4. Click Create to set the backup schedule.

Step 5: Configure alerts and notifications

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 6 Connect to the cluster

Use the Mongo shell or your application driver:

mongosh -u <mongo_admin> -p <password> --authenticationDatabase admin --host 192.168.99.200

Check shard cluster status:

sh.status()

Step 7: Cluster management operations

ClusterControl supports:

• Adding/Remove shards
• Adding/remove mongos router & config server
• Add new nodes in shards
• Performing minor rolling upgrades
• Resyncing lagging nodes
• Manual or automatic failover
• Customizing MongoDB configuration
• Upgrading MongoDB versions
• Managing backup schedules and restores
• User and role management

All operations can be executed safely from the UI without logging into individual nodes.

Conclusion

You have successfully deployed a MongoDB Sharded Cluster using ClusterControl. Your cluster is now fault-tolerant, secure, and manageable through a unified interface.