From 62a9d4f8c1b11e36c5052696a9671c0ba4cda961 Mon Sep 17 00:00:00 2001 From: Johan Wikman Date: Fri, 31 May 2019 15:19:39 +0300 Subject: [PATCH] MXS-2524 Add MaxScale Clustrix tutorial --- Documentation/Documentation-Contents.md | 2 + .../Tutorials/MaxScale-Clustrix-Tutorial.md | 161 ++++++++++++++++++ 2 files changed, 163 insertions(+) create mode 100644 Documentation/Tutorials/MaxScale-Clustrix-Tutorial.md diff --git a/Documentation/Documentation-Contents.md b/Documentation/Documentation-Contents.md index cef6344f7..5ca89d9e6 100644 --- a/Documentation/Documentation-Contents.md +++ b/Documentation/Documentation-Contents.md @@ -49,6 +49,8 @@ These tutorials are for specific use cases and module combinations. - [MySQL Cluster Setup](Tutorials/MySQL-Cluster-Setup.md) - [RabbitMQ and Tee Filter Data Archiving Tutorial](Tutorials/RabbitMQ-And-Tee-Archiving.md) - [RabbitMQ Setup and MariaDB MaxScale Integration Tutorial](Tutorials/RabbitMQ-Setup-And-MaxScale-Integration.md) + - [Clustrix Monitor Tutorial](Tutorials/Configuring-Clustrix-Monitor.md) + - [MaxScale Clustrix Tutorial](Tutorials/MaxScale-Clustrix-Tutorial.md) Here are tutorials on monitoring and managing MariaDB MaxScale in cluster environments. diff --git a/Documentation/Tutorials/MaxScale-Clustrix-Tutorial.md b/Documentation/Tutorials/MaxScale-Clustrix-Tutorial.md new file mode 100644 index 000000000..1d412da68 --- /dev/null +++ b/Documentation/Tutorials/MaxScale-Clustrix-Tutorial.md @@ -0,0 +1,161 @@ +# MaxScale and Clustrix Tutorial + +Since version 2.4, MaxScale has built-in support for Clustrix. This +tutorial explains how to setup MaxScale in front of a Clustrix +cluster. + +There is no Clustrix specific router, but both the +[readconnroute](../Routers/ReadConnRoute.md) and +the [readwritesplit](../Routers/ReadWriteSplit.md) routers can be +used. + +## Clustrix and Readconnroute + +With _readconnroute_ you get simple connection based routing, where +each new connection is created (by default) to the Clustrix node with +the least amount of existing connections. That is, with readconnroute +the behaviour will be very similar to the behaviour when +[HAProxy](http://www.haproxy.org) is used as the Clustrix load +balancer. + +### Bootstrap servers + +The Clustrix monitor is capable of autonomously figuring out the cluster +configuration, but in order to get going there must be at least one +_server_-section referring to a node in the Clustrix cluster. +``` +[Bootstrap-1] +type=server +address=IP-OF-NODE +port=3306 +protocol=MySQLBackend +``` +That server defintion will be used by the monitor in order to connect +to the Clustrix cluster. There can be more than one such "bootstrap" +definition to cater for the case that the node used as a bootstrap +server is down when MaxScale starts. + +**NOTE** These bootstrap servers should _only_ be referred to from the + Clustrix monitor configuration, but _never_ from a service. + +### Monitor + +In the Clustrix monitor section, the bootstrap servers are referred to +in the same way as "ordinary" servers are referred to in other monitors. +``` +[Clustrix] +type=monitor +module=clustrixmon +servers=Bootstrap-1 +user=USER +password=PASSWORD +``` +The bootstrap servers are only used for connecting to the Clustrix +cluster; thereafter the Clustrix monitor will dynamically find out the +cluster configuration. + +The discovered cluster configuration will be stored (the ips and ports +of the Clustrix nodes) and upon subsequent restarts the Clustrix +monitor will use that information if the bootstrap servers happen to +be unavailable. + +With the configuration above `maxctrl list servers` might output +the following: +``` +┌───────────────────┬──────────────┬──────┬─────────────┬─────────────────┬──────┐ +│ Server │ Address │ Port │ Connections │ State │ GTID │ +├───────────────────┼──────────────┼──────┼─────────────┼─────────────────┼──────┤ +│ @@Clustrix:node-7 │ 10.2.224.102 │ 3306 │ 0 │ Master, Running │ │ +├───────────────────┼──────────────┼──────┼─────────────┼─────────────────┼──────┤ +│ @@Clustrix:node-8 │ 10.2.224.103 │ 3306 │ 0 │ Master, Running │ │ +├───────────────────┼──────────────┼──────┼─────────────┼─────────────────┼──────┤ +│ @@Clustrix:node-6 │ 10.2.224.101 │ 3306 │ 0 │ Master, Running │ │ +├───────────────────┼──────────────┼──────┼─────────────┼─────────────────┼──────┤ +│ Bootstrap-1 │ 10.2.224.101 │ 3306 │ 0 │ Master, Running │ │ +└───────────────────┴──────────────┴──────┴─────────────┴─────────────────┴──────┘ +``` +All servers whose name start with `@@` have been detected dynamically. + +Note that the address `10.2.224.101` appears twice; once for +`Bootstrap-1` and another time for `@@Clustrix:node-6`. The Clustrix +monitor will create a dynamic server instance for _all_ nodes in the +Clustrix cluster; also for the ones used in bootstrap server sections. + +### Service + +The service is specified as follows: +``` +[Clustrix-Service] +type=service +router=readconnroute +user=USER +password=PASSWORD +cluster=Clustrix +``` +Note that the service does *not* list any specific servers, but +instead refers, using the argument `cluster`, to the Clustrix monitor. + +In practice this means that the service will use the servers of the +monitor named `Clustrix` and in the case of a Clustrix monitor those +servers will be the ones that the monitor has detected +dynamically. That is, when setup like this, the service will +automatically adjust to any changes taking place in the Clustrix +cluster. + +### Listener + +To complete the configuration, a listener must be specified. +``` +[Clustrix-Service-Listener] +type=listener +service=Clustrix-Service +protocol=MariaDBClient +port=4008 +``` + +## Clustrix and Readwritesplit + +The primary purpose of the router _readwritesplit_ is to split +statements between one master and multiple slaves. In the case of +Clustrix, all servers will be masters, but _readwritesplit_ may still +be the right choise. + +Namely, as _readwritesplit_ is transaction aware and capable of +replaying transactions, it can be used for hiding certain events +taking place in Clustrix from the clients that use it. + +For instance, whenever a node is removed from or added to a Clustrix +cluster there will be a _group change_, which is visible to a client +as a transaction rollback. However, if _readwritesplit_ is used and +transaction replay is enabled, then MaxScale may be able to hide the +group change so that the client only detects a slight delay. + +Apart from the service section, the configuration when using +_readwritesplit_ is identical to the _readconnroute_ configuration +described above. + +### Service + +The service is specified as follows: +``` +[Clustrix-Service] +type=service +router=readwritesplit +user=maxscale +password=maxscale +cluster=Clustrix-Service +transaction_replay=true +``` +With this configuration, subject to the boundary conditions of +transaction replaying, a client will neither notice group change +events nor the disappearance of the very node the client is connected +to. In that latter case, MaxScale will simply connect to another node +and replay the current transaction (if one is active). + +For detailed information about the transaction replay functionality, +please refer to the _readwritesplit_ +[documentation](../Routers/ReadWriteSplit.md#transaction_replay). + +As a rule of thumb, use _readwritesplit_ if it is important that +changes taking place in the cluster configuration are hidden from the +applications, otherwise use _readconnroute_.