Import Database Cluster

If you already have a running database node or cluster, you can bring it under ClusterControl management using Import Database Cluster feature. You may import one database node

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
MySQL Group Replication	Oracle	Single-primary, multi-primary
PostgreSQL	PostgreSQL, EnterpriseDB	Standalone, streaming replication, logical replication
TimescaleDB	TimescaleDB	Standalone, streaming replication
MongoDB	MongoDB, Percona, MongoDB Enterprise	Replica set, sharded cluster
Redis	Redis, Valkey	Sentinel, cluster
Microsoft SQL Server for Linux	Microsoft	Standalone, Always On availability group
Elasticsearch	Elastic	Single-node cluster, high availability cluster
ClickHouse	ClickHouse	Standalone, replicated cluster, sharded cluster

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.
The target cluster must be in healthy state and not in a degraded state. For example, if you have a three-node Galera cluster, all nodes must be alive, accessible, and in sync.

Note

For more details, refer to the Requirements section. Each time you import an existing cluster or server, ClusterControl will trigger a job under ClusterControl GUI → Activity Center → Jobs. You can see the progress and status on this page. Click on … of the importing job and click Details. A window will also appear with messages showing the progress.

Common Wizard Steps

The Import Database Cluster wizard follows the same flow and step order for every database type listed in the Support Matrix above. Only the Node configuration and Add nodes steps have database-specific fields. These differences are documented per database type in Database-Specific Settings below.

ClusterControl GUIClusterControl CLI

Opening the wizard

Go to ClusterControl GUI → Deploy a cluster → Import a database cluster and under the Database dropdown, choose your target database type (see the dropdown label listed at the start of each entry in Database-Specific Settings).

Step 1: Cluster details

Under Cluster details, specify the cluster details you want to assign:
- Name: Optional. This is the name of your cluster, labeled Name your cluster. Once the import is done, ClusterControl will use this as the cluster's registry name.
- Tags: Add tags to search or group your database clusters.
MongoDB Replica Set and MongoDB Sharded Cluster only

This step also has a Vendor field, under Vendor and version. This is required and identifies which vendor's binaries the existing cluster is running: choose from Percona, MongoDB, or MongoDB Enterprise.

Click Continue.

Step 2: SSH configuration

Under the SSH configuration section, specify the SSH credentials that ClusterControl should use to connect to the database nodes:
- SSH user: The SSH user that ClusterControl will use to perform SSH to the database node. ClusterControl assumes that all database nodes are using the same SSH user.
- SSH user key path: The SSH private key path that ClusterControl will use to perform SSH authentication to the database node. Relative path is not supported. The SSH private key must be physically secured and exist on the ClusterControl node.
- SSH port: The SSH port that ClusterControl will use to perform SSH to the database node. ClusterControl assumes that all database nodes are using the same SSH port.
- SSH sudo password: The sudo password if the SSH user requires a password for privilege escalation.
- SSH sudo / OS elevation command: The OS elevation command (sudo, doas, pbrun) that ClusterControl will use for a non-root account.
Click Continue to proceed to the next step.

Step 3: Node configuration

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

Click Continue to proceed to the next step.

Step 4: Add nodes

Under the Add nodes section, specify your existing target database nodes. Since this is an existing database cluster that is already set up, ClusterControl will identify and scan the topology of your database cluster automatically. The exact fields depend on the database type; see Database-Specific Settings for the full list for your chosen database.

Note

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

Finishing the wizard

Click Continue to proceed to the Preview page. In this section, you can see the summary of your import and if everything is correct, you may proceed by clicking Finish. You can always go back to any previous section to modify your configurations if you wish. The settings will be kept until you exit the wizard.
ClusterControl will trigger an import job and the progress can be monitored under ClusterControl GUI → Activity Center → Jobs.

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

Importing via CLI is not currently implemented for SQL Server or Elasticsearch — use the GUI for those database types.

Database-Specific Settings

