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 topology are supported:

Database	Vendor	Topology
MySQL	Percona, Oracle	Standalone, replication
MariaDB	MariaDB	Standalone, replication
Galera Cluster	MariaDB, Percona	Galera certification-based replication
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

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.

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.
Percona Server for MySQL - 8.0.
MariaDB Server - 10.4, 10.5, 10.6 (LTS), 10.11 (LTS) and 11.4 (LTS).

ClusterControl supports configuring both 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).

Deployment steps

ClusterControl GUIClusterControl CLITerraform Provider for ClusterControl

To create a new MySQL replication cluster, go to ClusterControl GUI → Deploy a cluster → Create a database cluster and under the Database dropdown, choose "MySQL Replication".
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.
You will be presented with a Deploy MySQL Replication Cluster deployment wizard. 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 and click Continue to the next step.

Tip

A proper tag configuration will help you group your database clusters and is commonly recommended in a large deployment.
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 existed 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.
- Install software: Toogle on (default) will instruct ClusterControl to install the database software from the package repository during deployment. Toggling off will skip 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 recomemnded 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 recomemnded 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.
Under the Node configuration section, specify the database credentials and configurations that ClusterControl shall use when deploying the cluster:
- 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: Choose "Use vendor repositories" (default) will let 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) and ClusterControl will 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: Toggle on (default) will instruct ClusterControl to configure database SSL encryption for both client-server and replication. Toggle off will make ClusterControl skip this step.
- Semi-synchronous replication: Toggle on (default) will instruct ClusterControl to configure a semi-synchronous replication. Toggle off will instruct ClusterControl to configure an asynchronous replication.
Click Continue to proceed to the next step.
Under the Add nodes section, you can specify the target database nodes and configure the database topology that you want to deploy:
- 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: Toggle off (default) will instruct ClusterControl to create the replication cluster as a single-primary replication. Toggling on will open up another set of Primary node and Replica nodes form field to be filled up for multi-primary replication. ClusterControl will set up the secondary primary node using circular replication but with read-only enabled.
  
  Note
  
  You can only proceed to the next step if all of the specified nodes are reachable (shown in green).
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.

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

}

Recommended Next Steps

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.
MariaDB Cluster - 10.4, 10.5, 10.6 (LTS), 10.11 (LTS) and 11.4 (LTS).

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.

Deployment steps

ClusterControl GUIClusterControl CLITerraform Provider for ClusterControl

To create a new MySQL Galera Cluster, go to ClusterControl GUI → Deploy a cluster → Create a database cluster and under the Database dropdown, choose "MySQL Galera".
Choose a vendor from the Vendor dropdown.
Choose a major database version from the Version dropdown.
Click Continue.
You will be presented with a Deploy MySQL Galera Cluster deployment wizard. 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 and click Continue to the next step.

Tip

A proper tag configuration will help you group your database clusters and is commonly recommended in a large deployment.
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 existed 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.
- Install software: Toogle on (default) will instruct ClusterControl to install the database software from the package repository during deployment. Toggling off will skip 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 recomemnded 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 recomemnded 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.
Under the Node configuration section, specify the database credentials and configurations that ClusterControl shall use when deploying the cluster:
- 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: Choose "Use vendor repositories" (default) will let 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) and ClusterControl will 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: Toggle on (default) will instruct ClusterControl to configure database SSL encryption for both client-server and replication. Toggle off will make ClusterControl skip 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.
Click Continue to proceed to the next step.
Under the Add nodes section, you can specify the target database nodes and configure the database topology that you want to deploy:
- 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 odd number of nodes in total to avoid split-brain situation.
  
  Note
  
  You can only proceed to the next step if all of the specified nodes are reachable (shown in green).
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.

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

}

Recommended Next Steps

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 - 12, 13, 14, 15, 16 and 17.
PostgreSQL from EDB repository - 12, 13, 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.

Deployment steps

ClusterControl GUIClusterControl CLITerraform Provider for ClusterControl

