hcq/MaxScale
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MXS-3239 Update Clustix/Xpand documentation

Browse Source 
- 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
2020-10-19 14:15:39 +03:00
parent 3c2299d1b5
commit 0f1983fe1a
4 changed files with 102 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
Documentation/Documentation-Contents.md
View File

@ -49,8 +49,8 @@ These tutorials are for specific use cases and module combinations.
- [Filter Tutorial](Tutorials/Filter-Tutorial.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)
- [Xpand Monitor Tutorial](Tutorials/Configuring-Xpand-Monitor.md)
- [MaxScale Xpand Tutorial](Tutorials/MaxScale-Xpand-Tutorial.md)
Here are tutorials on monitoring and managing MariaDB MaxScale in cluster environments.
@ -110,7 +110,7 @@ Module specific documentation.
- [Galera Monitor](Monitors/Galera-Monitor.md)
- [ColumnStore Monitor](Monitors/ColumnStore-Monitor.md)
- [Aurora Monitor](Monitors/Aurora-Monitor.md)
- [Clustrix Monitor](Monitors/Clustrix-Monitor.md)
- [Xpand Monitor](Monitors/Xpand-Monitor.md)
## Protocols

67
Documentation/Monitors/Clustrix-Monitor.md → Documentation/Monitors/Xpand-Monitor.md
View File

@ -1,29 +1,32 @@
# Clustrix Monitor
# Xpand Monitor
**NOTE** The Xpand monitor is intended for use with a native Xpand
cluster, not with the Xpand storage engine.
## Overview
The Clustrix Monitor is a monitor that monitors a Clustrix cluster. It is
The Xpand Monitor is a monitor that monitors a Xpand cluster. It is
capable of detecting the cluster setup and creating corresponding server
instances within MaxScale.
## Configuration
A minimal configuration for a monitor requires one server in the Clustrix
A minimal configuration for a monitor requires one server in the Xpand
cluster, and a username and a password to connect to the server. Note that
by default the Clustrix monitor will only use that server in order to
by default the Xpand monitor will only use that server in order to
dynamically find out the configuration of the cluster; after startup it
will completely rely upon information obtained at runtime. To change the
default behaviour, please see the parameter
[dynamic_node_detection](#dynamic_node_detection).
To ensure that the Clustrix monitor will be able to start, it is adviseable
To ensure that the Xpand monitor will be able to start, it is adviseable
to provide _more_ than one server to cater for the case that not all nodes
are always up when MaxScale starts.
```
[TheClustrixMonitor]
[TheXpandMonitor]
type=monitor
module=clustrixmon
module=xpandmon
servers=server1,server2,server3
user=myuser
password=mypwd
@ -32,22 +35,22 @@ password=mypwd
## Dynamic Servers
The server objects the Clustrix monitor creates for each detected
Clustrix node will be named like
The server objects the Xpand monitor creates for each detected
Xpand node will be named like
```
@@<name-of-clustrix-monitor>:node-<id>
@@<name-of-xpand-monitor>:node-<id>
```
where `<name-of-clustrix-monitor>` is the name of the Clustrix monitor
where `<name-of-xpand-monitor>` is the name of the Xpand monitor
instance, as defined in the MaxScale configuration file, and `<id>` is the
id of the Clustrix node.
id of the Xpand node.
For instance, with the Clustrix monitor defined as above and a Clustrix
For instance, with the Xpand monitor defined as above and a Xpand
cluster consisting of 3 nodes whose ids are `1`, `2` and `3` respectively,
the names of the created server objects will be:
```
@@TheClustrixMonitor:node-1
@@TheClustrixMonitor:node-2
@@TheClustrixMonitor:node-3
@@TheXpandMonitor:node-1
@@TheXpandMonitor:node-2
@@TheXpandMonitor:node-3
```
### Grants
@ -76,9 +79,9 @@ The user name must be changed to the one actually being used.
For a list of optional parameters that all monitors support, read the
[Monitor Common](Monitor-Common.md) document.
## Clustrix Monitor optional parameters
## Xpand Monitor optional parameters
These are optional parameters specific to the Clustrix Monitor.
These are optional parameters specific to the Xpand Monitor.
### `cluster_monitor_interval`
@ -105,12 +108,12 @@ health_check_threshold=3
### `dynamic_node_detection`
By default, the Clustrix monitor will only use the bootstrap nodes
in order to connect to the Clustrix cluster and then find out the
By default, the Xpand monitor will only use the bootstrap nodes
in order to connect to the Xpand cluster and then find out the
cluster configuration dynamically at runtime.
That behaviour can be turned off with this optional parameter, in
which case all Clustrix nodes must manually be defined as shown below.
which case all Xpand nodes must manually be defined as shown below.
```
[Node-1]
@ -125,9 +128,9 @@ port=3306
[Node-3]
...
[Clustrix-Monitor]
[TheXpandMonitor]
type=monitor
module=clustrixmon
module=xpandmon
servers=Node-1, Node-2, Node-3
dynamic_node_detection=false
```
@ -151,26 +154,26 @@ is `false`. Note also that the port must be the same for all nodes.
## Commands
The Clustrix monitor supports the following module commands.
The Xpand monitor supports the following module commands.
### `softfail`
With the `softfail` module command, a node can be _softfailed_ via
MaxScale. The command requires as argument the name of the Clustrix
MaxScale. The command requires as argument the name of the Xpand
monitor instance (as defined in the configuration file) and the name
of the node to be softfailed.
For instance, with a configuration file like
```
[TheClustrixMonitor]
[TheXpandMonitor]
type=monitor
module=clustrixmon
module=xpandmon
...
```
then the node whose server name is `@@TheClustrixMonitor:node-1` can
then the node whose server name is `@@TheXpandMonitor:node-1` can
be softfailed like
```
$ maxctrl call command clustrixmon softfail TheClustrixMonitor @@TheClustrixMonitor:node-1
$ maxctrl call command xpandmon softfail TheXpandMonitor @@TheXpandMonitor:node-1
```
If the softfailing of a node is successfully initiated, then the status
of the corresponding MaxScale server object will be set to `Draining`,
@ -184,14 +187,14 @@ of the softfailing operation is.
### `unsoftfail`
With the `unsoftfail` module command, a node can be _unsoftfailed_ via
MaxScale. The command requires as argument the name of the Clustrix
MaxScale. The command requires as argument the name of the Xpand
monitor instance (as defined in the configuration file) and the name
of the node to be unsoftfailed.
With a setup similar to the `softfail` case, a node can be unsoftfailed
like:
```
$ maxctrl call command clustrixmon unsoftfail TheClustrixMonitor @@TheClustrixMonitor:node-1
$ maxctrl call command xpandmon unsoftfail TheXpandMonitor @@TheXpandMonitor:node-1
```
If a node is successfully softfailed, then a `Draining` status of
the corresponding MaxScale server object will be cleared.
@ -213,6 +216,6 @@ If a node that was softfailed is UNSOFTFAILed then the `Draining`
status will be cleared.
If the softfailing and unsoftfailing is initiated using the `softfail`
and `unsoftfail` commands of the Clustrix monitor, then there will be
and `unsoftfail` commands of the Xpand monitor, then there will be
no delay between the softfailing or unsoftfailing being initated and the
`Draining` status being turned on/off.

47
Documentation/Tutorials/Configuring-Clustrix-Monitor.md → Documentation/Tutorials/Configuring-Xpand-Monitor.md
View File

@ -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).

75
Documentation/Tutorials/MaxScale-Clustrix-Tutorial.md → Documentation/Tutorials/MaxScale-Xpand-Tutorial.md
View File

@ -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