diff --git a/Documentation/Documentation-Contents.md b/Documentation/Documentation-Contents.md index 16ec504f2..897cafb8f 100644 --- a/Documentation/Documentation-Contents.md +++ b/Documentation/Documentation-Contents.md @@ -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 diff --git a/Documentation/Monitors/Clustrix-Monitor.md b/Documentation/Monitors/Xpand-Monitor.md similarity index 77% rename from Documentation/Monitors/Clustrix-Monitor.md rename to Documentation/Monitors/Xpand-Monitor.md index 01f6e1c4f..7ef433f60 100644 --- a/Documentation/Monitors/Clustrix-Monitor.md +++ b/Documentation/Monitors/Xpand-Monitor.md @@ -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 ``` -@@:node- +@@:node- ``` -where `` is the name of the Clustrix monitor +where `` is the name of the Xpand monitor instance, as defined in the MaxScale configuration file, and `` 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. diff --git a/Documentation/Tutorials/Configuring-Clustrix-Monitor.md b/Documentation/Tutorials/Configuring-Xpand-Monitor.md similarity index 64% rename from Documentation/Tutorials/Configuring-Clustrix-Monitor.md rename to Documentation/Tutorials/Configuring-Xpand-Monitor.md index 0ee72fa6f..393e3d990 100644 --- a/Documentation/Tutorials/Configuring-Clustrix-Monitor.md +++ b/Documentation/Tutorials/Configuring-Xpand-Monitor.md @@ -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 `@@:node-, 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). \ No newline at end of file +[documentation](../Monitors/Xpand-Monitor.md). \ No newline at end of file diff --git a/Documentation/Tutorials/MaxScale-Clustrix-Tutorial.md b/Documentation/Tutorials/MaxScale-Xpand-Tutorial.md similarity index 74% rename from Documentation/Tutorials/MaxScale-Clustrix-Tutorial.md rename to Documentation/Tutorials/MaxScale-Xpand-Tutorial.md index f4624a929..aaf580a7a 100644 --- a/Documentation/Tutorials/MaxScale-Clustrix-Tutorial.md +++ b/Documentation/Tutorials/MaxScale-Xpand-Tutorial.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