To create a new PostgreSQL streaming replication, go to ClusterControl GUI → Deploy a cluster → Create a database cluster and under the Database dropdown, choose "PostgreSQL Streaming".
Choose a vendor from the Vendor dropdown. This will determine the version and package repository to use in the deployment. For "PostgreSQL Enterprise DB", it requires a valid EDB repository token.
Choose a major database version from the Version dropdown.
Click Continue.
You will be presented with a Deploy PostgreSQL cluster deployment wizard. 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. If you choose "PostgreSQL Enteprise DB" as the vendor, provide the EDB repository token where you can retrieve it from here. 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.
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 existed 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.
- Install software: Toogle on (default) will instruct ClusterControl to install the database software from the package repository during deployment. Toggling off will skip 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 recomemnded 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 recomemnded 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.
Under the Node configuration section, specify the database credentials and configurations that ClusterControl shall use when deploying the cluster:
- 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: Choose "Use vendor repositories" (default) will let 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) and ClusterControl will 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: Toggle on (default) will instruct ClusterControl to configure database SSL encryption for both client-server and replication. Toggle off will make ClusterControl skip this step.
Click Continue to proceed to the next step.
Under the Add nodes section, you can specify the target database nodes and configure the database topology that you want to deploy:
- 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: Toggle off (default) will instruct ClusterControl to skip the synchronous replication. Toggling on will instruct ClusterControl to configure synchronous replication to the corresponding replica. You can have a mixed of synchronous and asynchronous replication for multiple replicas in a cluster.
Note

You can only proceed to the next step if all of the specified nodes are reachable (shown in green).
Click Continue to proceed to the Extensions page. In this section, you can toggle on extension from the list you want to be installed together with the PostgreSQL database. Once the cluster is deployed, you will need to enable the extension by using the CREATE EXTENSION statement.
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.

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

}

Recommended Next Steps

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 will be 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 section under the 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 - 12, 13, 14, 15, 16 and 17.
PostgreSQL from EDB repository - 12, 13, 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 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.

Deployment steps

ClusterControl GUIClusterControl CLITerraform Provider for ClusterControl

To create a new PostgreSQL logical replication, go to ClusterControl GUI → Deploy a cluster → Create a database cluster and under the Database dropdown, choose "PostgreSQL Logical".
Choose a vendor from the Vendor dropdown. This will determine the version and package repository to use in the deployment. For "PostgreSQL Enterprise DB", it requires a valid EDB repository token.
Choose a major database version from the Version dropdown.
Click Continue.
You will be presented with a Deploy PostgreSQL Logical cluster deployment wizard. 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. If you choose "PostgreSQL Enteprise DB" as the vendor, provide the EDB repository token where you can retrieve it from here. 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.
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 existed 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.
- Install software: Toogle on (default) will instruct ClusterControl to install the database software from the package repository during deployment. Toggling off will skip 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 recomemnded 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 recomemnded 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.
Under the Node configuration section, specify the database credentials and configurations that ClusterControl shall use when deploying the cluster:
- 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: Choose "Use vendor repositories" (default) will let 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) and ClusterControl will 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: Toggle on (default) will instruct ClusterControl to configure database SSL encryption for both client-server and replication. Toggle off will make ClusterControl skip this step.
Click Continue to proceed to the next step.
Under the Add nodes section, you can specify the target database nodes and configure the database topology that you want to deploy:
- Cluster 1
  - 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: Toggle off (default) will instruct ClusterControl to skip the synchronous replication. Toggling on will instruct ClusterControl to configure synchronous replication to the corresponding replica. You can have a mixed of synchronous and asynchronous replication for multiple replicas in a cluster.
- Cluster 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 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: Toggle off (default) will instruct ClusterControl to skip the synchronous replication. Toggling on will instruct ClusterControl to configure synchronous replication to the corresponding replica. You can have a mixed of synchronous and asynchronous replication for multiple replicas in a cluster.
Note

You can only proceed to the next step if all of the specified nodes are reachable (shown in green).
Click Continue to proceed to the Extensions page. In this section, you can toggle on extension from the list you want to be installed together with the PostgreSQL database. Once the cluster is deployed, you will need to enable the extension by using the CREATE EXTENSION statement.
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.

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

}

Recommended Next Steps

TimescaleDB

Deploys a new TimescaleDB standalone or streaming replication cluster from ClusterControl. A minimum of two nodes is required for TimescaleDB streaming replication. The following vendors and versions are supported for a new deployment:

TimescaleDB - 12, 13, 14, 15, 16 and 17.

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.

Deployment steps

ClusterControl GUIClusterControl CLITerraform Provider for ClusterControl