MySQL Replication

Database dropdown value: "MySQL Replication"

ClusterControl can manage and monitor existing MySQL and MariaDB servers, whether standalone or in a replication setup. 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.

When adding individual hosts, listing them together will place them in the same server group. For this to work, ClusterControl expects all instances within a group to use the same MySQL root password. It will also automatically try to identify each server's role (primary, replica, multi, or standalone).

When importing an existing MySQL Replication, ClusterControl will do the following:

Verify SSH connectivity to all nodes.
Detect the host environment and operating system.
Discover the database role of each node (primary, replica, multi, standalone).
Pull the configuration files.
Generate the authentication key and register the nodes into ClusterControl.

Default configuration

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

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

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

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

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

Attention

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

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
Server data directory: The database server data directory path that ClusterControl shall configure on all database nodes. If the path does not exist, ClusterControl will create and configure it automatically.
Admin/Root user: The database admin username that ClusterControl shall configure on all database nodes. This user will be granted global SUPER privilege and the GRANT option for localhost only.
Admin/Root password: The password for Admin/Root user.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.
information_schema queries: Off by default. When enabled, this allows ClusterControl to query the information_schema schema to collect metrics from your MySQL database nodes.
Cluster auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a degraded or failing cluster.
Node auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a failing node, for example one whose database process was unexpectedly terminated.

Add nodes fields

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.

CLI example

s9s cluster --register \
    --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' \
    --wait \
    --log

Regardless of node order, ClusterControl identifies the primary node(s) through the read_only and super_read_only variables.

MySQL Galera

Database dropdown value: "MySQL Galera"

ClusterControl can manage and monitor existing Galera Clusters, assuming all instances in the group use the same MySQL root password. Adding asynchronous slaves and adding load balancers connected to the Galera Cluster should be specified and imported separately after the cluster is imported into ClusterControl.

When importing an existing Galera Cluster, ClusterControl will perform the following:

Verify SSH connectivity to all nodes.
Detect the host environment and operating system.
Detect the remaining nodes in the cluster, only if Automatic node discovery is ON.
Pull the configuration files.
Generate the authentication key and register the nodes into ClusterControl.

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 importing your existing cluster:

Percona XtraDB Cluster - 8.0 and 8.4.
Percona XtraDB Cluster Pro - 8.4.
MariaDB Cluster - 10.4, 10.5, 10.6, 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.

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
Server data directory: The database server data directory path that ClusterControl shall configure on all database nodes. If the path does not exist, ClusterControl will create and configure it automatically.
Admin/Root user: The database admin username that ClusterControl shall configure on all database nodes. This user will be granted global SUPER privilege and the GRANT option for localhost only.
Admin/Root password: The password for Admin/Root user.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.
information_schema queries: Off by default. When enabled, this allows ClusterControl to query the information_schema schema to collect metrics from your MySQL database nodes.
Cluster auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a degraded or failing cluster.
Node auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a failing node, for example one whose database process was unexpectedly terminated.
Automatic node discovery: On by default. Set this to off if wsrep_node_incoming_address=AUTO for all of your primary Galera nodes, or if your ClusterControl node uses different IPs/hostnames to connect to Galera nodes for inter-node connectivity than the ones you pass here.

Add nodes fields

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.

CLI examples

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

s9s cluster --register \
    --cluster-type=galera \
    --nodes="10.10.10.11;10.10.10.12;10.10.10.13" \
    --vendor=percona \
    --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' \
    --wait \
    --log

Import a three-node MariaDB Cluster 11.4:

s9s cluster --register \
    --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 \
    --log

PostgreSQL Streaming

Database dropdown value: "PostgreSQL Streaming"

ClusterControl can manage and monitor existing PostgreSQL or TimescaleDB clusters running streaming replication version 12 or later. When importing hosts, those listed together will form a server group in the user interface. It is expected that all instances within the same group use the same database administrator password.

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 importing your existing cluster:

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

