Deploy MaxScale 6 with Galera Monitor and Read/Write Split Router
This page is part of MariaDB's Enterprise Documentation.
The parent of this page is: MariaDB Deployment
Topics on this page:
Overview
This procedure provides instructions for deploying MariaDB MaxScale 6 with MariaDB Community Server. If you are using MariaDB Enterprise Server, see "Deploy Galera Cluster Topology".
These instructions detail how to deploy MariaDB MaxScale as a load balancing and high availability solution for Galera Cluster.
Prerequisites
These instructions assume that the back-end MariaDB Server instances have already been deployed.
See the following resources for how to deploy Cluster nodes:
MaxScale Components
These instructions detail the deployment of MaxScale with the following components:
Component | Description |
---|---|
| |
|
Term Definitions
Term | Definition |
---|---|
MaxScale instance |
|
Installation
MariaDB Corporation provides package repositories for YUM (RHEL, CentOS), APT (Debian, Ubuntu), and ZYpp (SLES).
Install via YUM (CentOS, RHEL)
Retrieve your Customer Download Token at https://customers.mariadb.com/downloads/token/ and substitute for
CUSTOMER_DOWNLOAD_TOKEN
in the following directions.Configure the YUM package repository.
Installable versions of MariaDB MaxScale are
6
,2.5
, and2.4
. Pass the version you want to install using the--mariadb-maxscale-version
flag to the mariadb_es_ script. The following directions referencerepo_ setup 6
.To configure YUM package repositories:
$ sudo yum install wget
$ wget https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup
$ echo "cfcd35671125d657a212d92b93be7b1f4ad2fda58dfa8b5ab4b601bf3afa4eae mariadb_es_repo_setup" \ | sha256sum -c -
$ chmod +x mariadb_es_repo_setup
$ sudo ./mariadb_es_repo_setup --token="CUSTOMER_DOWNLOAD_TOKEN" --apply \ --mariadb-maxscale-version="6"
Install MariaDB MaxScale and package dependencies:
$ sudo yum install maxscale
Configure MaxScale.
Installation only loads MariaDB MaxScale to the system. MariaDB MaxScale requires configuration before MaxScale is ready for use.
See Configuration.
Install via APT (Debian, Ubuntu)
Retrieve your Customer Download Token at https://customers.mariadb.com/downloads/token/ and substitute for
CUSTOMER_DOWNLOAD_TOKEN
in the following directions.Configure the APT package repository.
Installable versions of MariaDB MaxScale are
6
,2.5
, and2.4
. Pass the version you want to install using the--mariadb-maxscale-version
flag to the mariadb_es_ script. The following directions referencerepo_ setup 6
.To configure APT package repositories:
$ sudo apt install wget
$ wget https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup
$ echo "cfcd35671125d657a212d92b93be7b1f4ad2fda58dfa8b5ab4b601bf3afa4eae mariadb_es_repo_setup" \ | sha256sum -c -
$ chmod +x mariadb_es_repo_setup
$ sudo ./mariadb_es_repo_setup --token="CUSTOMER_DOWNLOAD_TOKEN" --apply \ --mariadb-maxscale-version="6"
$ sudo apt update
Install MariaDB MaxScale and package dependencies:
$ sudo apt install maxscale
Configure MaxScale.
Installation only loads MariaDB MaxScale to the system. MariaDB MaxScale requires configuration before MaxScale is ready for use.
See Configuration.
Install via ZYpp (SLES)
Retrieve your Customer Download Token at https://customers.mariadb.com/downloads/token/ and substitute for
CUSTOMER_DOWNLOAD_TOKEN
in the following directions.Configure the ZYpp package repository.
Installable versions of MariaDB MaxScale are
6
,2.5
, and2.4
. Pass the version you want to install using the--mariadb-maxscale-version
flag to the mariadb_es_ script. The following directions referencerepo_ setup 6
.To configure ZYpp package repositories:
$ sudo zypper install wget
$ wget https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup
$ echo "cfcd35671125d657a212d92b93be7b1f4ad2fda58dfa8b5ab4b601bf3afa4eae mariadb_es_repo_setup" \ | sha256sum -c -
$ chmod +x mariadb_es_repo_setup
$ sudo ./mariadb_es_repo_setup --token="CUSTOMER_DOWNLOAD_TOKEN" --apply \ --mariadb-maxscale-version="6"
Install MariaDB MaxScale and package dependencies:
$ sudo zypper install maxscale
Configure MaxScale.
Installation only loads MariaDB MaxScale to the system. MariaDB MaxScale requires configuration before MaxScale is ready for use.
See Configuration.
Configuration
MariaDB MaxScale's parameters can be configured in two ways:
All parameters can be set in a configuration file (such as the
/etc/maxscale.cnf
file). When the configuration file is updated, the MaxScale instance must be restarted to apply the changes.If a parameter supports dynamic changes, it can be set on-the-fly using the MaxCtrl utility.
Configure MaxScale's Global Parameters
Determine which global parameters you need to configure.
Useful global parameters for MariaDB MaxScale:
Parameter
Description
Sets the local IP address or network interface to use when connecting to MariaDB Community Servers.
Sets whether the MaxScale Instance supports the REST API. Disable to block access.
Sets the network interface used by the REST API.
Sets the port used by the REST API.
Sets whether the REST API uses HTTP Basic Access authentication. Users can be created wih maxctrl.
Set your global parameters in
maxscale.cnf
.MariaDB MaxScale global parameters, which apply to the all MaxScale modules, are set in the
[maxscale]
configuration group:For example:
[maxscale] admin_auth = true
Configure Servers
Determine which server parameters you need to configure.
Mandatory parameters for Server objects:
Parameter
Description
type
Set the module type to
server
.address
Set the IP address for the MariaDB Community Server.
port
Set the port the MariaDB Community Server listens on.
protocol
Set the protocol to
MariaDBBackend
to connect the Server.Set your server parameters in
maxscale.cnf
.For each Server in your deployment, add a new uniquely-named configuration group to the MaxScale Instance. The name of the configuration group is arbitrary, but it cannot contain any white space. Use whatever terms you find most convenient, but it is most common to use names like
serverN
or the server's host name.For example:
[server1] type = server address = 192.0.2.102 port = 3306 protocol = MariaDBBackend
Configure Galera Monitor
Determine which parameters for Galera Monitor (galeramon) you need to configure.
Mandatory parameters for Galera Monitor (
galeramon
):Parameter
Description
type
Set the type to
monitor
.module
Set to
galeramon
for MariaDB Enterprise Cluster.servers
Set to a comma-separated list of the Server object names.
user
Set to the user MariaDB MaxScale uses to connect to the Servers.
password
Set to the password MariaDB MaxScale uses to authenticate on the Servers.
Useful parameters for Galera Monitor (
galeramon
):Parameter
Description
disable_master_failback
If a node marked as master inside MaxScale happens to fail and the master status is assigned to another node MaxScale will normally return the master status to the original node after it comes back up. With this option enabled, if the master status is assigned to a new node it will not be reassigned to the original node for as long as the new master node is running.
available_when_donor
This option allows Galera nodes to be used normally when they are donors in an SST operation when the SST method is non-blocking.
Set your Galera Monitor parameters in
maxscale.cnf
.Add a new uniquely-named configuration group for the monitor to the MaxScale Instance. The name of the configuration group is arbitrary, but it cannot contain any white space. Use whatever terms you find most convenient, but it is most common to use names like
cluster-monitor
.For example:
[cluster-monitor] type = monitor module = galeramon servers = server1,server2,server3 user = maxscale password = max_passwd
Configure Read/Write Split Router
Determine which parameters for Read/Write Split Router (readwritesplit) you need to configure.
Mandatory parameters for Read/Write Split Router (
readwritesplit
):Parameter
Description
type
Set the module type as
service
.router
Use to set the type of router you want to use for the service. For the Read/Write Split router, set to
readwritesplit
.servers
Set as a comma-separated list of the Server object names.
user
Set the user you want the MaxScale Instance to use when connecting to Servers.
password
Set the password you want the MaxScale Instance to use in authentication when connecting to Servers.
Set your Read/Write Split Router parameters in
maxscale.cnf
.Add a new uniquely-named configuration group for the router to the MaxScale Instance. The name of the configuration group is arbitrary, but it cannot contain any white space. Use whatever terms you find most convenient, but it is most common to use names like
split-router
.For example:
[split-router] type = service router = readwritesplit servers = server1,server2,server3 user = maxscale password = max_passwd
Configure the Router's Listener
Determine which parameters for the listener you need to configure.
Mandatory parameters for the listener:
Parameter
Description
type
Set the module type as a
listener
.service
Use this parameter to connect the listener to a configured routing service.
protocol
Set this parameter to
MariaDBClient
to handle incoming client connections.port
Set this parameter to specify the port you want the MaxScale Instance to listen on.
Set your listener parameters in
maxscale.cnf
.Add a new uniquely-named configuration group for the listener to the MaxScale Instance. The name of the configuration group is arbitrary, but it cannot contain any white space. Use whatever terms you find most convenient, but it is most common to use names like
split-router-listener
.For example:
[split-router-listener] type = listener service = split-router protocol = MariaDBClient port = 3306
Configure the User Account
On each back-end MariaDB server, create the user account used by the monitor and the router using the CREATE USER statement. Make sure that the user account can connect from the MaxScale instance's IP address:
CREATE USER 'maxscale'@'192.0.2.101' IDENTIFIED BY 'max_passwd';
On each back-end MariaDB server, grant the required privileges to the user account used by the monitor and the router using the GRANT statement.
For the Read/Write Split Router (readwritesplit) , the global
SHOW DATABASES
privilege and theSELECT
privilege on several of the system's privilege tables are required:GRANT SHOW DATABASES ON *.* TO 'maxscale'@'192.0.2.101'; GRANT SELECT ON mysql.columns_priv TO 'maxscale'@'192.0.2.101'; GRANT SELECT ON mysql.db TO 'maxscale'@'192.0.2.101'; GRANT SELECT ON mysql.procs_priv TO 'mxs'@'192.0.2.101'; GRANT SELECT ON mysql.proxies_priv TO 'maxscale'@'192.0.2.101'; GRANT SELECT ON mysql.roles_mapping TO 'maxscale'@'192.0.2.101'; GRANT SELECT ON mysql.tables_priv TO 'maxscale'@'192.0.2.101'; GRANT SELECT ON mysql.user TO 'maxscale'@'192.0.2.101';
For Galera Monitor (galeramon), the required permissions depend on the version of MariaDB Enterprise Server that is being used.
In CS 10.5.8-5 and later, the following privileges are required:
GRANT BINLOG MONITOR, REPLICA MONITOR ON *.* TO 'maxscale'@'192.0.2.101';
In CS 10.5.6-4 and before, the following privileges are required:
GRANT BINLOG MONITOR, REPLICATION SLAVE ADMIN ON *.* TO 'maxscale'@'192.0.2.101';
In CS 10.4 and before, the following privileges are required:
GRANT REPLICATION CLIENT ON *.* TO 'maxscale'@'192.0.2.101';
Start the MaxScale Service
MariaDB MaxScale installations include configuration to start, stop, restart, enable/disable on boot, and check the status of the MaxScale Instance using the operating system default process management system.
For distributions that use systemd (most supported OSes), you can manage the MaxScale process using the systemctl
command:
Operation | Command |
Start |
|
Stop |
|
Restart |
|
Enable during startup |
|
Disable during startup |
|
Status |
|
Testing
When you have MariaDB MaxScale up and running, you should test it to ensure that it is working and that weren't any issues during startup.
Check MaxScale Status
Check that MaxScale is running properly by using the MaxCtrl utility:
$ sudo maxctrl show maxscale
┌──────────────┬──────────────────────────────────────────────────────────────────────┐ │ Version │ 6.4.1 │ ├──────────────┼──────────────────────────────────────────────────────────────────────┤ │ Commit │ 61b8bbf7f63c38ca9c408674e66f3627a0b2192e │ ├──────────────┼──────────────────────────────────────────────────────────────────────┤ │ Started At │ Fri, 30 Jul 2021 18:05:18 GMT │ ├──────────────┼──────────────────────────────────────────────────────────────────────┤ │ Activated At │ Fri, 30 Jul 2021 18:05:18 GMT │ ├──────────────┼──────────────────────────────────────────────────────────────────────┤ │ Uptime │ 109 │ ├──────────────┼──────────────────────────────────────────────────────────────────────┤ │ Parameters │ { │ │ │ "libdir": "/usr/lib/x86_64-linux-gnu/maxscale", │ │ │ "datadir": "/var/lib/maxscale", │ │ │ "process_datadir": "/var/lib/maxscale/data3850", │ │ │ "cachedir": "/var/cache/maxscale", │ │ │ "configdir": "/etc", │ │ │ "config_persistdir": "/var/lib/maxscale/maxscale.cnf.d", │ │ │ "module_configdir": "/etc/maxscale.modules.d", │ │ │ "piddir": "/var/run/maxscale", │ │ │ "logdir": "/var/log/maxscale", │ │ │ "langdir": "/var/lib/maxscale", │ │ │ "execdir": "/usr/bin", │ │ │ "connector_plugindir": "/usr/lib/x86_64-linux-gnu/mysql/plugin", │ │ │ "threads": 1, │ │ │ "thread_stack_size": 8388608, │ │ │ "writeq_high_water": 0, │ │ │ "writeq_low_water": 0, │ │ │ "auth_connect_timeout": 3, │ │ │ "auth_read_timeout": 1, │ │ │ "auth_write_timeout": 2, │ │ │ "skip_permission_checks": false, │ │ │ "admin_auth": true, │ │ │ "admin_enabled": true, │ │ │ "admin_log_auth_failures": true, │ │ │ "admin_host": "127.0.0.1", │ │ │ "admin_port": 8989, │ │ │ "admin_ssl_key": "", │ │ │ "admin_ssl_cert": "", │ │ │ "admin_ssl_ca_cert": "", │ │ │ "admin_pam_readwrite_service": "", │ │ │ "admin_pam_readonly_service": "", │ │ │ "passive": false, │ │ │ "query_classifier": "", │ │ │ "query_classifier_cache_size": 155008819, │ │ │ "retain_last_statements": 0, │ │ │ "dump_last_statements": "never", │ │ │ "session_trace": 0, │ │ │ "load_persisted_configs": true, │ │ │ "max_auth_errors_until_block": 10 │ │ │ } │ └──────────────┴──────────────────────────────────────────────────────────────────────┘