To create a new TimescaleDB streaming replication, go to ClusterControl GUI → Deploy a cluster → Create a database cluster and under the Database dropdown, choose "TimescaleDB".
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.
You will be presented with a Deploy TimescaleDB cluster deployment wizard. 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.
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 existed 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.
- Install software: Toogle on (default) will instruct ClusterControl to install the database software from the package repository during deployment. Toggling off will skip 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 recomemnded 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 recomemnded 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.
Under the Node configuration section, specify the database credentials and configurations that ClusterControl shall use when deploying the cluster:
- 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: Choose "Use vendor repositories" (default) will let 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) and ClusterControl will 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: Toggle on (default) will instruct ClusterControl to configure database SSL encryption for both client-server and replication. Toggle off will make ClusterControl skip this step.
Click Continue to proceed to the next step.
Under the Add nodes section, you can specify the target database nodes and configure the database topology that you want to deploy:
- 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: Toggle off (default) will instruct ClusterControl to skip the synchronous replication. Toggling on will instruct ClusterControl to configure synchronous replication to the corresponding replica. You can have a mixed of synchronous and asynchronous replication for multiple replicas in a cluster.
Note

You can only proceed to the next step if all of the specified nodes are reachable (shown in green).
Click Continue to proceed to the Extensions page. In this section, you can toggle on extension from the list you want to be installed together with the TimescaleDB database. Once the cluster is deployed, you will need to enable the extension by using the CREATE EXTENSION statement.
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.

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

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 MongoDB arbiter) is recommended for a replica set. If only one node is specified, ClusterControl will deploy it as a standalone node. The following vendors and versions are supported for a new deployment:

MongoDB Community - 4.4, 5.0, 6.0 and 7.0
MongoDB Enterprise - 4.4, 5.0, 6.0 and 7.0
Percona Server for MongoDB - 4.4, 5.0, 6.0 and 7.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.

Deployment steps

ClusterControl GUIClusterControl CLITerraform Provider for ClusterControl

To create a new MongoDB replica set, go to ClusterControl GUI → Deploy a cluster → Create a database cluster and under the Database dropdown, choose "MongoDB ReplicaSet".
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.
You will be presented with a Deploy MongoDB ReplicaSet cluster deployment wizard. 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 and click Continue to the next step.

Tip

A proper tag configuration will help you group your database clusters and is commonly recommended in a large deployment.
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 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.
- Install software: Toogle on (default) will instruct ClusterControl to install the database software from the package repository during deployment. Toggling off will skip 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 recomemnded 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 recomemnded 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.
Under the Node configuration section, specify the database credentials and configurations that ClusterControl shall use when deploying the cluster:
- 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: Choose "Use vendor repositories" (default) will let 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 enteprise databases) and ClusterControl will 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: Toggle on (default) will instruct ClusterControl to configure database SSL encryption for both client-server and replication. Toggle off will make ClusterControl skip this step.
Click Continue to proceed to the next step.
Under the Add nodes section, you can specify the target database nodes and configure the database topology that you want to deploy:
- 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: Toggle off (default) will instruct ClusterControl to configure the node as a standard MongoDB replica. Toggling on will instruct ClusterControl to configure the node as a MongoDB arbiter. An arbiter participates in elections for primary but it does not have a copy of the data set and cannot become a primary.
  Note
  
  You can only proceed to the next step if all of the specified nodes are reachable (shown in green).
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.

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 Enteprise 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

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 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 - 4.4, 5.0, 6.0 and 7.0
MongoDB Community - 4.4, 5.0, 6.0 and 7.0
Percona Server for MongoDB - 4.4, 5.0, 6.0 and 7.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 a shared remote backup storage accessible on all MongoDB nodes.

Deployment steps

ClusterControl GUIClusterControl CLITerraform Provider for ClusterControl

To create a new MongoDB replica set, go to ClusterControl GUI → Deploy a cluster → Create a database cluster and under the Database dropdown, choose "MongoDB Shards".
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.
You will be presented with a Deploy MongoDB ReplicaSet cluster deployment wizard. 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 and click Continue to the next step.

Tip

