Create Database Cluster

The Create Database Cluster feature in ClusterControl allows users to easily deploy new database clusters with just a few clicks, eliminating the complexities of manual database setup. This feature provides an intuitive workflow for configuring high-availability setups, replication, load balancing, and more.

With Create Database Cluster, you can:

Automatically deploy single or multi-node database clusters.
Configure the topology and replication mechanisms during deployment.
Fine-tune the database server with custom configuration template.
Configure encryption to improve security.

This feature ensures a streamlined process, making it simple for administrators to quickly set up robust, highly available database environments that are ready for production use. Whether you are a beginner or an experienced DBA, ClusterControl’s guided deployment process ensures consistency, reliability, and best practices in database management.

Support Matrix

The following database cluster types, vendors and topologies are supported:

Database	Vendor	Topology
MySQL	Percona, Oracle	Standalone, replication
MariaDB	MariaDB	Standalone, replication
Galera Cluster	MariaDB, Percona	Galera certification-based replication
MySQL Group Replication	Oracle	Single-primary, multi-primary
PostgreSQL	PostgreSQL, EnterpriseDB	Standalone, streaming replication, logical replication
TimescaleDB	TimescaleDB	Standalone, streaming replication
MongoDB	MongoDB, Percona, MongoDB Enterprise	Replica set, sharded cluster
Redis	Redis, Valkey	Sentinel, cluster
Microsoft SQL Server for Linux	Microsoft	Standalone, Always On availability group
Elasticsearch	Elastic	Single-node cluster, high-availability cluster
ClickHouse	ClickHouse	Standalone, replicated cluster, sharded cluster

Multi-threaded Deployment

Since the release of version 2.5.0, deployments for the following clusters have multi-threaded deployments. As of this period, the clusters supported are the following:

Galera Cluster
PostgreSQL
MySQL Replication clusters

This means that for these cluster types, package installations are parallelized during deployment, which can be noticeable in cluster deployment job logs.

Example

For example, when deploying a MySQL Replication Cluster, you shall notice the following in the deployment job logs (using ClusterControl CLI to highlight the parallelism):

$ s9s job --list --job-id 1111
ID   CID STATE    OWNER  GROUP  CREATED             RDY TITLE
1111   0 FINISHED admin2 admins 2026-08-01 23:44:08 100% Deploy MySQL Galera Cluster

$ s9s job --log --job-id 1111 | grep -iE 'parallel'
...
Setting up remaining 2 node(s) in parallel.
...
All 2 parallel node setup(s) completed successfully.
...

Prerequisites

There are prerequisites that need to be fulfilled prior to the deployment for all database clusters:

Make sure the target database nodes are running on a supported architecture platform and operating system. See Hardware and Operating System.
Passwordless SSH (SSH using key-based authentication) is configured from the ClusterControl node to all database nodes. See SSH Key-based Authentication.
Verify that sudo is working properly if you are using a non-root user. See Operating System User.

Common Wizard Steps

The Create Database Cluster wizard follows the same flow and step order for every database type listed in the Support Matrix above. Only the Node configuration and Add nodes steps have database-specific fields, and a small number of database types insert an extra step (HBA Rules, Extensions, Snapshot storage configuration) or a License note. These differences are documented per database type in Database-Specific Settings below.

ClusterControl GUIClusterControl CLITerraform Provider for ClusterControl

Opening the wizard

Go to ClusterControl GUI → Deploy a cluster → Create a database cluster and under the Database dropdown, choose your target database type (see the dropdown label listed at the start of each entry in Database-Specific Settings).
Choose a vendor from the Vendor dropdown. This will determine the version and package repository to use in the deployment.
Choose a major database version from the Version dropdown.
Click Continue.

Step 1: Cluster name and tags

You will be presented with a deployment wizard for your chosen database type. Specify the cluster name and tags. For cluster name, you may leave it blank and ClusterControl will generate a name for the cluster. For cluster tags, you can add multiple tags by pressing Enter or choose from any existing tags. Click Continue to proceed to the next step.

Tip

A proper tag configuration will help you group your database clusters and is commonly recommended in a large deployment.

PostgreSQL and PostgreSQL Logical only

If you choose "PostgreSQL Enterprise DB" as the vendor, this step also asks for the EDB repository token, which you can retrieve from here.

Step 2: SSH configuration

Under the SSH configuration section, specify the SSH credentials that ClusterControl should use to connect to the database nodes:

SSH user: The SSH user that ClusterControl will use to perform SSH to the database node. ClusterControl assumes that all database nodes are using the same SSH user.
SSH user key path: The SSH private key path that ClusterControl will use to perform SSH authentication to the database node. Relative path is not supported. The SSH private key must be physically secured and exist on the ClusterControl node.
SSH port: The SSH port that ClusterControl will use to perform SSH to the database node. ClusterControl assumes that all database nodes are using the same SSH port.
SSH sudo password: The sudo password if the SSH user requires a password for privilege escalation.
SSH sudo / OS elevation command: Select the OS command used to elevate user privileges for executing system-level operations. You can choose from sudo, doas, pbrun.
Install software: Toggling on (default) instructs ClusterControl to install the database software from the package repository during deployment. Toggling off skips the database installation part. In some cases, where you have a custom database build or in an offline environment without a proper offline repository set up, you may install the database server packages manually beforehand and set this option to off. ClusterControl will then skip the installation part and proceed to the database configuration part.
Disable firewall: Whether ClusterControl should disable firewall (iptables, ufw, firewalld) on the database node during deployment. It is recommended to use the default setting (checked). If unchecked, this configuration task will be skipped. If the firewall is enabled, ensure you have configured the necessary ports prior to this deployment otherwise there is a risk of failure deployment. See Firewall and Security Groups.
Disable SELinux/AppArmor: Whether ClusterControl should disable SELinux (Red Hat-based operating system) or AppArmor (Debian-based operating system). It is recommended to use the default setting (checked). If unchecked, ensure you have set a proper policy for the database-related processes and all of their dependencies.

Click Continue to proceed to the next step.

Step 3: Node configuration

Under the Node configuration section, specify the database credentials and configurations that ClusterControl shall use when deploying the cluster. The exact fields shown depend on the database type; see Database-Specific Settings for the full list for your chosen database.

Click Continue to proceed to the next step.

Step 4: Add nodes

Under the Add nodes section (labeled differently for some database types, e.g. Configuration Servers and Routers for MongoDB Sharded Cluster), specify the target database nodes and configure the topology you want to deploy. The exact fields depend on the database type; see Database-Specific Settings for the full list for your chosen database.

Note

You can only proceed to the next step if all of the specified nodes are reachable (shown in green).

Finishing the wizard

Some database types insert one extra step here before the Preview page (an HBA Rules step for PostgreSQL/PostgreSQL Logical, an Extensions step for PostgreSQL/PostgreSQL Logical/TimescaleDB, or a Snapshot storage configuration step for Elasticsearch). See Database-Specific Settings if your chosen database type has one.
Click Continue to proceed to the Preview page. In this section, you can see the summary of your deployment and if everything is correct, you may proceed to deploy the cluster by clicking Finish. 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.
ClusterControl will trigger a deployment job and the progress can be monitored under ClusterControl GUI → Activity Center → Jobs.

Every database type is created with the same s9s cluster --create command. Only --cluster-type, --nodes, --vendor, and a handful of type-specific flags change between database types. See Database-Specific Settings for a full working example per database type.

Every database type uses the same clustercontrol_db_cluster resource. Only db_cluster_type and a handful of type-specific arguments change between database types. See Database-Specific Settings for a full working example per database type.

Database-Specific Settings

MySQL Replication

Database dropdown value: "MySQL Replication"

A minimum of two nodes is required for MySQL/MariaDB replication. If only one database IP address or hostname is provided, ClusterControl will deploy it as a standalone MySQL/MariaDB server with binary log enabled.

The following vendors and versions are supported for a new deployment:

Oracle MySQL - 8.0 and 8.4.
Percona Server for MySQL - 8.0 and 8.4.
Percona Server for MySQL Pro - 8.0 and 8.4.
MariaDB Server - 10.5, 10.6, 10.11, 11.4, 11.8.

ClusterControl supports configuring either replication scheme - asynchronous or semisynchronous. It is possible to set up a primary-primary replication (circular replication) under the Add nodes section. You can also add more replicas later after the deployment is completed.

Default configuration

By default, ClusterControl deploys MySQL/MariaDB replication with the following configurations:

MySQL GTID with log_slave_updates enabled (MySQL and Percona only).
MariaDB GTID with log_slave_updates enabled (MariaDB only).
All database nodes will be configured with read_only=ON and super_read_only=ON (if supported) for protection against accidental write. The chosen primary will be promoted by disabling the read-only in the runtime.
The generated account credentials are stored inside secrets-backup.cnf under the MySQL configuration directory.

ClusterControl will create and grant necessary privileges for the following database users:

Database user	Purpose
`cmon`	Management and automation.
`cmonexporter`	Prometheus exporter for database monitoring.
`cmonagent`	ClusterControl query monitoring agent.
`cmon_replication`	MySQL/MariaDB replication.
`backupuser`	Backup and restore management.

If you would like to customize the above configurations, modify the template base file to suit your needs before proceeding to the deployment. See Configuration Template for details.

Attention

ClusterControl sets read_only=ON on all slaves but a privileged user (SUPER) can still write to a slave (except for MySQL versions that support super_read_only).

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
Server data directory: The database server data directory path that ClusterControl shall configure on all database nodes. If the path does not exist, ClusterControl will create and configure it automatically.
Admin/Root user: The database admin username that ClusterControl shall configure on all database nodes. This user will be granted global SUPER privilege and the GRANT option for localhost only.
Admin/Root password: The password for Admin/Root user.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.
Configuration template: The dropdown loads all MySQL configuration template files under /etc/cmon/templates or /usr/share/cmon/templates of the ClusterControl node for this cluster type. Choose one configuration template for the deployment. See Configuration Template.
Enable SSL encryption: Toggling on (default) instructs ClusterControl to configure database SSL encryption for both client-server and replication. Toggling off skips this step.
Semi-synchronous replication: Toggling on (default) instructs ClusterControl to configure semi-synchronous replication. Toggling off instructs ClusterControl to configure asynchronous replication.