When importing an existing PostgreSQL or TimescaleDB streaming replication cluster, ClusterControl will perform the following:

Verify SSH connectivity to all nodes.
Detect the host environment and operating system.
Discover the database role of each node (primary, replica, TimescaleDB extension).
Pull the configuration files.
Generate the authentication key and register the nodes into ClusterControl.

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.

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
User: The database admin username that ClusterControl shall configure on all database nodes. This user will be granted global SUPERUSER role and allowed for localhost only.
Password: The password for User.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.

Add nodes fields

Primary node: Specify the IP address or hostname of the primary database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. Only one primary node is allowed for single-primary replication.
Replica nodes: Specify the IP address or hostname of the replica database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. You can specify zero or more replica nodes. If you have more than one replica node, make sure to add each of them under this field.

CLI examples

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

s9s cluster --register \
    --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' \
    --wait --log

Import 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 --register \
    --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='mydbuser' \
    --db-admin-passwd='mydbPassw0rd' \
    --enterprise-token='XXXXXXXXXXXXXXXXXXXXXXXXX' \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --cluster-name='System A - PostgreSQL EDB 16 - Streaming Replication' \
    --wait

TimescaleDB

Database dropdown value: "TimescaleDB"

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

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

Default configuration

By default, ClusterControl deploys TimescaleDB with the following configurations:

Configure and load the pg_stat_statements module and timescaledb extension.
The WAL level is set to replica.
All replica will be set with hot_standby.
Configure the cluster_name value.
ClusterControl will configure the TimescaleDB 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 import an existing PostgreSQL cluster and convert it to TimescaleDB at a later stage. However, this action is irreversible and ClusterControl will treat the cluster as TimescaleDB from that point onward.

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
User: The database admin username that ClusterControl shall configure on all database nodes. This user will be granted global SUPERUSER role and allowed for localhost only.
Password: The password for User.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.

Add nodes fields

Primary node: Specify the IP address or hostname of the primary database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. Only one primary node is allowed for single-primary replication.
Replica nodes: Specify the IP address or hostname of the replica database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic. You can specify zero or more replica nodes. If you have more than one replica node, make sure to add each of them under this field.

CLI examples

Import 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 --register \
    --cluster-type=postgresql \
    --nodes="10.10.10.11;10.10.10.12;10.10.10.13" \
    --vendor=postgresql \
    --provider-version=16 \
    --db-admin='mydbuser' \
    --db-admin-passwd='mydbPassw0rd' \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_rsa \
    --with-tags='production;timescaledb' \
    --cluster-name='TimescaleDB 16 - Streaming Replication' \
    --with-timescaledb

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

s9s cluster --register \
    --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

MongoDB Replica Set

Database dropdown value: "MongoDB ReplicaSet"

ClusterControl is able to manage and monitor an existing MongoDB or Percona Server for MongoDB replica set.

When importing an existing MongoDB replica set, ClusterControl will perform the following:

Verify SSH connectivity to all nodes.
Detect the host environment and operating system.
Discover the database role of each node (primary, secondary, arbiter).
Pull the configuration files.
Generate the authentication key and register the nodes into ClusterControl.

The database cluster will be automatically added to ClusterControl once the import completes successfully. If only one node is specified, ClusterControl will import it as a standalone MongoDB node. The following vendors and versions are supported for importing your existing cluster:

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

Attention

If SSL/TLS is required, ClusterControl only supports a proper CAFile configuration, as shown in the MongoDB documentation, and does not support the --allowInvalidCertificates flag.

Default configuration

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

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

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

Attention

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

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
User: The database admin username that ClusterControl shall configure on all database nodes. This user will be granted global SUPERUSER role and allowed for localhost only.
Password: The password for User.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.

Add nodes fields

Node: Specify the IP address or hostname of the primary database node only. 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. The secondary/replica nodes and arbiters are auto-detected and imported along with the primary.

