MXS-3239 Update Clustix/Xpand documentation
- Rename files - Change Clustrix -> Xpand in files - Update links - Add warning that the monitor is intended for use with a native Xpand cluster, not with the Xpand storage engine.
This commit is contained in:
Johan Wikman
@ -1,16 +1,19 @@
|
||||
# Configuring the Clustrix Monitor
|
||||
# Configuring the Xpand Monitor
|
||||
|
||||
This document describes how to configure the Clustrix monitor for use
|
||||
with a Clustrix cluster.
|
||||
**NOTE** The Xpand monitor is intended for use with a native Xpand
|
||||
cluster, not with the Xpand storage engine.
|
||||
|
||||
This document describes how to configure the Xpand monitor for use
|
||||
with a Xpand cluster.
|
||||
|
||||
## Configuring the Monitor
|
||||
|
||||
Contrary to the other monitors of MaxScale, the Clustrix monitor will
|
||||
autonomously figure out the cluster configuration and for each Clustrix
|
||||
Contrary to the other monitors of MaxScale, the Xpand monitor will
|
||||
autonomously figure out the cluster configuration and for each Xpand
|
||||
node create the corresponding MaxScale server object.
|
||||
|
||||
In order to do that, a _sufficient_ number of "bootstrap" server instances
|
||||
must be specified in the MaxScale configuration file for the Clustrix
|
||||
must be specified in the MaxScale configuration file for the Xpand
|
||||
monitor to start with. One server instance is in principle sufficient, but
|
||||
if the corresponding node happens to be down when MaxScale starts, the
|
||||
monitor will not be able to function.
|
||||
@ -30,14 +33,14 @@ protocol=mariadbbackend
|
||||
```
|
||||
|
||||
The server configuration is identical with that of any other server, but since
|
||||
these servers are _only_ used for bootstrapping the Clustrix monitor it is
|
||||
these servers are _only_ used for bootstrapping the Xpand monitor it is
|
||||
adviceable to use names that clearly will identify them as such.
|
||||
|
||||
The actual Clustrix monitor configuration looks as follows:
|
||||
The actual Xpand monitor configuration looks as follows:
|
||||
```
|
||||
[Clustrix]
|
||||
[Xpand]
|
||||
type=monitor
|
||||
module=clustrixmon
|
||||
module=xpandmon
|
||||
servers=Bootstrap1, Bootstrap2
|
||||
user=monitor_user
|
||||
password=monitor_password
|
||||
@ -56,19 +59,19 @@ is, access the `system` tables of the Cluster for checking the Cluster
|
||||
configuration. The default values are `2000` and `60000`, that is, 2 seconds
|
||||
and 1 minute, respectively.
|
||||
|
||||
For each detected Clustrix node a corresponding MaxScale server object will be
|
||||
For each detected Xpand node a corresponding MaxScale server object will be
|
||||
created, whose name is `@@<Monitor-Name>:node-<id>, where _Monitor-Name_
|
||||
is the name of the monitor, in this example `Clustrix` and _id_ is the node id
|
||||
of the Clustrix node. So, with a cluster of three nodes, the created servers
|
||||
is the name of the monitor, in this example `Xpand` and _id_ is the node id
|
||||
of the Xpand node. So, with a cluster of three nodes, the created servers
|
||||
might be named like.
|
||||
|
||||
```
|
||||
@@Clustrix:node-2`
|
||||
@@Clustrix:node-3`
|
||||
@@Clustrix:node-7`
|
||||
@@Xpand:node-2`
|
||||
@@Xpand:node-3`
|
||||
@@Xpand:node-7`
|
||||
```
|
||||
Note that as these are created at runtime and may disappear at any moment,
|
||||
depending on changes happening in and made to the Clustrix cluster, they
|
||||
depending on changes happening in and made to the Xpand cluster, they
|
||||
should never be referred to directly from service configurations. Instead,
|
||||
services should refer to the monitor, as shown in the following:
|
||||
```
|
||||
@ -77,12 +80,12 @@ type=service
|
||||
router=readconnroute
|
||||
user=service_user
|
||||
password=service_password
|
||||
cluster=Clustrix
|
||||
cluster=Xpand
|
||||
```
|
||||
Instead of listing the servers of the service explicitly using the `servers`
|
||||
parameter as usually is the case, the service refers to the Clustrix monitor
|
||||
using the `cluster` parameter. This will cause the service to use the Clustrix
|
||||
nodes that the Clustrix monitor discovers at runtime.
|
||||
parameter as usually is the case, the service refers to the Xpand monitor
|
||||
using the `cluster` parameter. This will cause the service to use the Xpand
|
||||
nodes that the Xpand monitor discovers at runtime.
|
||||
|
||||
For additional details, please consult the monitor
|
||||
[documentation](../Monitors/Clustrix-Monitor.md).
|
||||
[documentation](../Monitors/Xpand-Monitor.md).
|
||||
@ -1,28 +1,31 @@
|
||||
# MaxScale and Clustrix Tutorial
|
||||
# MaxScale and Xpand Tutorial
|
||||
|
||||
Since version 2.4, MaxScale has built-in support for Clustrix. This
|
||||
tutorial explains how to setup MaxScale in front of a Clustrix
|
||||
**NOTE** The Xpand monitor is intended for use with a native Xpand
|
||||
cluster, not with the Xpand storage engine.
|
||||
|
||||
Since version 2.4, MaxScale has built-in support for Xpand. This
|
||||
tutorial explains how to setup MaxScale in front of a Xpand
|
||||
cluster.
|
||||
|
||||
There is no Clustrix specific router, but both the
|
||||
There is no Xpand specific router, but both the
|
||||
[readconnroute](../Routers/ReadConnRoute.md) and
|
||||
the [readwritesplit](../Routers/ReadWriteSplit.md) routers can be
|
||||
used.
|
||||
|
||||
## Clustrix and Readconnroute
|
||||
## Xpand and Readconnroute
|
||||
|
||||
With _readconnroute_ you get simple connection based routing, where
|
||||
each new connection is created (by default) to the Clustrix node with
|
||||
each new connection is created (by default) to the Xpand 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
|
||||
[HAProxy](http://www.haproxy.org) is used as the Xpand load
|
||||
balancer.
|
||||
|
||||
### Bootstrap servers
|
||||
|
||||
The Clustrix monitor is capable of autonomously figuring out the cluster
|
||||
The Xpand 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.
|
||||
_server_-section referring to a node in the Xpand cluster.
|
||||
```
|
||||
[Bootstrap-1]
|
||||
type=server
|
||||
@ -31,31 +34,31 @@ 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"
|
||||
to the Xpand 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.
|
||||
Xpand monitor configuration, but _never_ from a service.
|
||||
|
||||
### Monitor
|
||||
|
||||
In the Clustrix monitor section, the bootstrap servers are referred to
|
||||
In the Xpand monitor section, the bootstrap servers are referred to
|
||||
in the same way as "ordinary" servers are referred to in other monitors.
|
||||
```
|
||||
[Clustrix]
|
||||
[Xpand]
|
||||
type=monitor
|
||||
module=clustrixmon
|
||||
module=xpandmon
|
||||
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
|
||||
The bootstrap servers are only used for connecting to the Xpand
|
||||
cluster; thereafter the Xpand 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
|
||||
of the Xpand nodes) and upon subsequent restarts the Xpand
|
||||
monitor will use that information if the bootstrap servers happen to
|
||||
be unavailable.
|
||||
|
||||
@ -65,11 +68,11 @@ the following:
|
||||
┌───────────────────┬──────────────┬──────┬─────────────┬─────────────────┬──────┐
|
||||
│ Server │ Address │ Port │ Connections │ State │ GTID │
|
||||
├───────────────────┼──────────────┼──────┼─────────────┼─────────────────┼──────┤
|
||||
│ @@Clustrix:node-7 │ 10.2.224.102 │ 3306 │ 0 │ Master, Running │ │
|
||||
│ @@Xpand:node-7 │ 10.2.224.102 │ 3306 │ 0 │ Master, Running │ │
|
||||
├───────────────────┼──────────────┼──────┼─────────────┼─────────────────┼──────┤
|
||||
│ @@Clustrix:node-8 │ 10.2.224.103 │ 3306 │ 0 │ Master, Running │ │
|
||||
│ @@Xpand:node-8 │ 10.2.224.103 │ 3306 │ 0 │ Master, Running │ │
|
||||
├───────────────────┼──────────────┼──────┼─────────────┼─────────────────┼──────┤
|
||||
│ @@Clustrix:node-6 │ 10.2.224.101 │ 3306 │ 0 │ Master, Running │ │
|
||||
│ @@Xpand:node-6 │ 10.2.224.101 │ 3306 │ 0 │ Master, Running │ │
|
||||
├───────────────────┼──────────────┼──────┼─────────────┼─────────────────┼──────┤
|
||||
│ Bootstrap-1 │ 10.2.224.101 │ 3306 │ 0 │ Master, Running │ │
|
||||
└───────────────────┴──────────────┴──────┴─────────────┴─────────────────┴──────┘
|
||||
@ -77,29 +80,29 @@ the following:
|
||||
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
|
||||
`Bootstrap-1` and another time for `@@Xpand:node-6`. The Xpand
|
||||
monitor will create a dynamic server instance for _all_ nodes in the
|
||||
Clustrix cluster; also for the ones used in bootstrap server sections.
|
||||
Xpand cluster; also for the ones used in bootstrap server sections.
|
||||
|
||||
### Service
|
||||
|
||||
The service is specified as follows:
|
||||
```
|
||||
[Clustrix-Service]
|
||||
[Xpand-Service]
|
||||
type=service
|
||||
router=readconnroute
|
||||
user=USER
|
||||
password=PASSWORD
|
||||
cluster=Clustrix
|
||||
cluster=Xpand
|
||||
```
|
||||
Note that the service does *not* list any specific servers, but
|
||||
instead refers, using the argument `cluster`, to the Clustrix monitor.
|
||||
instead refers, using the argument `cluster`, to the Xpand 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
|
||||
monitor named `Xpand` and in the case of a Xpand 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
|
||||
automatically adjust to any changes taking place in the Xpand
|
||||
cluster.
|
||||
|
||||
**NOTE** There is no need to specify any `router_options`, but the
|
||||
@ -111,25 +114,25 @@ cause only a _single_ node to be used.
|
||||
|
||||
To complete the configuration, a listener must be specified.
|
||||
```
|
||||
[Clustrix-Service-Listener]
|
||||
[Xpand-Service-Listener]
|
||||
type=listener
|
||||
service=Clustrix-Service
|
||||
service=Xpand-Service
|
||||
protocol=MariaDBClient
|
||||
port=4008
|
||||
```
|
||||
|
||||
## Clustrix and Readwritesplit
|
||||
## Xpand 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
|
||||
Xpand, 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.
|
||||
taking place in Xpand from the clients that use it.
|
||||
|
||||
For instance, whenever a node is removed from or added to a Clustrix
|
||||
For instance, whenever a node is removed from or added to a Xpand
|
||||
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
|
||||
@ -143,12 +146,12 @@ described above.
|
||||
|
||||
The service is specified as follows:
|
||||
```
|
||||
[Clustrix-Service]
|
||||
[Xpand-Service]
|
||||
type=service
|
||||
router=readwritesplit
|
||||
user=maxscale
|
||||
password=maxscale
|
||||
cluster=Clustrix
|
||||
cluster=Xpand
|
||||
transaction_replay=true
|
||||
slave_selection_criteria=LEAST_GLOBAL_CONNECTIONS
|
||||
```
|
||||
@ -163,7 +166,7 @@ to the _readwritesplit_
|
||||
|
||||
**NOTE** It is vital to have
|
||||
`slave_selection_criteria=LEAST_GLOBAL_CONNECTIONS`, as otherwise
|
||||
connections will **not** be distributed evenly across all Clustrix
|
||||
connections will **not** be distributed evenly across all Xpand
|
||||
nodes.
|
||||
|
||||
As a rule of thumb, use _readwritesplit_ if it is important that
|
||||
Reference in New Issue
Block a user