Add nodes fields

Primary node: Specify the IP address or hostname of the primary database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. Only one primary node is allowed for single-primary replication. If you want to configure a multi-primary replication (circular replication), toggle on Use multi-primary replication.
Replica nodes: Specify the IP address or hostname of the replica database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. You can specify zero or more replica nodes.
Use multi-primary replication: Toggling off (default) instructs ClusterControl to create the replication cluster as a single-primary replication. Toggling on opens another set of Primary node and Replica nodes form fields to be filled in for multi-primary replication. ClusterControl will set up the secondary primary node using circular replication but with read-only enabled.

CLI and Terraform examples

ClusterControl CLITerraform Provider for ClusterControl

Create a three-node Oracle MySQL replication 8.0, with operating system user "ubuntu" (the first node is the primary):

s9s cluster --create \
    --cluster-type=mysqlreplication \
    --nodes="10.10.10.11;10.10.10.12;10.10.10.13" \
    --vendor=oracle \
    --provider-version=8.0 \
    --db-admin-passwd='mYpa$$word' \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_rsa \
    --cluster-name='PROD - MySQL Replication 8.0'

Create a four-node MariaDB 11.4 multi-primary replication, using operating system user "root", with multiple primaries and replicas (note the ? sign to identify the node’s role in the --nodes parameter, where the second primary will be a backup-primary) and let the deployment job run in the foreground:

s9s cluster --create \
    --cluster-type=mysqlreplication \
    --nodes="192.168.5.11?master;192.168.5.12?slave;192.168.7.11?master;192.168.7.12?slave" \
    --vendor=mariadb \
    --provider-version=11.4 \
    --db-admin-passwd='Str0ngpa$$w0rd' \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --cluster-name='System A - MariaDB 11.4' \
    --wait

Deploy a 3-node Percona Server for MySQL replication 8.0 with semi-synchronous replication, with operating system user "ubuntu" (the first node will be the primary):

resource "clustercontrol_db_cluster" "my-replication-cluster" {

    db_cluster_create = true
    db_cluster_name = "PROD - MySQL Replication 8.0"
    db_cluster_type = "replication"
    db_version = "8.0"
    db_vendor = "percona"
    db_admin_user_password = var.cc_api_user_password
    db_host {
        hostname = "10.10.10.11"
        hostname_internal = "db1.mydb.local"
    }
    db_host {
        hostname = "10.10.10.12"
        hostname_internal = "db2.mydb.local"
    }
    db_host {
        hostname = "10.10.10.13"
        hostname_internal = "db3.mydb.local"
    }
    ssh_key_file = "/home/ubuntu/.ssh/id_rsa"
    ssh_user = "ubuntu"
    db_deploy_agents = true
    disable_firewall = true
    disable_selinux = true
    db_install_software = true
    db_semi_sync_replication = true

}

MySQL Galera

Database dropdown value: "MySQL Galera"

A minimal setup is comprised of one Galera node (no high availability, but this can later be scaled with more nodes). However, a minimum of 3 nodes is recommended for high availability. Garbd (an arbitrator) can be added later after the deployment completes.

The following vendors and versions are supported for a new deployment:

Percona XtraDB Cluster - 8.0 and 8.4.
Percona XtraDB Cluster Pro - 8.4.
MariaDB Cluster - 10.5, 10.6, 10.11, 11.4 and 11.8.

Default configuration

By default, ClusterControl deploys Galera Cluster with the following configurations:

Use xtrabackup-v2 or mariabackup (depending on the vendor chosen) for wsrep_sst_method.
Binary logging is enabled.
The generated account credentials are stored inside secrets-backup.cnf under the MySQL configuration directory.

ClusterControl will create and grant necessary privileges for the following database users:

Database user	Purpose
`cmon`	Management and automation.
`cmonexporter`	Prometheus exporter for database monitoring.
`cmonagent`	ClusterControl query monitoring agent.
`cmon_replication`	MySQL/MariaDB replication.
`backupuser`	Galera SST, backup and restore management.

If you would like to customize the above configurations, modify the template base file to suit your needs before proceeding to the deployment. See Configuration Template for details.

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
Server data directory: The database server data directory path that ClusterControl shall configure on all database nodes. If the path does not exist, ClusterControl will create and configure it automatically.
Admin/Root user: The database admin username that ClusterControl shall configure on all database nodes. This user will be granted global SUPER privilege and the GRANT option for localhost only.
Admin/Root password: The password for Admin/Root user.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.
Version: Choose a supported minor version from the dropdown. If ignored, ClusterControl will install the latest minor version of the current major version available at the moment.
Configuration template: The dropdown loads all MySQL configuration templates file under /etc/cmon/templates or /usr/share/cmon/templates of the ClusterControl node for this cluster type. Choose one configuration template for the deployment. See Configuration Template.
Enable SSL encryption: Toggling on (default) instructs ClusterControl to configure database SSL encryption for both client-server and replication. Toggling off skips this step. This option is ignored if the chosen vendor is Percona. Percona XtraDB Cluster 8.0 enables SSL by default regardless of this setting.

Add nodes fields

Galera nodes: Specify the IP address or hostname of the database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. A minimum of 3 nodes is recommended, and try to stick with an odd number of nodes in total to avoid a split-brain situation.

CLI and Terraform examples

ClusterControl CLITerraform Provider for ClusterControl

Create a three-node Percona XtraDB Cluster 8.0, with operating system user "ubuntu":

s9s cluster --create \
    --cluster-type=galera \
    --nodes="10.10.10.101;10.10.10.102;10.10.10.103" \
    --vendor=percona \
    --provider-version=8.0 \
    --db-admin-passwd='mYpa$$word' \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_rsa \
    --cluster-name='Percona XtraDB Cluster 8.0'

Create a three-node MariaDB Cluster 11.4 and let the deployment job run in the foreground:

s9s cluster --create \
    --cluster-type=galera \
    --nodes="192.168.5.11;192.168.5.12;192.168.5.13" \
    --vendor=mariadb \
    --provider-version=11.4 \
    --db-admin-passwd='Str0ngpa$$w0rd' \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --cluster-name='System A - MariaDB Cluster 11.4' \
    --wait

Deploy a 3-node Percona XtraDB Cluster 8.0, with operating system user "ubuntu":

resource "clustercontrol_db_cluster" "my-galera-cluster" {

    db_cluster_create = true
    db_cluster_name = "Percona XtraDB Cluster 8.0"
    db_cluster_type = "galera"
    db_version = "8.0"
    db_vendor = "percona"
    db_admin_user_password = var.cc_api_user_password
    db_host {
        hostname = "10.10.10.101"
    }
    db_host {
        hostname = "10.10.10.102"
    }
    db_host {
        hostname = "10.10.10.103"
    }
    ssh_key_file = "/home/ubuntu/.ssh/id_rsa"
    ssh_user = "ubuntu"
    db_deploy_agents = true
    disable_firewall = true
    disable_selinux = true
    db_install_software = true

}

MySQL Group Replication

Database dropdown value: "MySQL Group Replication"

A minimal setup is comprised of one node (no high availability - can be scaled later with more nodes). A recommended setup should have a minimum of 3 nodes for high availability.

The following vendors and versions are supported for a new deployment:

Oracle MySQL Group Replication - 8.0 and 8.4.

Default configuration

By default, ClusterControl deploys Group Replication Cluster with the following configurations:

By default, Clustercontrol parameter auto_manage_readonly is set to false.
Set loose-group_replication_single_primary_mode=OFF, which means it is configured for multi-primary mode by default.
Additional my.cnf settings:
- loose-group_replication_exit_state_action=ABORT_SERVER
- loose-group_replication_ssl_mode=REQUIRED
- loose-group_replication_recovery_use_ssl=ON
Binary logging is enabled.
The generated account credentials are stored inside secrets-backup.cnf under the MySQL configuration directory.

ClusterControl will create and grant necessary privileges for the following database users:

Database user	Purpose
`cmon`	Management and automation.
`cmonexporter`	Prometheus exporter for database monitoring.
`cmonagent`	ClusterControl query monitoring agent.
`rpl_user`	MySQL group replication.
`backupuser`	Backup and restore management.

If you would like to customize the above configurations, modify the template base file to suit your needs before proceeding to the deployment. See Configuration Template for details.

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
Server data directory: The database server data directory path that ClusterControl shall configure on all database nodes. If the path does not exist, ClusterControl will create and configure it automatically.
Admin/Root user: The database admin username that ClusterControl shall configure on all database nodes. This user will be granted global SUPER privilege and the GRANT option for localhost only.
Admin/Root password: The password for Admin/Root user.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.
Version: Choose a supported minor version from the dropdown. If ignored, ClusterControl will install the latest minor version of the current major version available at the moment.
Configuration template: The dropdown loads all MySQL configuration templates file under /etc/cmon/templates or /usr/share/cmon/templates of the ClusterControl node for this cluster type, by default ClusterControl uses my.cnf.grouprepl template. Choose one configuration template for the deployment. See Configuration Template.
Enable SSL encryption: Toggling on (default) instructs ClusterControl to configure database SSL encryption for both client-server and replication. Toggling off skips this step. This option is ignored if the chosen vendor is Percona. Percona XtraDB Cluster 8.0 enables SSL by default regardless of this setting.

Add nodes fields

Node: Specify the IP address or hostname of the database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. A minimum of 3 nodes is recommended, and try to stick with an odd number of nodes in total to avoid losing quorum.

CLI and Terraform examples

ClusterControl CLITerraform Provider for ClusterControl

Create a three-node Oracle MySQL Group Replication Cluster 8.0, with operating system user "ubuntu":

s9s cluster --create \
    --cluster-type=group_replication \
    --nodes="192.168.40.194;192.168.40.195;192.168.40.196" \
    --vendor=oracle \
    --provider-version=8.0 \
    --db-admin='root' \
    --db-admin-passwd='mydbPassw0rd' \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_rsa \
    --cluster-name='My Group Replication Cluster v8.0'