CLI examples

Import a 2-node MongoDB replica set using Percona binaries. Only the primary node needs to be specified — the replica (in this example, at 192.168.40.191) is auto-detected and imported alongside it. This example uses ubuntu as the OS username and ed25519 as the SSH key algorithm, and waits for and prints the logs of the job:

s9s cluster --register \
    --cluster-type=mongodb \
    --nodes="192.168.40.190" \
    --vendor=percona \
    --provider-version='7.0' \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_ed25519 \
    --db-admin='mydbuser' \
    --db-admin-passwd='mydbPassw0rd' \
    --cluster-name='MongoDB Percona Server ReplicaSet 7.0' \
    --wait --log

Import a three-node MongoDB Enterprise replica set 7.0, with operating system user "root", running in the foreground:

s9s cluster --register \
    --cluster-type=mongodbenterprise \
    --nodes="192.168.40.155" \
    --vendor=mongodbenterprise \
    --provider-version='7.0' \
    --os-user=root \
    --os-key-file=/root/.ssh/id_rsa \
    --db-admin='mydbuser' \
    --db-admin-passwd='mydbPassw0rd' \
    --cluster-name='MongoDB Enterprise ReplicaSet 7.0'

MongoDB Sharded Cluster

Database dropdown value: "MongoDB Shards"

ClusterControl is able to manage and monitor an existing MongoDB, Percona Server for MongoDB, or MongoDB Enterprise 4.x, 5.x, 6.x, 7.x, or 8.x sharded cluster.

When importing an existing MongoDB sharded cluster, ClusterControl will perform the following:

Verify SSH connectivity to all nodes.
Detect the host environment and operating system.
Discover the database role of each node (mongos, config server, shard server - primary, secondary, arbiter).
Pull the configuration files.
Generate the authentication key and register the nodes into ClusterControl.

The following vendors and versions are supported for importing your existing cluster:

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

Default configuration

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

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

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

Attention

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

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
User: The database admin username that ClusterControl shall configure on all database nodes. This user will be granted global SUPERUSER role and allowed for localhost only.
Password: The password for User.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.

Add nodes fields

Node router server: Specify the IP address or hostname of a mongos (router) node only. 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. Specify only the MongoDB router servers (mongos); ClusterControl discovers the config servers and shard members automatically. If you have multiple router servers, add each of them here.

CLI example

Import a MongoDB sharded cluster using Percona binaries, consisting of 3 router (mongos) nodes, using ubuntu as the OS username and ed25519 as the SSH key algorithm, waiting for and printing the logs of the job:

s9s cluster --register \
    --cluster-type=mongodb \
    --nodes="mongos://192.168.1.11;mongos://192.168.1.12;mongos://192.168.1.12;" \
    --vendor=percona \
    --provider-version='7.0' \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_ed25519 \
    --db-admin='mydbuser' \
    --db-admin-passwd='mydbPassw0rd' \
    --cluster-name='MongoDB Percona Server Shards 7.0' \
    --wait --log

Valkey Sentinel

Database dropdown value: "Valkey Sentinel"

Imports existing Valkey instances with Sentinel, for v7 and v8. When importing existing Valkey instances, ClusterControl will perform the following:

Verify SSH connectivity to all nodes.
Detect the host environment and operating system.
Discover the database role of each node (primary, replica, sentinel).

Attention

ClusterControl does not support importing Valkey instances without authentication. Authentication must be enabled and the provided admin username and password must have ~* +@all (all keys, all commands) privilege.

The following vendors and versions are supported for importing your existing cluster:

Valkey Sentinel - 7 and 8
Canonical - 7

For a very minimal setup (suitable for testing and experimenting), it is possible to import a single-node Valkey instance with Sentinel (both services co-located on the same node), and later scale 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 import a two-node Valkey replication cluster (Sentinel will be co-located on each database instance).

Node configuration fields

