Skip to content

Import Load Balancer

The Import Load Balancer feature in ClusterControl supports importing existing load balancer instances into its management console. It enables users to integrate external load balancers with imported database clusters, allowing centralized visibility, monitoring, and management from within ClusterControl.

With Import Load Balancer, it allows you to:

  • Import supported load balancers in front of your database clusters.
  • Monitor performance metrics such as throughput, latency, and active connections.
  • Automatically configure health checks and failover mechanisms.
  • Manage configuration changes.
  • Integrate with Keepalived to provide VIP-based failover.
  • Manage multiple load balancer instances for redundancy.

ClusterControl supports importing the following load balancer types:

  • ProxySQL
  • HAProxy
  • MariaDB MaxScale
  • Garbd
  • PgBouncer
  • Keepalived

Prerequisites

Before importing a load balancer, ensure the following:

  • You have a database cluster imported and managed by ClusterControl. Every load balancer must be associated with a database cluster, and can't be shared with another cluster.
  • Passwordless SSH (SSH using key-based authentication) is configured from the ClusterControl node to load balancer 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 node(s) are reachable from the ClusterControl server.

Support Matrix

Load Balancer Supported Databases
ProxySQL MySQL, MariaDB, Galera Cluster
HAProxy MySQL, MariaDB, Galera Cluster, PostgreSQL, TimescaleDB
MariaDB MaxScale MySQL, MariaDB, Galera Cluster
Garbd Galera Cluster
PgBouncer PostgreSQL, TimescaleDB
Keepalived For floating virtual IP address (VIP) setup. Support ProxySQL, HAProxy and MariaDB MaxScale

ProxySQL

This section is for ProxySQL nodes (MySQL/MariaDB replication, Galera Cluster). By default, ClusterControl imports ProxySQL in read/write split mode – your read-only traffic will be sent to replicas while your writes will be sent to a writable primary by creating two host groups. In case of primary failure, ProxySQL will detect the new writable primary and route writes to it automatically without any user intervention.

ProxySQL offers a wide range of features and capabilities that make it suitable for various scenarios, including improving the scalability, availability, performance, and security of MySQL database infrastructures. You can use an existing database server or another new host by specifying the hostname or IP address. With two or more ProxySQL nodes, you can then configure a virtual IP address service using Keepalived.

See also

Database Load Balancing for MySQL and MariaDB with ProxySQL – Tutorial

  1. Navigate to ClusterControl GUI → Select a cluster → Cluster Actions → Add new → Load balancer and choose Import balancer.

  2. Choose the load balancer service ProxySQL.

  3. Click Continue.

  4. You will be presented with a Import ProxySQL service, and on the step 1, it's on the Configuration:

    • Server address: Specify the hostname or IP address of the host. This host must be accessible via passwordless SSH from the ClusterControl node.
    • Admin port: ProxySQL administration port. The default is 6032.
    • Listening port: ProxySQL for MySQL load balancing. The default is 6033. This is where the applications and clients will connect after ProxySQL is activated.
    • Import configuration: By default, this is Off. If set to On, this means its enabled. A text field will show up allowing you to type the hostname of your source ProxySQL instance that contains the configuration.

  5. Click Continue to proceed to the Preview step. In this section, you can see the summary of your import and if everything is correct, you may proceed to import the load balancer by clicking Finish. You can always go back to any previous section to modify your configurations if you wish. The import settings will be kept until you exit the import wizard.

  6. ClusterControl will trigger an import job and the progress can be monitored under ClusterControl GUI → Activity Center → Jobs.

  • Import a ProxySQL node:

    s9s cluster \
    --register \
    --cluster-id=2 \
    --nodes="proxysql://10.10.10.103?db_username=proxysqluser&db_password=proxysqlpass&db_database='*.*'&db_privs='ALL PRIVILEGES'" \
    --wait \
    --log

HAProxy

This section is for HAProxy nodes (MySQL/MariaDB replication, Galera Cluster, PostgreSQL, TimescaleDB). ClusterControl will automatically install and configure HAProxy, install mysqlcheck script (for MySQL health checks) on each of the database nodes as part of xinetd service, and start the HAProxy service. If you set up read/write splitting for primary-replica replication, there will be two listening ports configured (one for read-write and another one for read-only connections). You can use an existing database server or another new host by specifying the hostname or IPv4 address. With two or more HAProxy nodes, you can then configure a virtual IP address service using Keepalived.

See also