Deploy a 3-node MySQL Group Replication Cluster 8.0, with operating system user "ubuntu":

resource "clustercontrol_db_cluster" "my-group-replication-cluster" {

    db_cluster_create = true
    db_cluster_name = "MySQL Group Replication Cluster 8.0"
    db_cluster_type = "group_replication"
    db_version = "8.0"
    db_vendor = "oracle"
    db_admin_user_password = var.cc_api_user_password
    db_host {
        hostname = "192.168.40.194"
    }
    db_host {
        hostname = "192.168.40.195"
    }
    db_host {
        hostname = "192.168.40.196"
    }
    ssh_key_file = "/home/ubuntu/.ssh/id_rsa"
    ssh_user = "ubuntu"
    db_deploy_agents = true
    disable_firewall = true
    disable_selinux = true
    db_install_software = true

}

PostgreSQL Streaming

Database dropdown value: "PostgreSQL Streaming"

A minimum of two nodes is required for PostgreSQL streaming replication. If only one database IP address or hostname is provided, ClusterControl will deploy it as a standalone PostgreSQL server. The following vendors and versions are supported for a new deployment:

PostgreSQL from postgresql.org repository - 14, 15, 16, 17 and 18.
PostgreSQL from EDB repository - 14, 15, 16 and 17 (requires a valid EDB repository token).

Default configuration

By default, ClusterControl deploys PostgreSQL instances with the following configurations:

Configure and load the pg_stat_statements module.
The WAL level is set to replica.
All replica will be set with hot_standby.
Configure the cluster_name value.
ClusterControl will configure the PostgreSQL instance with SSL encryption for client-server connections.

ClusterControl will create and grant necessary privileges for the following database users:

Database user	Purpose
`cmon`	Management and automation.
`cmonexporter`	Prometheus exporter for database monitoring.
`cmonagent`	ClusterControl query monitoring agent.
`cmon_replication`	PostgreSQL streaming replication.
`backupuser`	Backup and restore management.

Tip

ClusterControl supports pgvector and PostGIS extensions which can be enabled with our PostgreSQL deployment wizard through an additional Extensions step, inserted after Add nodes and before Preview (see Common Wizard Steps). Once the cluster is deployed, you will need to enable the extension by using the CREATE EXTENSION statement.

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
Server data directory: The database server data directory path that ClusterControl shall configure on all database nodes. If the path does not exist, ClusterControl will create and configure it automatically. If blank, ClusterControl will use the default path.
User: The database admin username that ClusterControl shall configure on all database nodes. This user will be granted global SUPERUSER role and allowed for localhost only.
Password: The password for User.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.
Configuration template: The dropdown loads all PostgreSQL configuration template files under /etc/cmon/templates or /usr/share/cmon/templates of the ClusterControl node for this cluster type. Choose one configuration template for the deployment. See Configuration Template.
Enable SSL encryption: Toggling on (default) instructs ClusterControl to configure database SSL encryption for both client-server and replication. Toggling off skips this step.
Additional HBA rules: Defaults to None, ClusterControl's built-in rules only; no additional entries are appended to pg_hba.conf. Pick a rule set to append a pre-defined group of rules from /etc/cmon/templates/. Choose Custom to define the rules yourself in the next wizard step. These custom rules can be edited later from Database Users and Privileges.

Extra step: HBA Rules

If you chose Custom for Additional HBA rules in the Node configuration step, an HBA Rules section is shown next, before Add nodes:

Click Add HBA Rule to define a new rule. The list is empty until you add one, with columns Type, Database, User, Address, Method, Info, and Action.
Type: The connection type this rule applies to. Default host (matches any TCP/IP connection). Other options are hostssl (SSL-only), hostnossl (non-SSL only), and local (Unix domain socket connections; no address required).
Database: The database name this rule applies to. Default all (matches any database). Use sameuser to match a database with the same name as the connecting user, or enter a specific database name.
User: The database user this rule applies to. Default all (matches any user), or enter a specific username.
Address: The client IP address or CIDR range this rule applies to, for example 192.168.1.0/24 or 0.0.0.0/0 for all. Not applicable for the local connection type. Empty by default.
Method: The authentication method. Default scram-sha-256. scram-sha-256 and md5 require a password, trust allows connections without a password, reject unconditionally denies the connection, peer uses the OS user name (local connections only), and cert uses SSL client certificates.

As you configure a rule, a live Preview message summarizes it in plain language, for example "Allow TCP connections from any address to any database for any user, using SCRAM-SHA-256 password authentication" or "Allow local Unix-socket connections to database 'db1' for user 'user1', using SCRAM-SHA-256 password authentication." The same text is shown when hovering over the info icon in the Info column once the rule is added to the list.

Rules are appended to pg_hba.conf in the order shown in the list, after PostgreSQL's built-in default rules and ClusterControl's replication and controller access entries. Use the ⋮ menu in the Action column to Move to top, Move to bottom, Move up, Move down, Edit, or Delete a rule.

Check Save these rules as rule set to have the controller save the rules above as /etc/cmon/templates/pg_hba.conf.<name> during this deployment, so other users see the rule set in the Additional HBA rules dropdown on their next deployment. If a rule set with the same name already exists, a numeric suffix (.1, .2, …) is appended.

Add nodes fields

Primary node: Specify the IP address or hostname of the primary database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. Only one primary node is allowed for single-primary replication.
Replica nodes: Specify the IP address or hostname of the replica database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. You can specify zero or more replica nodes.
- Synchronous Replication: Toggling off (default) instructs ClusterControl to skip synchronous replication. Toggling on instructs ClusterControl to configure synchronous replication to the corresponding replica. You can have a mix of synchronous and asynchronous replication for multiple replicas in a cluster.

CLI and Terraform examples

ClusterControl CLITerraform Provider for ClusterControl

Create a three-node PostgreSQL 16 streaming replication, with operating system user "ubuntu" (the first node is the primary) with tags production and postgres:

s9s cluster --create \
    --cluster-type=postgresql \
    --nodes="10.10.10.11;10.10.10.12;10.10.10.13" \
    --vendor=postgresql \
    --provider-version=16 \
    --db-admin='postgres' \
    --db-admin-passwd='mYpa$$word' \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_rsa \
    --with-tags='production;postgres' \
    --cluster-name='PostgreSQL 16 - Streaming Replication'

Create a four-node PostgreSQL EDB 16 streaming replication, using operating system user "root" (the first node is the primary) and let the deployment job run in the foreground:

s9s cluster --create \
    --cluster-type=postgresql \
    --nodes="192.168.5.11;192.168.5.12;192.168.5.13;192.168.5.14" \
    --vendor=enterprisedb \
    --provider-version=11.4 \
    --db-admin='postgres' \
    --db-admin-passwd='Str0ngpa$$w0rd' \
    --enterprise-token='XXXXXXXXXXXXXXXXXXXXXXXXX' \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --cluster-name='System A - PostgreSQL EDB 16 - Streaming Replication' \
    --wait

Deploy a 3-node PostgreSQL streaming replication 16.0, with operating system user "ubuntu" (the first node will be the primary):

resource "clustercontrol_db_cluster" "my-postgresql-cluster" {

    db_cluster_create = true
    db_cluster_name = "PostgreSQL Streaming Replication 16"
    db_cluster_type = "postgresql"
    db_version = "16"
    db_vendor = "postgresql"
    db_admin_user_password = var.cc_api_user_password
    db_host {
        hostname = "10.10.10.11"
    }
    db_host {
        hostname = "10.10.10.12"
    }
    db_host {
        hostname = "10.10.10.13"
    }
    ssh_key_file = "/home/ubuntu/.ssh/id_rsa"
    ssh_user = "ubuntu"
    db_deploy_agents = true
    disable_firewall = true
    disable_selinux = true
    db_install_software = true

}

PostgreSQL Logical

Database dropdown value: "PostgreSQL Logical"

Deploys a new PostgreSQL logical replication cluster from ClusterControl. A PostgreSQL logical cluster is built up of multiple PostgreSQL streaming clusters. Logical replication occurs between these streaming clusters, and each streaming cluster can have both publications and subscriptions. A minimum of two nodes is required for PostgreSQL logical replication, which is represented in the Cluster 1 and Cluster 2 sections under Add Nodes. Cluster 1 can be the target publisher and Cluster 2 can be the target subscriber (or vice versa). Multi-primary replication is possible by configuring two-way publication and subscription links of the same supported database objects.

The following vendors and versions are supported for a new deployment:

PostgreSQL from postgresql.org repository - 16, 17 and 18.
PostgreSQL from EDB repository - 16, 17 and 18 (requires a valid EDB repository token).

Default configuration

By default, ClusterControl deploys PostgreSQL instances with the following configurations:

Configure and load the pg_stat_statements module.
The WAL level is set to logical.
Configure the cluster_name value.
ClusterControl will configure the PostgreSQL instance with SSL encryption for client-server connections.

ClusterControl will create and grant necessary privileges for the following database users:

Database user	Purpose
`cmon`	Management and automation.
`cmonexporter`	Prometheus exporter for database monitoring.
`cmonagent`	ClusterControl query monitoring agent.
`cmon_replication`	PostgreSQL streaming replication.
`cmon_logical_replication`	PostgreSQL logical replication.
`backupuser`	Backup and restore management.

Tip

ClusterControl supports pgvector and PostGIS extensions which can be enabled with our PostgreSQL deployment wizard through an additional Extensions step, inserted after Add nodes and before Preview (see Common Wizard Steps). Once the cluster is deployed, you will need to enable the extension by using the CREATE EXTENSION statement.

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
Server data directory: The database server data directory path that ClusterControl shall configure on all database nodes. If the path does not exist, ClusterControl will create and configure it automatically. If blank, ClusterControl will use the default path.
User: The database admin username that ClusterControl shall configure on all database nodes. This user will be granted global SUPERUSER role and allowed for localhost only.
Password: The password for User.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.
Configuration template: The dropdown loads all PostgreSQL configuration template files under /etc/cmon/templates or /usr/share/cmon/templates of the ClusterControl node for this cluster type. Choose one configuration template for the deployment. See Configuration Template.
Enable SSL encryption: Toggling on (default) instructs ClusterControl to configure database SSL encryption for both client-server and replication. Toggling off skips this step.
Additional HBA rules: Defaults to None, ClusterControl's built-in rules only; no additional entries are appended to pg_hba.conf. Pick a rule set to append a pre-defined group of rules from /etc/cmon/templates/. Choose Custom to define the rules yourself in the next wizard step. These custom rules can be edited later from Database Users and Privileges.