Valkey port: The database server port that ClusterControl shall configure on all Valkey database nodes.
Valkey Sentinel port: The database server port that ClusterControl shall configure on all Valkey Sentinel nodes.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part. Choose "Create new repository" to let ClusterControl create a local repository for the chosen vendor on the ClusterControl node.
Password: Under the Authentication pane, the primary node password used for client/replica authentication.
Replication user: Under the Authentication pane, the replication user of your Valkey replication cluster.
Replication password: Under the Authentication pane, the replication password of your Valkey replication cluster.
Sentinel password: The password for your Sentinel user sentinel-user.
Use existing certificates: Specify cmon's certificates directory to use on the imported cluster. If SSL configuration is not completed, scale-up operations may fail.
Cluster auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a degraded or failing cluster.
Node auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a failing node.

Add nodes fields

Primary node: Specify the IP address or hostname of the primary database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic.
Replica nodes: Specify the IP address or hostname of a replica 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. If you have more than one replica node, make sure to add each of them under this field.

CLI example

Import a three-node Valkey Sentinel cluster, using ubuntu as the OS username, sjl2l5wi as the Sentinel password, and ed25519 as the SSH key algorithm, waiting for and printing the logs of the job:

s9s cluster --register --cluster-type=valkey \
    --nodes="valkey://192.168.40.190:6379; valkey://192.168.40.191:6379;valkey://192.168.40.192:6379; \
             valkey-sentinel://192.168.40.190:26379;valkey-sentinel://192.168.40.191:26379; \
             valkey-sentinel://192.168.40.192:26379;" \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_ed25519 \
    --sentinel-passwd sjl2l5wi \
    --vendor=valkey \
    --provider-version=8 \
    --cluster-name="My Valkey Sentinel v8" \
    --log --wait

Valkey Cluster

Database dropdown value: "Valkey Cluster"

Imports an existing Valkey Cluster, for v7 and v8. When importing existing Valkey instances, ClusterControl will perform the following:

Verify SSH connectivity to all nodes.
Detect the host environment and operating system.
Discover the database role of each node (primary, replica).

Attention

ClusterControl does not support importing Valkey instances without authentication. Authentication must be enabled and the provided admin username and password must have ~* +@all (all keys, all commands) privilege.

The following vendors and versions are supported for importing your existing cluster:

Valkey Cluster - 7 and 8
Canonical - 7

Default configuration

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

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

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.
Username: 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 Username.
Cluster auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a degraded or failing cluster.
Node auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a failing node.

Add nodes fields

Cluster node: Specify the IP address or hostname of any node in the cluster. 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. Specify one node and ClusterControl will discover the rest of the cluster members.

CLI example

Import a Valkey Cluster by specifying a single endpoint node. Only the primary needs to be specified — replicas (in this example, at 192.168.40.199) are auto-detected and imported alongside it. This example uses ubuntu as the OS username and ed25519 as the SSH key algorithm, and waits for and prints the logs of the job:

s9s cluster --register \
    --cluster-type=valkey_sharded \
    --nodes="valkey://192.168.40.198;" \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_ed25519 \
    --vendor=valkey \
    --provider-version=8 \
    --cluster-name="My Valkey Sharded Cluster" \
    --log --wait

Redis Sentinel

Database dropdown value: "Redis Sentinel"

Imports existing Redis instances with Sentinel, for v7 and v8. When importing existing Redis instances, ClusterControl will perform the following:

Verify SSH connectivity to all nodes.
Detect the host environment and operating system.
Discover the database role of each node (primary, replica, sentinel).

Attention

ClusterControl does not support importing Redis instances without authentication. Authentication must be enabled and the provided admin username and password must have ~* +@all (all keys, all commands) privilege.

The following vendors and versions are supported for importing your existing cluster:

Redis Sentinel - 6, 7 and 8

Info

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

Default configuration

By default, ClusterControl deploys Redis 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 import a two-node Redis replication cluster (Sentinel will be co-located on each database instance).