MySQL Load Balancing with HAProxy – Tutorial

  1. Navigate to ClusterControl GUI → Select a cluster → Cluster Actions → Add new → Load balancer and choose Import balancer.

  2. Choose the load balancer service HAProxy.

  3. Click Continue.

  4. You will be presented with a Import HAProxy service, and on the step 1, it's on the Configuration:

    • Server address: Select which host to add the load balancer. If the host is not provisioned by ClusterControl, type in the IP address or hostname. The required files will be installed on the new host. Note that ClusterControl will access the new host using passwordless SSH.
    • Port: By default, this is set to 9600. This is the port to access stats for HAProxy. Unless you have different port, then change it to something else other than 9600.

    Then, click Continue to the next step.

  5. In Advanced settings section, specify:

    • Admin user: Admin username to access the HAProxy statistic page.
    • Admin password: Password for the admin user.
    • cmdline: This is a string of command line that will be executed to run the daemon service or server. By default, the value is /usr/sbin/haproxy -D -f /etc/haproxy/haproxy.cfg -sf $(cat /var/run/haproxy.pid)
    • LB name: This shall be the load balancer name. By default, this is set to lb_group1
    • Haproxy config: The default value is /etc/haproxy/haproxy.cfg. This is the path of the configuration for your HAProxy server.
    • Stats socket: The default value is /var/run/haproxy.socket. This is the path of the socket file for your haproxy server.

  6. Click Continue to proceed to the Preview step. In this section, you can see the summary of your import and if everything is correct, you may proceed to import the load balancer by clicking Finish. You can always go back to any previous section to modify your configurations if you wish. The import settings will be kept until you exit the import wizard.

  7. ClusterControl will trigger an import job and the progress can be monitored under ClusterControl GUI → Activity Center → Jobs.

  • Import an existing HAProxy node:

    s9s cluster \
    --register \
    --cluster-id=1 \
    --nodes="haproxy://10.10.10.101" \
    --wait \
    --log

MariaDB MaxScale

This section is for MariaDB MaxScale nodes (MySQL/MariaDB replication, Galera Cluster). MaxScale is an intelligent proxy that allows the forwarding of database statements to one or more database servers using complex rules, a semantic understanding of the database statements, and the roles of the various servers within the backend cluster of databases.

You can import the existing MaxScale node as a load balancer and query router for your Galera Cluster and MySQL/MariaDB replication. For new import using ClusterControl, by default, it will create two production services:

  • RW – Implements read-write split access.
  • RR – Implements round-robin access.

With two MaxScale nodes, you can then configure a virtual IP address service using Keepalived.

Attention

ClusterControl performs MariaDB MaxScale installation via direct package download without using the MariaDB repository. The package download URL is kept inside /usr/share/cmon/templates/packages.conf on the ClusterControl server under the [maxscale] section. Occasionally, the provided URL will be outdated as MariaDB releases a new minor version, and removes the older minor version for a specific MaxScale major version. If that is the case, a manual modification is required to update the download link in this file. The updated download URL is available on the MariaDB MaxScale website.

  1. Navigate to ClusterControl GUI → Select a cluster → Cluster Actions → Add new → Load balancer and choose Import balancer.

  2. Choose the load balancer service MariaDB MaxScale.

  3. Click Continue.

  4. You will be presented with a Import MaxScale service import wizard. Specify:

    • Server address: The IP address of the node where MaxScale will be installed. ClusterControl must be able to perform passwordless SSH to this host.
    • Threads: How many threads MaxScale is allowed to use.
    • RR Port: Port for round-robin listener. The default is 4006.
    • RW Post: Port for the read-write split listener. The default is 4008.
    • Disable firewall: Whether ClusterControl should disable firewall (iptables, ufw, firewalld) on the node during import. 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 import otherwise there is a risk of failure import. 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.

    Then, click Continue to the next step.

  5. Under the Configuration section, specify the credentials that ClusterControl should use to create the load balancer:

    • MaxScale admin username: MaxScale admin username. The default is ‘admin’.
    • MaxScale admin password: MaxScale enforces that the admin password for admin user ‘admin’ is ‘mariadb’. If you want to change or use another password you must create another user. The ‘admin’ user can later be dropped.
    • MaxScale MySQL username: MariaDB/MySQL user that will be used by MaxScale to access and monitor the MariaDB/MySQL nodes.
    • MaxScale MySQL password: Password of MaxScale MySQL Username.

  6. In the Server instances section, switch on the instances you want to be included in the load balancer.

  7. Click Continue to proceed to the Preview step. In this section, you can see the summary of your import and if everything is correct, you may proceed to import the load balancer by clicking Finish. You can always go back to any previous section to modify your configurations if you wish. The import settings will be kept until you exit the import wizard.

  8. ClusterControl will trigger an import job and the progress can be monitored under ClusterControl GUI → Activity Center → Jobs.

  • Import an existing MaxScale node:

    s9s node \
    --register \
    --cluster-id=2 \
    --nodes="maxscale://10.10.10.104" \
    −−maxscale-mysql-user=maxscaleuser \
    −−maxscale-mysql-password=maxscalepass \
    --wait \
    --log

Garbd

