Step 5: Start and Configure MariaDB MaxScale 2.5

This page details step 5 of a 6-step procedure for deploying MariaDB Enterprise Cluster 10.2.

This step configures MariaDB MaxScale to route connections to MariaDB Enterprise Cluster.

Interactive commands are detailed. Alternatively, the described operations can be performed using automation.

Replace Default Configuration File

MariaDB MaxScale installations include a configuration file with some example objects. This configuration file should be replaced.

On the MaxScale node, replace the default /etc/maxscale.cnf with the following configuration:

[maxscale]
threads          = auto
admin_host       = 0.0.0.0
admin_secure_gui = false

For additional information, see "Global Parameters".

Restart MaxScale

On the MaxScale node, restart the MaxScale service to ensure that MaxScale picks up the new configuration:

$ sudo systemctl restart maxscale

Create MaxScale User Account

MariaDB MaxScale connects to Enterprise Cluster through the client port. MaxScale requires its own user account to monitor and orchestrate Enterprise Cluster nodes.

  1. On any Enterprise Cluster node, use the CREATE USER statement to create a new user for MaxScale:

    CREATE USER maxscale@192.0.2.4 IDENTIFIED BY "passwd";
    
  2. Use the GRANT statement to grant required privileges to the MaxScale user:

    GRANT SHOW DATABASES ON *.* TO maxscale@192.0.2.4;
    GRANT SELECT ON mysql.columns_priv TO maxscale@192.0.2.4;
    GRANT SELECT ON mysql.db TO maxscale@192.0.2.4;
    GRANT SELECT ON mysql.procs_priv TO maxscale@192.0.2.4;
    GRANT SELECT ON mysql.proxies_priv TO maxscale@192.0.2.4;
    GRANT SELECT ON mysql.roles_mapping TO maxscale@192.0.2.4;
    GRANT SELECT ON mysql.tables_priv TO maxscale@192.0.2.4;
    GRANT SELECT ON mysql.user TO maxscale@192.0.2.4;
    
  3. Use the GRANT statement to grant the privileges required by Galera Monitor:

    GRANT REPLICATION CLIENT
    ON *.* TO maxscale@192.0.2.4;
    

Enterprise Cluster replicates the new user and privileges to the other Enterprise Cluster nodes.

Configure Server Objects

MariaDB MaxScale uses server objects to define the connections it makes to MariaDB Enterprise Servers.

On the MaxScale node, use maxctrl create server to create a server object for each MariaDB Enterprise Server:

$ maxctrl create server node1 192.0.2.1
$ maxctrl create server node2 192.0.2.2
$ maxctrl create server node3 192.0.2.3

Configure the Galera Monitor

MaxScale uses monitors to retrieve additional information from the servers. This information is used by other services in filtering and routing connections based on the current state of the node. For Enterprise Cluster, use the Galera Monitor (galeramon).

On the MaxScale node, use maxctrl create monitor to create a Galera Monitor for the cluster:

$ maxctrl create monitor example-cluster galeramon \
      --monitor-user maxscale --monitor-password 'maxscale_passwd' \
      --servers node1 node2 node3

In this example:

  • example-cluster specifies an arbitrary name for the monitoring service.

  • galeramon indicates that the servers are nodes in Enterprise Cluster.

  • --monitor-user specifies the user account MaxScale uses in connecting to the servers.

  • --monitor-password specifies the password for the user account on the servers.

  • --servers indicates the servers MaxScale should monitor with this service.

Choose a MaxScale Router

Routers control how MaxScale balances the load between Enterprise Cluster nodes. Each router uses a different approach to routing queries. Consider the specific use case of your application and database load and select the router that best suits your needs.

Router

Configuration Procedure

Description

Read Connection (readconnroute)

Configure Read Connection Router

  • Connection-based load balancing

  • Routes connections to Enterprise Cluster nodes designated as replica servers for a read-only pool

  • Routes connections to an Enterprise Cluster node designated as the primary server for a read-write pool.

Read/Write Split (readwritesplit)

Configure Read/Write Split

  • Query-based load balancing

  • Routes write queries to an Enterprise Cluster node designated as the primary server

  • Routes read queries to Enterprise Cluster nodes designated as replica servers

  • Automatically reconnects after node failures

  • Automatically replays transactions after node failures

  • Optionally enforces causal reads

Read Connection Router

MaxScale Read Connection Router (readconnroute)

On the MaxScale node, use maxctrl create service to create a router:

$ maxctrl create service connection_router_service readconnroute \
      user=maxscale password=max_passwd \
      router_options=slave \
      --servers node1 node2 node3

In this example:

  • connection_router_service is the arbitrary name of this routing service.

  • readconnroute is the specific router to use with this service, the Read Connection Router.

  • user indicates the user account MaxScale uses to connect to the servers.

  • password indicates the password for the user account.

  • slave is the router_options, specified as a key=value pair. With this value, connections will only route to Enterprise Cluster nodes designated as replica servers.

  • --servers indicates the configured servers to which MaxScale should route queries.

Configure Listener for the Read Connection Router

These instructions reference TCP port 3308. You can use a different TCP port. The TCP port used must not be bound by any other listener.

On the MaxScale node, use the maxctrl create listener command to configure MaxScale to use a listener for the Read Connection Router (readconnroute):

$ maxctrl create listener connection_router_service connection_router_listener 3308 \
      --protocol=MariaDBClient

In this example:

  • connection_router_service is the name of the service that uses the Read Connection Router (readconnroute).

  • connection_router_listener is the name of the new listener.

  • 3308 is the TCP port.

  • MariaDBClient is the protocol, specified with the --protocol option.

  • Other Module Parameters supported by listeners in MaxScale 2.5 can also be specified.

Read/Write Split Router

MaxScale Read/Write Split Router (readwritesplit) performs query-based load balancing. The router routes write queries to the primary and read queries to the replicas.

On the MaxScale node, use the maxctrl create service command to configure MaxScale to use the Read/Write Split Router (readwritesplit):

$ maxctrl create service query_router_service readwritesplit  \
      user=maxscale \
      password=max_passwd \
      --servers node1 node2 node3

In this example:

  • query_router_service is the name of the new service that uses the Read/Write Split Router (readwritesplit).

  • readwritesplit is the name of the module that implements the Read/Write Split Router.

  • maxscale is the database user account for MaxScale, specified as a key=value pair.

  • max_passwd is the password for the database user account, specified as a key=value pair.

  • node1, node2, and node3 are the names of the configured server objects, specified with the --servers option.

  • Other Module Parameters supported by readwritesplit in MaxScale 2.5 can also be specified.

Configure a Listener for the Read/Write Split Router

These instructions reference TCP port 3307. You can use a different TCP port. The TCP port used must not be bound by any other listener.

On the MaxScale node, use the maxctrl create listener command to configure MaxScale to use a listener for the Read/Write Split Router (readwritesplit):

$ maxctrl create listener query_router_service query_router_listener 3307 \
      --protocol=MariaDBClient

In this example:

  • query_router_service is the name of the service that uses the Read/Write Split Router (readwritesplit).

  • query_router_listener is the name of the new listener.

  • 3307 is the TCP port.

  • MariaDBClient is the protocol, specified with the --protocol option.

  • Other Module Parameters supported by listeners in MaxScale 2.5 can also be specified.

Start Services

To start the services and monitors, on the MaxScale node use maxctrl start services:

$ maxctrl start services

Next Step

Navigation in the MariaDB Enterprise Cluster 10.2 deployment procedure:

  • This page was step 5 of 6.