A proper tag configuration will help you group your database clusters and is commonly recommended in a large deployment.
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 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.
- Install software: Toogle on (default) will instruct ClusterControl to install the database software from the package repository during deployment. Toggling off will skip 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 recomemnded 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 recomemnded 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.
Under the Node configuration section, specify the database credentials and configurations that ClusterControl shall use when deploying the cluster:
- 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: Choose "Use vendor repositories" (default) will let 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 enteprise databases) and ClusterControl will 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: Toggle on (default) will instruct ClusterControl to configure database SSL encryption for both client-server and replication. Toggle off will make ClusterControl skip this step.
Click Continue to proceed to the next step.
Under the Configuration Servers and Routers section, you can specify the MongoDB config and mongos servers information:
- 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.
Note

You can only proceed to the next step if all of the specified nodes are reachable (shown in green).
Under the Shard section, you can specify the target MongoDB database nodes and configure the replica set and shards:
- 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.
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.

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 Enteprise ReplicaSet 7.0' \
    --wait

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

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

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).

Deployment steps

ClusterControl GUIClusterControl CLITerraform Provider for ClusterControl

To create a new Valkey replication with Sentinel, go to ClusterControl GUI → Deploy a cluster → Create a database cluster and under the Database dropdown, choose "Valkey Sentinel".
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.
You will be presented with a Deploy Valkey Sentinel Cluster deployment wizard. 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 and click Continue to the next step.

Tip

A proper tag configuration will help you group your database clusters and is commonly recommended in a large deployment.
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 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.
- Install software: Toogle on (default) will instruct ClusterControl to install the database software from the package repository during deployment. Toggling off will skip 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 recomemnded 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 recomemnded 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.
Under the Node configuration section, specify the database credentials and configurations that ClusterControl shall use when deploying the cluster:
- 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: Choose "Use vendor repositories" (default) will let 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 enteprise databases) and ClusterControl will 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: Toggle on (default) will instruct ClusterControl to configure database SSL encryption for both client-server and replication. Toggle off will make ClusterControl skip this step.
Click Continue to proceed to the next step.
Under the Add nodes section, you can specify the target database nodes and configure the database topology that you want to deploy:
- 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.
Note

You can only proceed to the next step if all of the specified nodes are reachable (shown in green).
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.

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

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 and 7

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.

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).

Deployment steps

ClusterControl GUIClusterControl CLITerraform Provider for ClusterControl

To create a new Redis replication with Sentinel, go to ClusterControl GUI → Deploy a cluster → Create a database cluster and under the Database dropdown, choose "Redis Sentinel".
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.
You will be presented with a Deploy Redis Sentinel Cluster deployment wizard. 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 and click Continue to the next step.

Tip

A proper tag configuration will help you group your database clusters and is commonly recommended in a large deployment.
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 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.
- Install software: Toogle on (default) will instruct ClusterControl to install the database software from the package repository during deployment. Toggling off will skip 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 recomemnded 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 recomemnded 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.
Under the Node configuration section, specify the database credentials and configurations that ClusterControl shall use when deploying the cluster:
- 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: Choose "Use vendor repositories" (default) will let 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 enteprise databases) and ClusterControl will 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: Toggle on (default) will instruct ClusterControl to configure database SSL encryption for both client-server and replication. Toggle off will make ClusterControl skip this step.
Click Continue to proceed to the next step.
Under the Add nodes section, you can specify the target database nodes and configure the database topology that you want to deploy:
- 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.
Note

You can only proceed to the next step if all of the specified nodes are reachable (shown in green).
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.

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

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

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.

Deployment steps

ClusterControl GUIClusterControl CLI

To create a new Valkey Cluster, go to ClusterControl GUI → Deploy a cluster → Create a database cluster and under the Database dropdown, choose "Valkey Cluster".
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.
You will be presented with a Deploy Valkey Cluster deployment wizard. 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 and click Continue to the next step.

Tip

A proper tag configuration will help you group your database clusters and is commonly recommended in a large deployment.
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 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.
- Install software: Toogle on (default) will instruct ClusterControl to install the database software from the package repository during deployment. Toggling off will skip 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 recomemnded 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 recomemnded 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.
Under the Node configuration section, specify the database credentials and configurations that ClusterControl shall use when deploying the cluster:
- 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 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 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: Choose "Use vendor repositories" (default) will let 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 enteprise databases) and ClusterControl will 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.
Click Continue to proceed to the next step.
Under the Shard 1 section, you can specify the target database nodes and configure the database topology that you want to deploy:
- 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.
Note

You can only proceed to the next step if all of the specified nodes are reachable (shown in green).
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.

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

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 and 7

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.