Exclusive for Galera Cluster. Galera arbitrator daemon (garbd) can be installed to avoid network partitioning or split-brain scenarios. If you already have an existing Galera arbitrator daemon running, you can import it into ClusterControl.

  1. Navigate to ClusterControl GUI → Select a cluster → Cluster Actions → Add new → Load balancer and choose Import balancer.

  2. Choose the load balancer service Garbd.

  3. Click Continue.

  4. You will be presented with a Import garbd service import wizard. Specify:

    • Server address: The server address that ClusterControl will use to import the load balancer. ClusterControl must be able to perform passwordless SSH to this host.
    • CmdLine: Garbd command line to start garbd process on the target node.
    • Disable firewall: Whether ClusterControl should disable firewall (iptables, ufw, firewalld) on the node during import. 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 import otherwise there is a risk of failure import. 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.

    Then, click Continue to the next step.

  5. Click Continue to proceed to the Preview step. In this section, you can see the summary of your import and if everything is correct, you may proceed to import the load balancer by clicking Finish. You can always go back to any previous section to modify your configurations if you wish. The import settings will be kept until you exit the import wizard.

  6. ClusterControl will trigger an import job and the progress can be monitored under ClusterControl GUI → Activity Center → Jobs.

Attention

ClusterControl does not support and allow garbd import on a server where ClusterControl is also running and hosted. There is a tendency that the existing MySQL packages will be removed which is managed by the software packaging tools.

PgBouncer

This section is for PgBouncer nodes (PostgreSQL, TimescaleDB). PgBouncer is a lightweight connection pooler for PostgreSQL. It reduces PostgreSQL resource consumption (memory, backends, fork) and supports online restart or upgrade without dropping client connections.

Using ClusterControl, you can manage PgBouncer on one or more nodes, manage multiple pools per node and support 3 pool modes:

  • session (default): When a client connects, a server connection will be assigned to it for the whole duration the client stays connected. When the client disconnects, the server connection will be put back into the pool.
  • transaction: A server connection is assigned to a client only during a transaction. When PgBouncer notices that the transaction is over, the server connection will be put back into the pool.
  • statement: The server connection will be put back into the pool immediately after a query completes. Multi-statement transactions are disallowed in this mode as they would break.

  1. Navigate to ClusterControl GUI → Select a cluster → Cluster Actions → Add new → Load balancer and choose Import balancer.

  2. Choose the load balancer service PgBouncer.

  3. Click Continue.

  4. You will be presented with a Import PgBouncer service import wizard. In the first step, under Authentication, specify the following fields below:

    • PgBouncer admin user: PgBouncer admin username you currently used in your PgBouncer
    • PgBouncer admin password: The password for the PgBouncer admin user.

  5. Under the Add nodes section, specify the nodes where to import PgBouncer and the Listening port to be used (default is 6432).

  6. Click Continue to proceed to the Preview step. In this section, you can see the summary of your import and if everything is correct, you may proceed to import the load balancer by clicking Finish. You can always go back to any previous section to modify your configurations if you wish. The import settings will be kept until you exit the import wizard.

  7. ClusterControl will trigger an import job and the progress can be monitored under ClusterControl GUI → Activity Center → Jobs.

  • Import an existing PgBouncer node:

    s9s node \
    --register \
    --cluster-id=4 \
    --nodes="pgbouncer://10.10.10.107" \
    --wait \
    --log

Keepalived

This section is for Keepalived import. Keepalived requires two or more HAProxy, ProxySQL, or MariaDB MaxScale instances to provide virtual IP address failover. By default, the virtual IP address will be assigned to instance ‘Keepalived 1’. If the node goes down, the IP address will automatically fail over to ‘Keepalived 2’ accordingly.

Keepalived uses the IP Virtual Server (IPVS) kernel module to provide transport layer (Layer 4) load balancing, redirecting requests for network-based services to individual members of a server cluster.

See also

How ClusterControl Configures Virtual IP and What to Expect During Failover

  1. Navigate to ClusterControl GUI → Select a cluster → Cluster Actions → Add new → Load balancer and choose Import balancer.

  2. Choose the load balancer service Keepalived.

  3. Click Continue.

  4. You will be presented with a Import Keepalived service import wizard:

    • Keepalived: Choose the servers that contains your Keepalived instance. Take note that importing a Keepalived requires that the host/node shall be existing in the cluster.

  5. Click Continue.

  6. Under the Host configuration section, specify the virtual IP address and network interface that is currently used by your existing Keepalived in your database cluster.

    Attention

    Make sure the network interface matches the name of the network interface in the nodes.

  7. Click Continue to proceed to the Preview step. In this section, you can see the summary of your import and if everything is correct, you may proceed to import the load balancer by clicking Finish. You can always go back to any previous section to modify your configurations if you wish. The import settings will be kept until you exit the import wizard.

  8. ClusterControl will trigger an import job and the progress can be monitored under ClusterControl GUI → Activity Center → Jobs.

Copyright © 2014-2025 Severalnines AB. All rights reserved.

Severalnines and ClusterControl are registered trademarks in the US, UK, and EU. The 3rd-party trademarks on this site are property of their respective owners and are used for referential purposes only.

Made with Material for MkDocs