MXS-2524 Add MaxScale Clustrix tutorial
This commit is contained in:
Johan Wikman
161
Documentation/Tutorials/MaxScale-Clustrix-Tutorial.md
Normal file
161
Documentation/Tutorials/MaxScale-Clustrix-Tutorial.md
Normal file
@ -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_.
|
||||
Reference in New Issue
Block a user