Node configuration fields

Redis port: The database server port that ClusterControl shall configure on all Redis database nodes.
Redis Sentinel port: The database server port that ClusterControl shall configure on all Redis Sentinel nodes.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part. Choose "Create new repository" to let ClusterControl create a local repository for the chosen vendor on the ClusterControl node.
Password: Under the Authentication pane, the primary node password used for client/replica authentication.
Replication user: Under the Authentication pane, the replication user of your Redis replication cluster.
Replication password: Under the Authentication pane, the replication password of your Redis replication cluster.
Sentinel password: The password for your Sentinel user sentinel-user.
Use existing certificates: Specify cmon's certificates directory to use on the imported cluster. If SSL configuration is not completed, scale-up operations may fail.
Cluster auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a degraded or failing cluster.
Node auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a failing node.

Add nodes fields

Primary node: Specify the IP address or hostname of the primary database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic.
Replica nodes: Specify the IP address or hostname of a replica 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. If you have more than one replica node, make sure to add each of them under this field.

CLI example

Import a three-node Redis Sentinel cluster, using ubuntu as the OS username, sjl2l5wi as the Sentinel password, and ed25519 as the SSH key algorithm, waiting for and printing the logs of the job:

s9s cluster --register --cluster-type=redis \
    --nodes="redis://192.168.40.190:6379; redis://192.168.40.191:6379;redis://192.168.40.192:6379; \
             redis-sentinel://192.168.40.190:26379;redis-sentinel://192.168.40.191:26379; \
             redis-sentinel://192.168.40.192:26379;" \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_ed25519 \
    --sentinel-passwd sjl2l5wi \
    --vendor=redis \
    --provider-version=8 \
    --cluster-name="My Redis Sentinel Cluster" \
    --log --wait

Redis Cluster

Database dropdown value: "Redis Cluster"

Imports an existing Redis Cluster, for v7 and v8. When importing existing Redis instances, ClusterControl will perform the following:

Verify SSH connectivity to all nodes.
Detect the host environment and operating system.
Discover the database role of each node (primary, replica).

Attention

ClusterControl does not support importing Redis instances without authentication. Authentication must be enabled and the provided admin username and password must have ~* +@all (all keys, all commands) privilege.

The following vendors and versions are supported for importing your existing cluster:

Redis Cluster - 6, 7 and 8
Canonical - 7

Info

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

Default configuration

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

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

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.
Username: 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 Username.
Cluster auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a degraded or failing cluster.
Node auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a failing node.

Add nodes fields

Cluster node: Specify the IP address or hostname of any node in the cluster. 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. Specify one node and ClusterControl will discover the rest of the cluster members.

CLI example

Import a Redis Cluster by specifying a single endpoint node. Only the primary needs to be specified — replicas (in this example, at 192.168.40.189) are auto-detected and imported alongside it. This example uses ubuntu as the OS username and ed25519 as the SSH key algorithm, and waits for and prints the logs of the job:

s9s cluster --register \
    --cluster-type=redis_sharded \
    --nodes="redis://192.168.40.188;" \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_ed25519 \
    --vendor=redis \
    --provider-version=8 \
    --cluster-name="My Redis Sharded Cluster" \
    --log --wait

Microsoft SQL Server

Database dropdown value: "SQL Server"

Imports an existing Microsoft SQL Server for Linux instance or Always On availability group - 2019, 2022 and 2025. When importing existing SQL Server instances, ClusterControl will perform the following:

Verify SSH connectivity to all nodes.
Detect the host environment and operating system.
Discover the database role of each node (primary, replica).

The following vendors and versions are supported:

Microsoft SQL Server for Linux - 2019, 2022 and 2025

Attention

A Microsoft SQL Server database node must have at least 2000 MB of memory. ClusterControl will abort the import job if this requirement is not met.

Default configuration