Extra step: HBA Rules

Identical to the HBA Rules step documented for PostgreSQL Streaming above — shown only if you chose Custom for Additional HBA rules.

Add nodes fields

The Add nodes section is split into two blocks, Cluster 1 and Cluster 2, each with the same fields:

Primary node: Specify the IP address or hostname of the primary database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. Only one primary node is allowed for single-primary replication.
Replica nodes: Specify the IP address or hostname of the replica database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. You can specify zero or more replica nodes.
- Synchronous Replication: Toggling off (default) instructs ClusterControl to skip synchronous replication. Toggling on instructs ClusterControl to configure synchronous replication to the corresponding replica. You can have a mix of synchronous and asynchronous replication for multiple replicas in a cluster.

CLI and Terraform examples

ClusterControl CLITerraform Provider for ClusterControl

Create a two-node PostgreSQL 16 logical replication, with operating system user "ubuntu" (the first node is the primary) with tags production and postgres:

s9s cluster --create \
    --cluster-type=postgresql_logical \
    --nodes="10.10.10.11;10.10.10.12" \
    --vendor=postgresql \
    --provider-version=16 \
    --db-admin='postgres' \
    --db-admin-passwd='mYpa$$word' \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_rsa \
    --with-tags='production;postgres' \
    --cluster-name='PostgreSQL 16 - Logical Replication'

Create a two-node PostgreSQL EDB 16 logical replication, using operating system user "root" (the first node is the primary) and let the deployment job run in the foreground:

s9s cluster --create \
    --cluster-type=postgresql_logical \
    --nodes="192.168.5.11;192.168.5.12;" \
    --vendor=enterprisedb \
    --provider-version=11.4 \
    --db-admin='postgres' \
    --db-admin-passwd='Str0ngpa$$w0rd' \
    --enterprise-token='XXXXXXXXXXXXXXXXXXXXXXXXX' \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --cluster-name='System A - PostgreSQL EDB 16 - Logical Replication' \
    --wait

Deploy a 2-node PostgreSQL logical replication 17.0, with operating system user "ubuntu" (the first node will be the primary):

resource "clustercontrol_db_cluster" "my-postgresql-cluster" {

    db_cluster_create = true
    db_cluster_name = "PostgreSQL Logical Replication 16"
    db_cluster_type = "postgresql_logical"
    db_version = "17"
    db_vendor = "postgresql"
    db_admin_user_password = var.cc_api_user_password
    db_host {
        hostname = "10.10.10.11"
    }
    db_host {
        hostname = "10.10.10.12"
    }
    ssh_key_file = "/home/ubuntu/.ssh/id_rsa"
    ssh_user = "ubuntu"
    db_deploy_agents = true
    disable_firewall = true
    disable_selinux = true
    db_install_software = true

}

TimescaleDB

Database dropdown value: "TimescaleDB"

Deploys a new TimescaleDB standalone or streaming replication cluster from ClusterControl. A minimum of two nodes is required for TimescaleDB streaming replication. If only one database IP address or hostname is provided, ClusterControl will deploy it as a standalone TimescaleDB server. The following vendors and versions are supported for a new deployment:

TimescaleDB - 14, 15, 16, 17 and 18.

Default configuration

By default, ClusterControl deploys TimescaleDB with the following configurations:

Configure and load the pg_stat_statements module and timescaledb extension.
The WAL level is set to replica.
All replica will be set with hot_standby.
Configure the cluster_name value.
ClusterControl will configure the PostgreSQL instance with SSL encryption for client-server connections.

ClusterControl will create and grant necessary privileges for the following database users:

Database user	Purpose
`cmon`	Management and automation.
`cmonexporter`	Prometheus exporter for database monitoring.
`cmonagent`	ClusterControl query monitoring agent.
`cmon_replication`	PostgreSQL streaming replication.
`backupuser`	Backup and restore management.

Note

You can also deploy a PostgreSQL and convert it to TimescaleDB at a later stage. However, this action will be irreversible and ClusterControl will treat the cluster as TimescaleDB onwards.

Tip

Same as PostgreSQL, TimescaleDB deployment also includes an additional Extensions step (inserted after Add nodes and before Preview) to toggle on extensions you want installed together with the database. Once the cluster is deployed, you will need to enable the extension by using the CREATE EXTENSION statement.

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
Server data directory: The database server data directory path that ClusterControl shall configure on all database nodes. If the path does not exist, ClusterControl will create and configure it automatically. If blank, ClusterControl will use the default path.
User: The database admin username that ClusterControl shall configure on all database nodes. This user will be granted global SUPERUSER role and allowed for localhost only.
Password: The password for User.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.
Configuration template: The dropdown loads all TimescaleDB configuration template files under /etc/cmon/templates or /usr/share/cmon/templates of the ClusterControl node for this cluster type. Choose one configuration template for the deployment. See Configuration Template.
Enable SSL encryption: Toggling on (default) instructs ClusterControl to configure database SSL encryption for both client-server and replication. Toggling off skips this step.

Add nodes fields

Primary node: Specify the IP address or hostname of the primary database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. Only one primary node is allowed for streaming replication.
Replica nodes: Specify the IP address or hostname of the replica database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. You can specify zero or more replica nodes.
- Synchronous Replication: Toggling off (default) instructs ClusterControl to skip synchronous replication. Toggling on instructs ClusterControl to configure synchronous replication to the corresponding replica. You can have a mix of synchronous and asynchronous replication for multiple replicas in a cluster.

CLI and Terraform examples

ClusterControl CLITerraform Provider for ClusterControl

Create a three-node TimescaleDB 16 streaming replication, with operating system user "ubuntu" (the first node is the primary) with tags production and timescaledb:

s9s cluster --create \
    --cluster-type=postgresql \
    --nodes="10.10.10.11;10.10.10.12;10.10.10.13" \
    --vendor=postgresql \
    --provider-version=16 \
    --db-admin='postgres' \
    --db-admin-passwd='mYpa$$word' \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_rsa \
    --with-tags='production;timescaledb' \
    --cluster-name='TimescaleDB 16 - Streaming Replication' \
    --with-timescaledb

Create a standalone TimescaleDB 15, with operating system user "root" with tags test and timescaledb, and wait until the job finishes:

s9s cluster --create \
    --cluster-type=postgresql \
    --nodes="192.168.99.11" \
    --vendor=postgresql \
    --provider-version=15 \
    --db-admin='postgres' \
    --db-admin-passwd='mYpa$$word' \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --with-tags='test;timescaledb' \
    --cluster-name='TimescaleDB 16 - standalone' \
    --with-timescaledb \
    --wait

Deploy a 3-node TimescaleDB streaming replication 16.0, with operating system user "ubuntu" (the first node will be the primary):

resource "clustercontrol_db_cluster" "my-timescaledb-cluster" {

    db_cluster_create = true
    db_cluster_name = "TimescaleDB Streaming Replication 16"
    db_cluster_type = "postgresql"
    db_version = "16"
    db_vendor = "postgresql"
    db_admin_user_password = var.cc_api_user_password
    db_host {
        hostname = "10.10.10.11"
    }
    db_host {
        hostname = "10.10.10.12"
    }
    db_host {
        hostname = "10.10.10.13"
    }
    ssh_key_file = "/home/ubuntu/.ssh/id_rsa"
    ssh_user = "ubuntu"
    db_deploy_agents = true
    disable_firewall = true
    disable_selinux = true
    db_install_software = true
    db_enable_timescale = true

}

MongoDB Replica Set

Database dropdown value: "MongoDB ReplicaSet"

Deploys a new MongoDB standalone or replica set. The database cluster will be automatically added to ClusterControl once deployed. A minimum of three nodes (including a MongoDB arbiter) is recommended for a replica set. If only one node is specified, ClusterControl will deploy it as a standalone MongoDB node. The following vendors and versions are supported for a new deployment:

MongoDB Community - 7.0 and 8.0.
MongoDB Enterprise - 7.0 and 8.0.
Percona Server for MongoDB - 7.0 and 8.0.

Default configuration

By default, ClusterControl deploys MongoDB Replica Set members with the following configurations:

Configure setParameter.enableLocalhostAuthBypass: true inside MongoDB configuration file.
ClusterControl will create and grant necessary roles for additional MongoDB users - admin.cmon_backup for backup and restore purposes and admin.cmonexporter for query monitoring.

If you would like to customize the above configurations, modify the template base file to suit your needs before proceeding to the deployment. See Configuration Template for details.

Attention

It is possible to deploy only 2 MongoDB nodes (without an arbiter). The caveat of this approach is no automatic failover. If the primary node goes down then manual failover is required to make the other server run as primary. Automatic failover works fine with 3 nodes and more.

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
Server data directory: The database server data directory path that ClusterControl shall configure on all database nodes. If the path does not exist, ClusterControl will create and configure it automatically.
User: The database admin username that ClusterControl shall configure on all database nodes. This user will be granted the built-in root role.
Password: The password for User.
ReplicaSet name: Specify the name of the replica set, similar to replication.replSetName option in MongoDB.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.
Configuration template: The dropdown loads all MongoDB configuration template files under /etc/cmon/templates or /usr/share/cmon/templates of the ClusterControl node for this cluster type. Choose one configuration template for the deployment. See Configuration Template.
Enable SSL encryption: Toggling on (default) instructs ClusterControl to configure database SSL encryption for both client-server and replication. Toggling off skips this step.

Add nodes fields

Primary node: Specify the IP address or hostname of the primary database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. Only one primary node is allowed for a replica set configuration.
Replica nodes: Specify the IP address or hostname of the replica database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. You can specify zero or more replica nodes. If this field is left blank, ClusterControl will deploy the primary node as a standalone node.
- Act as an arbiter: Toggling off (default) instructs ClusterControl to configure the node as a standard MongoDB replica. Toggling on instructs ClusterControl to configure the node as a MongoDB arbiter. An arbiter participates in elections for primary but does not have a copy of the data set and cannot become primary.