Deployment steps

ClusterControl GUIClusterControl CLI

To create a new Redis Cluster, go to ClusterControl GUI → Deploy a cluster → Create a database cluster and under the Database dropdown, choose "Redis Cluster".
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.
You will be presented with a Deploy Redis Cluster deployment wizard. 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 and click Continue to the next step.

Tip

A proper tag configuration will help you group your database clusters and is commonly recommended in a large deployment.
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 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.
- Install software: Toogle on (default) will instruct ClusterControl to install the database software from the package repository during deployment. Toggling off will skip 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 recomemnded 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 recomemnded 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.
Under the Node configuration section, specify the database credentials and configurations that ClusterControl shall use when deploying the cluster:
- 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: Choose "Use vendor repositories" (default) will let 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 enteprise databases) and ClusterControl will 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.
Click Continue to proceed to the next step.
Under the Shard 1 section, you can specify the target database nodes and configure the database topology that you want to deploy:
- 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.
Note

You can only proceed to the next step if all of the specified nodes are reachable (shown in green).
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.

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

Deploys a new standalone or 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 and 2022

Attention

Only hostname or FQDN is supported. Therefore, proper host naming and mapping must be performed beforehand. You may use /etc/hosts or DNS mapping to achieve this. When adding a database node in ClusterControl, entering an IP address will produce an error.

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.

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.

Deployment steps

ClusterControl GUIClusterControl CLITerraform Provider for ClusterControl

To create a new SQL Server, go to ClusterControl GUI → Deploy a cluster → Create a database cluster and under the Database dropdown, choose "SQL Server".
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.
You will be presented with a Deploy SQL Server Cluster deployment wizard. 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 and click Continue to the next step.

Tip

A proper tag configuration will help you group your database clusters and is commonly recommended in a large deployment.
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 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.
- Install software: Toogle on (default) will instruct ClusterControl to install the database software from the package repository during deployment. Toggling off will skip 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 recomemnded 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 recomemnded 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.
Under the Node configuration section, specify the database credentials and configurations that ClusterControl shall use when deploying the cluster:
- Admin username: Specify the SQL Server admin username.
- Admin password: The password for Admin username. The password must comply to 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: Choose "Use vendor repositories" (default) will let 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 enteprise databases) and ClusterControl will 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: Toggle on (default) will instruct ClusterControl to configure database SSL encryption for both client-server and replication. Toggle off will make ClusterControl skip this step.
Click Continue to proceed to the next step.
Under the Add nodes section, you can specify the target database nodes and configure the database topology that you want to deploy:
- 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.
Note

You can only proceed to the next step if all of the specified nodes are reachable (shown in green).
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.

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

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 2 data nodes (co-located with the masters). The following vendor and versions are supported for a new deployment:

Elastic - 7.17, 8.1 and 8.3

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.

Deployment steps

ClusterControl GUI

To create a new Elasticsearch cluster, go to ClusterControl GUI → Deploy a cluster → Create a database cluster and under the Database dropdown, choose "Elasticsearch".
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.
You will be presented with a Deploy Elasticsearch Cluster deployment wizard. 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 and click Continue to the next step.

Tip

A proper tag configuration will help you group your database clusters and is commonly recommended in a large deployment.
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 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.
- Install software: Toogle on (default) will instruct ClusterControl to install the database software from the package repository during deployment. Toggling off will skip 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 recomemnded 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 recomemnded 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.
Under the Node configuration section, specify the database credentials and configurations that ClusterControl shall use when deploying the cluster:
- 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: Choose "Use vendor repositories" (default) will let 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 enteprise databases) and ClusterControl will 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.
Click Continue to proceed to the next step.
Under the Add nodes section, you can specify the target database nodes and configure the database topology that you want to deploy:
- 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. Only one primary node is allowed for SQL Server AlwaysOn availability group configuration.
  - Use as data node - Toggle ON to configure the master as a data node. The role will be master-data. If 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.
Note

You can only proceed to the next step if all of the specified nodes are reachable (shown in green).
Click Continue to proceed to the next step.
Under the Snapshot storage configuration section, you can configure Elasticsearch backup-related storage configuration:
- 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: Toggle on to let ClusterControl install and configure the NFS shared filesystem on the chosen Storage host and Default storage location as the default cluster's snapshot repository. Toggle off to skip 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.
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.