By default, ClusterControl manages 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 supports AlwaysOn with asynchronous-commit mode, where it does not wait for any secondary replica to write incoming transaction log records to disk.

Node configuration fields

Admin username: The username of your existing admin user.
Admin password: The password for the admin user.
Server port: This field is disabled during import; it is shown only as a reference for the port already in use.
Cluster auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a degraded or failing cluster.
Node auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a failing node.

Add nodes fields

Primary node: Specify the IP address or hostname of the primary database node. Press Enter to add the node, where ClusterControl will perform a pre-deployment check to verify if the node is reachable via SSH key-based authentication. If the target node has more than one network interface, you will be able to select or enter a separate IP address to be used only for database traffic.
Replica nodes: Specify the IP address or hostname of a replica 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 you have more than one replica node, make sure to add each of them under this field.

CLI example

Importing via CLI is not currently implemented for SQL Server; use the GUI instead.

Elasticsearch

Database dropdown value: "Elasticsearch"

Imports an existing Elasticsearch cluster, for 7.x and 8.x. When importing existing Elasticsearch instances, ClusterControl will perform the following:

Verify SSH connectivity to all nodes.
Detect the host environment and operating system.
Discover the database role of each node (master, data).

Attention

ClusterControl does not support importing Elasticsearch instances without authentication. Authentication must be enabled, and a valid sysadmin username and password must be provided.

The following vendor and versions are supported:

Elastic - 7.17, 8.3 and 8.15

Default configuration

By default, ClusterControl manages Elasticsearch with the following configurations:

For a 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 a 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 import job if this requirement is not met. See Hardware Requirement for Elasticsearch.

Node configuration fields

HTTP port: This field is disabled during import; it is shown only as a reference for the port already in use.
Certificates password: If specified, the password for a preexisting CA private key.
Admin username: The sysadmin username used by your Elasticsearch cluster.
Admin password: The sysadmin password used by your Elasticsearch cluster.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.
Use existing certificates: Specify cmon's certificates directory to use on the imported cluster. If left blank, ClusterControl searches the configuration folder /etc/elasticsearch or the default generation folder /usr/share/elasticsearch for certificate files (such as elastic-certificates.p12, elastic-stack-ca.p12, and elasticsearch-ssl-http.zip) on the node, to configure certificates on any new nodes added to the cluster. If SSL configuration is not completed, scale-up operations may fail.
Cluster auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a degraded or failing cluster.
Node auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a failing node.

Add nodes fields

Cluster node: Specify the IP address or hostname of the primary or master-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. Specify one node and ClusterControl will discover the rest of the cluster members; the specified node is also used to search for certificate files.

CLI example

Importing via CLI is not currently implemented for Elasticsearch; use the GUI instead.

MySQL Group Replication

Database dropdown value: "MySQL Group Replication"

ClusterControl can manage and monitor existing MySQL Group Replication clusters. A minimum of three nodes is required for MySQL Group Replication to achieve high availability and automatic failover. The cluster can be configured in either single-primary mode (one primary and multiple secondaries) or multi-primary mode (all nodes accept writes).

When importing an existing MySQL Group Replication cluster, ClusterControl will do the following:

Verify SSH connectivity to all nodes.
Detect the host environment and operating system.
Pull the configuration files.
Detect the remaining nodes in the cluster, only if Automatic node discovery is ON.
Register the nodes into ClusterControl.

The following vendors and versions are supported for importing your existing cluster:

Oracle MySQL 8.0 and 8.4

Default configuration

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

MySQL GTID is enabled with log_slave_updates enabled.
Group Replication plugin is loaded and configured.
Binary logging is enabled.
All database nodes in multi-primary mode will be configured with read_only=OFF to allow writes on all nodes.
The generated backup 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.
`rpl_user`	MySQL Group Replication.
`backupuser`	Backup and restore management.

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

Attention

MySQL Group Replication requires all nodes to be reachable by each other. Ensure that network connectivity between all nodes is properly configured before importing the cluster.