CLI and Terraform examples

ClusterControl CLITerraform Provider for ClusterControl

Create a three-node MongoDB Enterprise replica set 7.0, with operating system user "ubuntu" (the first node is the primary) and let the deployment job run in the foreground:

s9s cluster --create \
    --cluster-type=mongodbenterprise \
    --nodes="192.168.99.13;192.168.99.15;192.168.99.19" \
    --vendor=mongodbenterprise \
    --provider-version='7.0' \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_rsa \
    --db-admin='admin' \
    --db-admin-passwd='MyS3cr3tPass' \
    --cluster-name='MongoDB Enterprise ReplicaSet 7.0' \
    --wait

Create a three-node MongoDB Community replica set 7.0, with operating system user "root" (the first node is the primary and the last node is an arbiter) and let the deployment job run in the foreground:

s9s cluster --create \
    --cluster-type=mongodb \
    --nodes="192.168.99.13;192.168.99.15;192.168.99.19?arbiter" \
    --vendor=mongodb \
    --provider-version='7.0' \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --db-admin='admin' \
    --db-admin-passwd='MyS3cr3tPass' \
    --cluster-name='MongoDB ReplicaSet 7.0' \
    --wait

Create a standalone MongoDB Community server 6.0, using operating system user "root" and let the deployment job run in the foreground:

s9s cluster --create \
    --cluster-type=mongodb \
    --nodes="192.168.5.11" \
    --vendor=mongodb \
    --provider-version='6.0' \
    --db-admin-passwd='Str0ngpa$$w0rd' \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --cluster-name='MongoDB 6.0 - standalone - devtest' \
    --wait

Deploy a 3-node replica set of Percona Server for MongoDB 7.0, with operating system user "ubuntu" (the first node will be the primary):

resource "clustercontrol_db_cluster" "my-mongodb-replicaset" {

    db_cluster_create = true
    db_cluster_name = "Percona MongoDB Replica Set 7.0"
    db_cluster_type = "mongodb"
    db_version = "7.0"
    db_vendor = "percona"
    db_admin_user_password = var.cc_api_user_password
    db_host {
        hostname = "10.10.10.11"
    }
    db_host {
        hostname = "10.10.10.12"
    }
    db_host {
        hostname = "10.10.10.13"
    }
    ssh_key_file = "/home/ubuntu/.ssh/id_rsa"
    ssh_user = "ubuntu"
    db_deploy_agents = true
    disable_firewall = true
    disable_selinux = true
    db_install_software = true

}

MongoDB Sharded Cluster

Database dropdown value: "MongoDB Shards"

Deploys a new MongoDB Sharded Cluster. The database cluster will be automatically added to ClusterControl once deployed. For production deployment, it is recommended to have at least 8 nodes for a high-availability setup:

2 nodes for the mongos (router),
3 nodes for the config server (replica set),
3 nodes per shard (replica set).

For a very minimal setup (suitable for testing and experimenting), you can start with two nodes and deploy it as below:

1 node for config server (one-node replica set) and mongos (co-locate together),
1 node for shard (one-node replica set).

The following vendors and versions are supported for a new deployment:

MongoDB Enterprise - 7.0 and 8.0.
MongoDB Community - 7.0 and 8.0.
Percona Server for MongoDB - 7.0 and 8.0.

Default configuration

By default, ClusterControl deploys MongoDB Sharded Cluster with the following configurations:

Configure setParameter.enableLocalhostAuthBypass: true inside MongoDB configuration file.
ClusterControl will create and grant necessary privileges for an additional MongoDB user - admin.cmon_backup for backup and restore purposes.

If you would like to customize the above configurations, modify the template base file to suit your needs before proceeding to the deployment. See Configuration Template for details.

Attention

MongoDB Sharded Cluster does not support mongodump backup method. Users will be asked to install Percona Backup for MongoDB (PBM) when creating or scheduling a backup for this cluster type after the deployment completes. Note that PBM requires shared remote backup storage (e.g., NFS) accessible on all MongoDB nodes.

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
Server data directory: The database server data directory path that ClusterControl shall configure on all database nodes. If the path does not exist, ClusterControl will create and configure it automatically.
User: The database admin username that ClusterControl shall configure on all database nodes. This user will be granted the built-in root role.
Password: The password for User.
Configuration template: The dropdown loads all MongoDB configuration template files under /etc/cmon/templates or /usr/share/cmon/templates of the ClusterControl node for this cluster type. Choose one configuration template for the deployment. See Configuration Template.
Router configuration template: The dropdown loads all MongoDB mongos configuration template files under /etc/cmon/templates or /usr/share/cmon/templates of the ClusterControl node for this cluster type. Choose one configuration template for the deployment. See Configuration Template.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part. Choose "Create new repository" to let ClusterControl create a local repository for the chosen vendor on the ClusterControl node.
Enable SSL encryption: Toggling on (default) instructs ClusterControl to configure database SSL encryption for both client-server and replication. Toggling off skips this step.

Add nodes fields (Configuration Servers and Routers, then Shard)

This database type replaces the generic Add nodes step with two steps:

Configuration Servers and Routers

Add configuration server: Specify the IP address or hostname of the MongoDB config servers. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. For high availability, at least 3 nodes are required.
- Port: MongoDB server port for MongoDB config server (config). The default is 27019.
Node router server: Specify the IP address or hostname of the MongoDB mongos servers. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. It is possible to co-locate mongos and config servers together.
- Port: MongoDB server port for MongoDB router server (mongos). The default is 27017.

Shard

ReplicaSet name: Specify the name of the replica set, similar to replication.replSetName option in MongoDB.
Port: MongoDB server port for MongoDB shard server (mongod). The default is 27018.
Add nodes to the shard: Specify the IP address or hostname of the primary database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. Only one primary node is allowed for a replica set configuration.
Replica nodes: Specify the IP address or hostname of the replica database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. You can specify zero or more replica nodes. If this field is left blank, ClusterControl will configure the shard with a single primary node.
- Replication delay - Specify the amount of time the secondary member should be delayed in seconds.
- Priority - Set the secondary member priority. A bigger integer represents a higher priority. A delayed secondary member should be set to 0 because it is not fit to become primary and should be hidden from the application.
Add another shard: Add another shard section to define another replica set of the shard. The same Shard form will be presented and you can add as many as 50 shards per cluster.
Remove this shard: Discard the current shard.

Note

After deployment completes, it is the database administrator job to enable sharding at the database and collection level.

CLI and Terraform examples

ClusterControl CLITerraform Provider for ClusterControl

Create a MongoDB Community sharded cluster 7.0 which consists of 3 mongos, 3 MongoDB config, and one shard consists of a three-node replica set called 'replset2' (with priority and slave_delay options), operating system user "root" and let the deployment job run in the foreground:

s9s cluster --create \
    --cluster-type=mongodb \
    --nodes="mongos://192.168.1.11;mongos://192.168.1.12;mongos://192.168.1.12;mongocfg://192.168.1.11;mongocfg://192.168.1.12;mongocfg://192.168.1.13;192.168.1.14?priority=5.0;192.168.1.15?arbiter_only=true;192.168.1.16?priority=2;192.168.1.17?rs=replset2;192.168.1.18?rs=replset2&arbiter_only=yes;192.168.1.19?rs=replset2&slave_delay=3&priority=0" \
    --vendor=mongodb \
    --provider-version='7.0' \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --db-admin='admin' \
    --db-admin-passwd='MyS3cr3tPass' \
    --cluster-name='MongoDB ReplicaSet 7.0' \
    --wait

Create a minimal 2-node MongoDB sharded cluster 6.0, using operating system user "root" and let the deployment job run in the foreground:

s9s cluster --create \
    --cluster-type=mongodb \
    --nodes="mongos://192.168.5.11:27017;mongocfg://192.168.5.11:27019;192.168.5.12:27018" \
    --vendor=mongodb \
    --provider-version='6.0' \
    --db-admin-passwd='Str0ngpa$$w0rd' \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --cluster-name='MongoDB Sharded Cluster 6.0 - minimal - devtest' \
    --wait

Deploy a 11-node MongoDB Sharded Cluster 7.0, with a 3-node config server replica set, a 6-node database nodes (2 replica sets, 3 nodes per shard) and 2-node mongos with operating system user "ubuntu" (the first node under db_replica_set will be the primary):

resource "clustercontrol_db_cluster" "my-mongodb-sharded-cluster" {

    db_cluster_create = true
    db_cluster_name = "MongoDB Sharded Cluster Set 7.0"
    db_cluster_type = "mongodb"
    db_version = "7.0"
    db_vendor = "mongodb"
    db_admin_user_password = var.cc_api_user_password
    db_config_server {
        rs = "rs_config"
        member {
            hostname = "192.168.10.201"
        }
        member {
            hostname = "192.168.10.202"
        }
        member {
            hostname = "192.168.10.203"
        }
    }

    db_mongos_server {
        hostname = "192.168.10.101"
    }

    db_mongos_server {
        hostname = "192.168.10.102"
    }

    db_replica_set {
        rs = "rs1"
        member {
            hostname = "192.168.10.111"
        }
        member {
            hostname = "192.168.10.112"
        }
        member {
            hostname = "192.168.10.113"
        }
    }

    db_replica_set {
        rs = "rs2"
        member {
            hostname = "192.168.10.121"
        }
        member {
            hostname = "192.168.10.122"
        }
        member {
            hostname = "192.168.10.123"
        }
    }
    ssh_key_file = "/home/ubuntu/.ssh/id_rsa"
    ssh_user = "ubuntu"
    db_deploy_agents = true
    disable_firewall = true
    disable_selinux = true
    db_install_software = true

}

Valkey Sentinel

Database dropdown value: "Valkey Sentinel"

Deploys new Valkey replication instances with Valkey Sentinel. A minimum of 3 nodes is recommended for high availability and automatic failover. The following vendors and versions are supported for a new deployment:

Valkey Sentinel - 7 and 8.
Canonical - 7.

For a very minimal setup (suitable for testing and experimenting), it is possible to deploy a single-node Valkey instance with Sentinel (both services co-located on the same node), and later can be scaled out with more Valkey database and Sentinel nodes.

Default configuration

By default, ClusterControl deploys Valkey instances with the following configurations:

Valkey Sentinel (default port is 26379) will be co-located with the Valkey instances (default port is 6379).
ClusterControl will configure the Valkey instance with appendonly enabled.
ClusterControl will secure the instance with authentication enabled and configure the requirepass and masterauth options.
ClusterControl will enable TLS encryption. To access the database nodes, one must use the --tls flag to connect.
The configuration maxMemory (70% of node's RAM, rounded to the nearest power of 2) and maxMemoryPolicy=allkeys-lru will be set, to reduce the risk of Valkey being killed by OOM.

Tips

Valkey Sentinel requires 3 nodes for automatic primary promotion. Sentinel can be co-located on the ClusterControl server if you want to deploy a two-node Valkey replication cluster (Sentinel will be co-located on each database instance).

Node configuration fields

Valkey port: The database server port that ClusterControl shall configure on all Valkey database nodes.
Valkey Sentinel port: The database server port that ClusterControl shall configure on all Valkey Sentinel nodes.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part. Choose "Create new repository" to let ClusterControl create a local repository for the chosen vendor on the ClusterControl node.
Password: The Valkey admin password that ClusterControl shall configure on all database nodes. The value will be used to configure the requirepass and masterauth options.
Enable SSL encryption: Toggling on (default) instructs ClusterControl to configure database SSL encryption for both client-server and replication. Toggling off skips this step.

Add nodes fields

Primary node: Specify the IP address or hostname of the primary database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. Only one primary node is allowed for a replication with Sentinel configuration.
Replica nodes: Specify the IP address or hostname of the replica database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. You can specify two or more replica nodes. If this field is left blank, ClusterControl will deploy the primary node as a standalone node.

CLI and Terraform examples

ClusterControl CLITerraform Provider for ClusterControl

Create a three-node Valkey Sentinel 8.0, with operating system user "ubuntu" (the first node is the primary), where the admin user password will be auto-generated, let the deployment job run in the foreground and show the job logs:

s9s cluster --create \
    --cluster-type=redis \
    --nodes="redis://10.0.0.11;redis://10.0.0.12;redis://10.0.0.13;redis-sentinel://10.0.0.11;redis-sentinel://10.0.0.12;redis-sentinel://10.0.0.13" \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_rsa \
    --vendor=valkey \
    --provider-version=8  \
    --log \
    --cluster-name="My Valkey Sentinel v8"

Create a standalone Valkey server (with Sentinel) 7.0, using operating system user "root" and let the deployment job run in the foreground:

s9s cluster --create \
    --cluster-type=redis \
    --nodes="redis://10.0.0.11;redis-sentinel://10.0.0.11" \
    --vendor=valkey \
    --provider-version=7 \
    --db-admin-passwd='Str0ngpa$$w0rd' \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --cluster-name='Valkey 7 - standalone - devtest' \
    --wait

Deploy a three-node Valkey with Sentinel 7.0, with operating system user "ubuntu" (the first node will be the primary):

resource "clustercontrol_db_cluster" "my-valkey-sentinel" {

    db_cluster_create = true
    db_cluster_name = "Valkey Sentinel 7"
    db_cluster_type = "redis"
    db_version = "7"
    db_vendor = "valkey"
    db_admin_user_password = var.cc_api_user_password
    db_host {
        hostname = "10.10.10.11"
    }
    db_host {
        hostname = "10.10.10.12"
    }
    db_host {
        hostname = "10.10.10.13"
    }
    ssh_key_file = "/home/ubuntu/.ssh/id_rsa"
    ssh_user = "ubuntu"
    db_deploy_agents = true
    disable_firewall = true
    disable_selinux = true
    db_install_software = true

}

Redis Sentinel

Database dropdown value: "Redis Sentinel"

Deploys new Redis replication instances with Redis. A minimum of 3 nodes is recommended for high availability and automatic failover. The following vendors and versions are supported for a new deployment:

Redis Sentinel - 6, 7 and 8.

For a very minimal setup (suitable for testing and experimenting), it is possible to deploy a single-node Redis instance with Sentinel (both services co-located on the same node), and later can be scaled out with more Redis database and Sentinel nodes.

Info

ClusterControl and Severalnines do not use or reproduce the official Redis® logo, which is a registered trademark of Redis Ltd. To comply with Redis trademark and branding guidelines, we have introduced our own distinct branding for Redis-related features within ClusterControl. This logo and name are original creations of Severalnines and are used solely as internal branding to represent Redis.

Default configuration

By default, ClusterControl deploys Redis instances with the following configurations:

Redis Sentinel (default port is 26379) will be co-located with the Redis instances (default port is 6379).
ClusterControl will configure the Redis instance with appendonly enabled.
ClusterControl will secure the instance with authentication enabled and configure the requirepass and masterauth options.
ClusterControl will enable TLS encryption. To access the database nodes, one must use the --tls flag to connect.
The configuration maxMemory (70% of node's RAM, rounded to the nearest power of 2) and maxMemoryPolicy=allkeys-lru will be set, to reduce the risk of Redis being killed by OOM.

Tips

Redis Sentinel requires 3 nodes for automatic primary promotion. Sentinel can be co-located on the ClusterControl server if you want to deploy a two-node Redis replication cluster (Sentinel will be co-located on each database instance).

Node configuration fields

Redis port: The database server port that ClusterControl shall configure on all Redis database nodes.
Redis Sentinel port: The database server port that ClusterControl shall configure on all Redis Sentinel nodes.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part. Choose "Create new repository" to let ClusterControl create a local repository for the chosen vendor on the ClusterControl node.
Password: The Redis admin password that ClusterControl shall configure on all database nodes. The value will be used to configure the requirepass and masterauth options.
Enable SSL encryption: Toggling on (default) instructs ClusterControl to configure database SSL encryption for both client-server and replication. Toggling off skips this step.

Add nodes fields

Primary node: Specify the IP address or hostname of the primary database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. Only one primary node is allowed for a replication with Sentinel configuration.
Replica nodes: Specify the IP address or hostname of the replica database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. You can specify two or more replica nodes. If this field is left blank, ClusterControl will deploy the primary node as a standalone node.

CLI and Terraform examples

ClusterControl CLITerraform Provider for ClusterControl

Create a three-node Redis Sentinel 7.0, with operating system user "ubuntu" (the first node is the primary), where the admin user password will be auto-generated, let the deployment job run in the foreground and show the job logs:

s9s cluster --create \
    --cluster-type=redis \
    --nodes="redis://10.0.0.11;redis://10.0.0.12;redis://10.0.0.13;redis-sentinel://10.0.0.11;redis-sentinel://10.0.0.12;redis-sentinel://10.0.0.13" \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_rsa \
    --vendor=redis \
    --provider-version=7  \
    --log \
    --cluster-name="My Redis Sentinel v7"

Create a standalone Redis server (with Sentinel) 6.0, using operating system user "root" and let the deployment job run in the foreground:

s9s cluster --create \
    --cluster-type=redis \
    --nodes="redis://10.0.0.11;redis-sentinel://10.0.0.11" \
    --vendor=redis \
    --provider-version=6 \
    --db-admin-passwd='Str0ngpa$$w0rd' \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --cluster-name='Redis 6 - standalone - devtest' \
    --wait

Deploy a three-node Redis Sentinel 7.0, with operating system user "ubuntu" (the first node will be the primary):

resource "clustercontrol_db_cluster" "my-redis-sentinel" {

    db_cluster_create = true
    db_cluster_name = "Redis with Sentinel 7"
    db_cluster_type = "redis"
    db_version = "7"
    db_vendor = "redis"
    db_admin_user_password = var.cc_api_user_password
    db_host {
        hostname = "10.10.10.11"
    }
    db_host {
        hostname = "10.10.10.12"
    }
    db_host {
        hostname = "10.10.10.13"
    }
    ssh_key_file = "/home/ubuntu/.ssh/id_rsa"
    ssh_user = "ubuntu"
    db_deploy_agents = true
    disable_firewall = true
    disable_selinux = true
    db_install_software = true

}

Valkey Cluster

Database dropdown value: "Valkey Cluster"

Deploy a new Valkey Cluster. A minimum of 3 nodes is recommended for automatic failover. Valkey Cluster requires at least 3 nodes for a standard cluster setup with 3 shards. However, each shard should have its replica, hence 6 nodes are recommended (1 primary + 1 replica per shard) for production deployment:

2 nodes (1 primary + 1 replica) for shard 1.
2 nodes (1 primary + 1 replica) for shard 2.
2 nodes (1 primary + 1 replica) for shard 3.

The following vendors and versions are supported for a new deployment:

Valkey Cluster - 7 and 8.
Canonical - 7.

Default configuration

By default, ClusterControl deploys Valkey cluster instances with the following configurations:

ClusterControl will configure the Valkey instances with appendonly enabled.
ClusterControl will secure the instance with AUTH enabled and configure the requirepass and masterauth options.
ClusterControl will enable TLS encryption. To access the cluster, one must use the --tls flag to connect.
The configuration maxMemory (70% of node's RAM, rounded to the nearest power of 2) and maxMemoryPolicy=allkeys-lru will be set, to reduce the risk of Valkey being killed by OOM.

Node configuration fields

Valkey port: The database server port that ClusterControl shall configure on all Valkey database nodes.
Cluster bus port: The database server port that ClusterControl shall configure for Valkey cluster communication.
Node timeout (ms): The maximum amount of time a Valkey Cluster node can be unavailable, without it being considered as failing. If a master node is not reachable for more than the specified amount of time, it will be failed over by its replicas. This parameter controls other important things in the Valkey Cluster. Notably, every node that can't reach the majority of master nodes for the specified amount of time, will stop accepting queries.
Replica validity factor: Specify the replication validity factor to consider a replica that is disconnected from the primary for more than Node timeout multiplied by this value. Set the factor to 0 to always consider a replica valid to failover. If the value is positive, a maximum disconnection time is calculated as the node timeout value multiplied by the factor provided with this option, and if the node is a replica, it will not try to start a failover if the master link was disconnected for more than the specified amount of time.
Configuration template: The dropdown loads all Valkey configuration template files under /etc/cmon/templates or /usr/share/cmon/templates of the ClusterControl node for this cluster type. Choose one configuration template for the deployment. See Configuration Template.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part. Choose "Create new repository" to let ClusterControl create a local repository for the chosen vendor on the ClusterControl node.
Username: The Valkey admin username that ClusterControl shall configure on all database nodes. The value will be used to configure the requirepass and masterauth options.
Password: The Valkey admin password that ClusterControl shall configure on all database nodes. The value will be used to configure the requirepass and masterauth options.

Add nodes fields (Shard 1, Shard 2, ...)

Primary node: Specify the IP address or hostname of the primary database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. Only one primary node is allowed for a replication with Sentinel configuration.
Replica nodes: Specify the IP address or hostname of the replica database node for this particular shard. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. You can specify zero or more replica nodes. If no replica nodes, ClusterControl will configure the shard as a single primary setup.
Add another shard: Add another shard section to define another replica set of the shard. A minimum of 3 shards is required. A similar Shard section will be presented where you can add another set of primary and replica nodes.
Remove this shard: Discard the current shard.

CLI examples

ClusterControl CLI

Create a 6-node Valkey Cluster 7.0, with operating system user "root", let the deployment job run in the foreground and show the job logs:

s9s cluster --create \
    --cluster-type=redis-sharded \
    --redis-port=6379 \
    --redis-bus-port=16379 \
    --vendor=valkey \
    --provider-version=7 \
    --node-timeout-ms=5000 \
    --replica-validity-factor=10 \
    --db-admin=admin \
    --db-admin-pass='Str0ngpa$$w0rd' \
    --nodes="redis-primary://192.168.0.101:6479;redis-replica://192.168.0.102:6479;redis-primary://192.168.0.111:6479;redis-replica://192.168.0.112:6479;redis-primary://192.168.0.121;redis-replica://192.168.0.123" \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --cluster-name="My Valkey Cluster v7" \
    --log

Create a 6-node Valkey Cluster 7.0, with operating system user "ubuntu", where the admin user password will be auto-generated, let the deployment job run in the foreground and show the job logs:

s9s cluster --create \
    --cluster-type=redis-sharded \
    --redis-port=6379 \
    --redis-bus-port=16379 \
    --vendor=valkey \
    --provider-version=7 \
    --node-timeout-ms=5000 \
    --replica-validity-factor=10 \
    --db-admin=admin \
    --nodes="redis-primary://192.168.0.101:6479;redis-replica://192.168.0.102:6479;redis-primary://192.168.0.111:6479;redis-replica://192.168.0.112:6479;redis-primary://192.168.0.121;redis-replica://192.168.0.123" \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_rsa \
    --cluster-name="My Valkey Cluster v7" \
    --log

Redis Cluster

Database dropdown value: "Redis Cluster"

Deploy a new Redis Cluster. A minimum of 3 nodes is recommended for automatic failover. Redis Cluster requires at least 3 nodes for a standard cluster setup with 3 shards. However, each shard should have its replica, hence 6 nodes are recommended (1 primary + 1 replica per shard) for production deployment:

2 nodes (1 primary + 1 replica) for shard 1.
2 nodes (1 primary + 1 replica) for shard 2.
2 nodes (1 primary + 1 replica) for shard 3.

The following vendors and versions are supported for a new deployment:

Redis Cluster - 6, 7 and 8.

Info

ClusterControl and Severalnines do not use or reproduce the official Redis® logo, which is a registered trademark of Redis Ltd. To comply with Redis trademark and branding guidelines, we have introduced our own distinct branding for Redis-related features within ClusterControl. This logo and name are original creations of Severalnines and are used solely as internal branding to represent Redis.

Default configuration

By default, ClusterControl deploys Redis cluster instances with the following configurations:

ClusterControl will configure the Redis instances with appendonly enabled.
ClusterControl will secure the instance with AUTH enabled and configure the requirepass and masterauth options.
ClusterControl will enable TLS encryption. To access the cluster, one must use the --tls flag to connect.
The configuration maxMemory (70% of node's RAM, rounded to the nearest power of 2) and maxMemoryPolicy=allkeys-lru will be set, to reduce the risk of Redis being killed by OOM.

Node configuration fields

Redis port: The database server port that ClusterControl shall configure on all Redis database nodes.
Cluster bus port: The database server port that ClusterControl shall configure for Redis cluster communication.
Node timeout (ms): The maximum amount of time a Redis Cluster node can be unavailable, without it being considered as failing. If a master node is not reachable for more than the specified amount of time, it will be failed over by its replicas. This parameter controls other important things in the Redis Cluster. Notably, every node that can't reach the majority of master nodes for the specified amount of time, will stop accepting queries.
Replica validity factor: Specify the replication validity factor to consider a replica that is disconnected from the primary for more than Node timeout multiplied by this value. Set the factor to 0 to always consider a replica valid to failover. If the value is positive, a maximum disconnection time is calculated as the node timeout value multiplied by the factor provided with this option, and if the node is a replica, it will not try to start a failover if the master link was disconnected for more than the specified amount of time.
Configuration template: The dropdown loads all Redis or Valkey configuration template files under /etc/cmon/templates or /usr/share/cmon/templates of the ClusterControl node for this cluster type. Choose one configuration template for the deployment. See Configuration Template.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part. Choose "Create new repository" to let ClusterControl create a local repository for the chosen vendor on the ClusterControl node.
Username: The Redis admin username that ClusterControl shall configure on all database nodes. The value will be used to configure the requirepass and masterauth options.
Password: The Redis admin password that ClusterControl shall configure on all database nodes. The value will be used to configure the requirepass and masterauth options.

Add nodes fields (Shard 1, Shard 2, ...)

Primary node: Specify the IP address or hostname of the primary database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. Only one primary node is allowed for a replication with Sentinel configuration.
Replica nodes: Specify the IP address or hostname of the replica database node for this particular shard. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. You can specify zero or more replica nodes. If no replica nodes, ClusterControl will configure the shard as a single primary setup.
Add another shard: Add another shard section to define another replica set of the shard. A minimum of 3 shards is required. A similar Shard section will be presented where you can add another set of primary and replica nodes.
Remove this shard: Discard the current shard.

CLI examples

ClusterControl CLI

Create a 6-node Redis Cluster 6.0, with operating system user "root", let the deployment job run in the foreground and show the job logs:

s9s cluster --create \
    --cluster-type=redis-sharded \
    --redis-port=6379 \
    --redis-bus-port=16379 \
    --vendor=redis \
    --provider-version=6 \
    --node-timeout-ms=5000 \
    --replica-validity-factor=10 \
    --db-admin=admin \
    --db-admin-pass='Str0ngpa$$w0rd' \
    --nodes="redis-primary://192.168.0.101:6479;redis-replica://192.168.0.102:6479;redis-primary://192.168.0.111:6479;redis-replica://192.168.0.112:6479;redis-primary://192.168.0.121;redis-replica://192.168.0.123" \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --cluster-name="My Redis Cluster v6" \
    --log \
    --print-request

Create a 6-node Redis Cluster 7.0, with operating system user "ubuntu", where the admin user password will be auto-generated, let the deployment job run in the foreground and show the job logs:

s9s cluster --create \
    --cluster-type=redis-sharded \
    --redis-port=6379 \
    --redis-bus-port=16379 \
    --vendor=redis \
    --provider-version=7 \
    --node-timeout-ms=5000 \
    --replica-validity-factor=10 \
    --db-admin=admin \
    --nodes="redis-primary://192.168.0.101:6479;redis-replica://192.168.0.102:6479;redis-primary://192.168.0.111:6479;redis-replica://192.168.0.112:6479;redis-primary://192.168.0.121;redis-replica://192.168.0.123" \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_rsa \
    --cluster-name="My Valkey Cluster v7" \
    --log \
    --print-request

SQL Server

Database dropdown value: "SQL Server"

Deploys a new standalone SQL Server instance or a SQL Server AlwaysOn high-availability setup. If only one database node is specified, ClusterControl will deploy it as standalone SQL Server. The following vendors and versions are supported for a new deployment:

Microsoft SQL Server for Linux - 2019, 2022 and 2025.

Attention

Only hostname or FQDN is supported. IP addresses are not accepted and will result in an error during the node addition process. Ensure proper host naming and mapping is configured beforehand, utilizing either /etc/hosts or a DNS resolver.

License

Deploying SQL Server with ClusterControl does not change how you must license SQL Server. Each node where SQL Server is running requires appropriate licensing, just as it would if you deployed SQL Server manually. The presence of ClusterControl as an orchestration or management layer has no bearing on Microsoft’s licensing rules. In a new deployment scenario, ClusterControl configures the SQL Server instance with the Evaluation edition, which is free to use for 180 days.

When deploying SQL Server in a clustered environment, licensing rules still apply to each server running SQL Server. However, the specifics differ depending on whether the node is actively running SQL Server or is a passive failover node:

Active Nodes: Each active node that runs SQL Server services needs to be fully licensed.
Passive Failover Nodes: Under current SQL Server licensing rules, you can typically have one passive failover node per licensed instance without needing an additional license for that passive node. The passive node is considered a “standby” server that can take over if the active server fails. It must truly remain passive, running no active workloads except those required for maintaining the standby state.

Obtain your SQL Server license directly from Microsoft, a certified Microsoft Partner, or a cloud marketplace (if applicable).

Default configuration

By default, ClusterControl deploys SQL Server with the following configurations:

All database nodes must use fully qualified domain name (FQDN). IP address is not supported.
Minimum available RAM is 1800 MB per database node.
Enforces the SQL Server user's password policy as shown here.
At the moment, ClusterControl only deploys AlwaysOn with asynchronous-commit mode, where it does not wait for any secondary replica to write incoming transaction log records to disk.
ClusterControl will set up the SQL Server using the Evaluation edition (free, 180-day limit).

Node configuration fields

Admin username: Specify the SQL Server admin username.
Admin password: The password for Admin username. The password must comply with the SQL Server password policy. See Password Policy. Click on the eye icon to view the unmasked password. Copy this value to somewhere safe, or you may generate a new one. It is recommended that you use the generated password as it meets the minimum requirements.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part. Choose "Create new repository" to let ClusterControl create a local repository for the chosen vendor on the ClusterControl node.
Enable SSL encryption: Toggling on (default) instructs ClusterControl to configure database SSL encryption for both client-server and replication. Toggling off skips this step.

Add nodes fields

Primary node: Specify hostname or FQDN of the primary database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. Only one primary node is allowed for SQL Server AlwaysOn availability group configuration.
Replica nodes: Specify hostname or FQDN of the replica database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. You can specify zero or more replica nodes. If no replica nodes, ClusterControl will configure the cluster as a standalone setup. You can add up to 8 replica nodes per availability group.

CLI and Terraform examples

ClusterControl CLITerraform Provider for ClusterControl

Create a 3-node SQL Server 2022 with Always On availability group, with operating system user "root", let the deployment job run in the foreground and show the job logs:

s9s cluster --create \
    --cluster-type=mssql_ao_async \
    --vendor=microsoft \
    --provider-version=2022 \
    --db-admin=SQLServerAdmin \
    --db-admin-pass='NqR$feGR68xli^#v' \
    --nodes="mssql://dsa-mssql-db1:1433;dsa-mssql-db2:1433;dsa-mssql-db3:1433;" \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --cluster-name="MSSQL Server 2022 Always On" \
    --log

Create a standalone SQL Server 2019, with operating system user "ubuntu", let the deployment job run in the foreground and show the job logs:

s9s cluster --create \
    --cluster-type=mssql_single \
    --vendor=microsoft \
    --provider-version=2019 \
    --db-admin=SQLServerAdmin \
    --db-admin-pass='NqR$feGR68xli^#v' \
    --nodes="mssql://dsa-mssql-db1:1433" \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_rsa \
    --cluster-name="Standalone SQL Server 2019" \
    --log

Deploy a three-node replica set of SQL Server 2022, with operating system user "ubuntu" (the first node will be the primary):

resource "clustercontrol_db_cluster" "my-mssql-2022" {
    db_cluster_create = true
    db_cluster_name = "Microsoft SQL Server 2022"
    db_cluster_type = "mssql_ao_async"
    db_version = "2022"
    db_vendor = "microsoft"
    db_admin_user = "SQLServerAdmin"
    db_admin_user_password = var.cc_api_user_password
    db_host {
        hostname = "10.10.10.11"
    }
    db_host {
        hostname = "10.10.10.12"
    }
    db_host {
        hostname = "10.10.10.13"
    }
    ssh_key_file = "/home/ubuntu/.ssh/id_rsa"
    ssh_user = "ubuntu"
    db_deploy_agents = true
    disable_firewall = true
    disable_selinux = true
    db_install_software = true
}

Elasticsearch

Database dropdown value: "Elasticsearch"

Deploys a new Elasticsearch single-node cluster or high-availability cluster setup. For a high-availability cluster setup, 3 nodes are required with 3 eligible masters and at least 2 data nodes (co-located with the masters). The following vendor and versions are supported for a new deployment:

Elastic - 7.17, 8.3 and 8.15.

Default configuration

By default, ClusterControl deploys Elasticsearch with the following configurations:

For high-availability cluster setup, ClusterControl will configure an NFS server on one of the Elasticsearch nodes and mount the shared filesystem on all data nodes. This is for snapshot backup and restoration.
For single-node cluster setup, ClusterControl will create a local path for snapshot backup and restoration.

Attention

The minimum memory requirement for an Elasticsearch master node, data node, or master-data node is 1576 MB. ClusterControl will abort the deployment job if this requirement is not met. See Hardware Requirement for Elasticsearch.

Node configuration fields

HTTP port: Elasticsearch HTTP port. The default is 9200 and not configurable.
Transfer port: Elasticsearch transfer port. The default is 9200 and not configurable.
Admin user: Specify the Elasticsearch admin username.
Admin password: Specify the password for Admin user.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part. Choose "Create new repository" to let ClusterControl create a local repository for the chosen vendor on the ClusterControl node.
Enable SSL encryption: This is not configurable as Elasticsearch enforces SSL encryption for high-availability cluster setup. If this is a single-node cluster setup, SSL encryption will be disabled automatically.

Add nodes fields

Eligible master: Specify IP address, hostname, or FQDN of the eligible master node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic.
- Use as data node - Toggling on configures the master as a data node. The role will be master-data. If toggled off, the node will be configured as master only. You may add more data nodes under the Data nodes section.
Data nodes: IP address, hostname, or FQDN of the data node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. You can specify zero or more replica nodes. If no replica nodes, ClusterControl will configure the server as a single-node cluster setup.

Extra step: Snapshot storage configuration

This step follows Add nodes, before Preview:

Repository name: Specify the snapshot storage repository name.
Storage host: Host with physical file system storing snapshots and sharing with other cluster's nodes.
Default storage location: Location of the shared filesystem used to store and retrieve snapshots. This location will be registered in the path.repo setting on all master and data nodes in the cluster.
Configure shared filesystem: Toggling on lets ClusterControl install and configure the NFS shared filesystem on the chosen Storage host and Default storage location as the default cluster's snapshot repository. Toggling off skips this configuration part. Users are responsible for configuring the NFS shared filesystem on the chosen Storage host and Default storage location. The deployment job will fail if a shared filesystem is not configured.

ClickHouse

Database dropdown value: "ClickHouse"

Deploys a new ClickHouse column-oriented OLAP cluster. ClusterControl supports three topologies:

Standalone - a single clickhouse-server node with no coordination service. Suitable for testing and development, and can be scaled out later.
Replicated cluster - two or more clickhouse-server nodes where data is replicated across all nodes. Coordination is handled by ClickHouse Keeper, either embedded in each data node or running on dedicated keeper nodes. A minimum of 3 keepers (Raft quorum) is recommended for production high availability.
Sharded cluster - data is distributed across multiple shards for horizontal scalability, with one or more replicas per shard for high availability. DDL operations propagate via ON CLUSTER and Distributed tables enable transparent cross-shard queries.

The following vendor and versions are supported for a new deployment:

ClickHouse - 24.8 (LTS) and 25.3.

Default configuration

By default, ClusterControl deploys ClickHouse with the following configurations:

ClickHouse cluster communication is TLS-only. ClusterControl configures secure ports for all client and inter-node traffic: 9440 (native TCP protocol), 8443 (HTTPS API), 9010 (interserver replication), 9281 (Keeper client) and 9234 (Keeper Raft).
For replicated and sharded topologies, ClusterControl configures ClickHouse Keeper (embedded in the data nodes by default) to coordinate replication metadata using the Raft consensus algorithm.
Prometheus metrics are exposed on port 9363 for monitoring.
The following packages are installed from the official ClickHouse repository: clickhouse-common-static, clickhouse-server and clickhouse-client.
An admin user (default admin) is created and granted full privileges. For replicated and sharded clusters, users are propagated to all nodes via CREATE USER ... ON CLUSTER.

If you would like to customize the above configurations, modify the template base file to suit your needs before proceeding to the deployment. See Configuration Template for details.

Note

ClusterControl only supports managing x86-64 architecture hosts for ClickHouse. All ClickHouse communication is TLS-only; there is no non-SSL deployment option.

Node configuration fields

Native TCP port: The secure native TCP port used by clickhouse-client. The default is 9440.
HTTPS API port: The secure HTTPS API port used for health checks and queries. The default is 8443.
Admin user: Specify the ClickHouse admin username. The default is admin.
Admin password: Specify the password for Admin user.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.
Enable SSL encryption: This is not configurable as ClickHouse enforces TLS encryption for all client and inter-node communication.

Add nodes fields

Data nodes: Specify the IP address or hostname of the ClickHouse data node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. Specifying a single data node deploys a standalone cluster; specifying two or more data nodes deploys a replicated cluster with embedded Keeper.
Keeper nodes: (Optional) Specify the IP address or hostname of dedicated ClickHouse Keeper nodes. Press Enter to add the node. If no keeper nodes are specified for a replicated cluster, ClusterControl configures Keeper embedded in each data node. A minimum of 3 keepers is recommended to maintain a Raft quorum.

CLI examples

ClusterControl CLI

Create a standalone ClickHouse 24.8 node, with operating system user "ubuntu":

s9s cluster --create \
    --cluster-type=clickhouse \
    --nodes="clickhouse://10.10.16.4" \
    --vendor=clickhouse \
    --provider-version=24.8 \
    --db-admin='admin' \
    --db-admin-passwd='mYpa$$word' \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_rsa \
    --cluster-name='ClickHouse 24.8 - Standalone'

Create a three-node ClickHouse 24.8 replicated cluster with embedded Keeper, with operating system user "ubuntu":

s9s cluster --create \
    --cluster-type=clickhouse \
    --nodes="clickhouse://10.10.16.4;clickhouse://10.10.16.5;clickhouse://10.10.16.6" \
    --vendor=clickhouse \
    --provider-version=24.8 \
    --db-admin='admin' \
    --db-admin-passwd='mYpa$$word' \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_rsa \
    --cluster-name='ClickHouse 24.8 - Replicated Cluster'

Create a ClickHouse 24.8 replicated cluster with dedicated Keeper nodes (2 data nodes + 3 keeper nodes), using operating system user "root" and let the deployment job run in the foreground:

s9s cluster --create \
    --cluster-type=clickhouse \
    --nodes="clickhouse://10.10.16.5;clickhouse://10.10.16.6;clickhouse-keeper://10.10.16.8;clickhouse-keeper://10.10.16.9;clickhouse-keeper://10.10.16.10" \
    --vendor=clickhouse \
    --provider-version=24.8 \
    --db-admin='admin' \
    --db-admin-passwd='Str0ngpa$$w0rd' \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --cluster-name='ClickHouse 24.8 - Dedicated Keeper' \
    --wait

Recommended Next Steps