Node configuration fields

Server port: The database server port that ClusterControl shall configure on all database nodes.
Server data directory: The database server data directory path that ClusterControl shall configure on all database nodes.
Admin/Root user: The database admin username that ClusterControl shall configure on all database nodes. This user will be granted global SUPER privilege and the GRANT option for localhost only.
Admin/Root password: The password for Admin/Root user.
Repository: Choosing "Use vendor repositories" (default) lets ClusterControl provision software by setting up and using the database vendor's preferred software repository. ClusterControl will always install the latest version of what is provided at that moment. Choose "Do not setup vendor repositories" if you have a special configuration from the vendor (commonly for enterprise databases); ClusterControl will then skip the repository configuration part.
Replication user/Replication password: The credentials configured for replication.
information_schema queries: Off by default. When enabled, this allows ClusterControl to query the information_schema schema to collect metrics from your MySQL database nodes.
Cluster auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a degraded or failing cluster.
Node auto-recovery: Off by default. When enabled, ClusterControl will automatically attempt to recover a failing node, for example one whose database process was unexpectedly terminated.
Automatic node discovery: On by default. Set it to off if you want to specify each of the IPs/hostnames that ClusterControl should use to connect to the database nodes yourself.

Add nodes fields

Node: Specify the IP address or hostname of any database node in the group. Press Enter to add the node, where ClusterControl will perform a 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 just one node; ClusterControl automatically discovers the remaining nodes in the Group Replication cluster.

CLI example

Import an Oracle MySQL Group Replication 8.4 cluster, with operating system user ubuntu:

s9s cluster --register \
    --cluster-type=group_replication \
    --nodes="10.10.10.10,10.10.10.11,10.10.10.12" \
    --vendor=oracle \
    --provider-version=8.4 \
    --db-admin-passwd="mYpa$$word" \
    --repl-user="rpl_user" \
    --repl-passwd="mYrepLpa$$word" \
    --os-user=ubuntu \
    --os-key-file=/home/ubuntu/.ssh/id_rsa \
    --cluster-name="MySQL Group Replication 8.4" \
    --wait \
    --log

ClickHouse

Database dropdown value: "ClickHouse"

ClusterControl can manage and monitor existing ClickHouse clusters, whether standalone, replicated, or sharded. When importing an existing ClickHouse cluster, ClusterControl will perform the following:

Verify SSH connectivity to all nodes.
Detect the host environment and operating system.
Discover the cluster topology and the role of each node (data, keeper) from system.clusters.
Register the nodes into ClusterControl without modifying any existing configuration files.

The import is non-invasive: ClusterControl does not change the configuration files of the existing ClickHouse cluster. You may specify a single node as an endpoint and ClusterControl will automatically discover the rest of the cluster topology.

The following vendor and versions are supported for importing your existing cluster:

ClickHouse - 24.8 (LTS) and 25.3

Attention

ClusterControl does not support importing ClickHouse instances without authentication. Authentication must be enabled and a valid admin username and password provided. All ClickHouse communication is TLS-only.

Default configuration

By default, ClusterControl manages ClickHouse with the following configurations:

ClickHouse cluster communication is TLS-only, using the secure ports: 9440 (native TCP protocol), 8443 (HTTPS API), 9010 (interserver replication), 9281 (Keeper client) and 9234 (Keeper Raft).
Prometheus metrics are collected from port 9363.
An admin user (default admin) is used to connect to and monitor the cluster.

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

Node configuration fields

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

Add nodes fields

Node: Specify the IP address or hostname of any ClickHouse data node in the cluster. 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 just one node; ClusterControl automatically discovers the remaining data and keeper nodes in the ClickHouse cluster.

CLI examples

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

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

Import an existing ClickHouse 24.8 replicated cluster by specifying a single endpoint node. ClusterControl will discover the rest of the topology (data and keeper nodes) automatically:

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

Recommended Next Steps