From b2bf4d125ba21187cd755d5d935cbef277f042c9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= <markus.makela@mariadb.com>
Date: Sun, 10 Mar 2019 11:20:46 +0200
Subject: [PATCH] MXS-2313: Document rank

Added documentation along with a few examples of how the parameter behaves
and how it can be used.
---
 .../Getting-Started/Configuration-Guide.md    | 92 +++++++++++++++++++
 1 file changed, 92 insertions(+)

diff --git a/Documentation/Getting-Started/Configuration-Guide.md b/Documentation/Getting-Started/Configuration-Guide.md
index 0e92275fe..7d2daa0fe 100644
--- a/Documentation/Getting-Started/Configuration-Guide.md
+++ b/Documentation/Getting-Started/Configuration-Guide.md
@@ -1556,6 +1556,98 @@ Note that the path to be used, is one of the paths returned by:
 There is no default value, but this parameter must be explicitly specified
 if the disk space situation should be monitored.
 
+#### `rank`
+
+The ranking of this server. Servers with a lower value of `rank` are prioritized
+over servers with a higher value. This parameter is intended to allow the user
+to control in which order the servers of a cluster are used.
+
+The default value is 2147483647 which is also the upper limit for the value. The
+lowest accepted value is 1. This parameter replaces the use of the `weightby`
+parameter as the primary means of controlling server usage.
+
+Each server that shares the same `rank` is placed into a set and only one set of
+servers is used at any one time. This behavior depends on the router
+implementation which is why there are a few exceptions to this rule.
+
+One exception to the rule is when a readwritesplit session must find a master
+server but the rank of the master is not the lowest among all available
+servers. In this case readwritesplit will pick the master with the lowest value
+of rank among all master servers.
+
+The following example configuration demonstrates how the parameter is used.
+
+```
+[A]
+type=server
+address=192.168.0.11
+protocol=MariaDBBackend
+rank=1
+
+[B]
+type=server
+address=192.168.0.22
+protocol=MariaDBBackend
+rank=2
+
+[C]
+type=server
+address=192.168.0.33
+protocol=MariaDBBackend
+rank=2
+
+[D]
+type=server
+address=192.168.0.44
+protocol=MariaDBBackend
+```
+
+The three servers, A, B and C, each have a `rank` value. Server D has no rank so
+the default value is used. Three distinct sets of servers are created:
+
+1. A
+2. B and C
+3. D
+
+If A is available, it will always be used. When A is not available, both B and C
+are used. Only when D is the last available server will it be used.
+
+Another example use-case for this is a remote server (D) replicating from a
+cluster (A, B, C) that is primarily used for backups but in case of a total
+cluster failure is also used as a read-only standbyu server. To configure this
+in MaxScale using `rank` the following could be used.
+
+```
+[A]
+type=server
+address=192.168.0.11
+protocol=MariaDBBackend
+rank=1
+
+[B]
+type=server
+address=192.168.0.22
+protocol=MariaDBBackend
+rank=1
+
+[C]
+type=server
+address=192.168.0.33
+protocol=MariaDBBackend
+rank=1
+
+[D]
+type=server
+address=192.168.0.44
+protocol=MariaDBBackend
+rank=2
+```
+
+With this configuration the three servers in the primary cluster (A, B, C) would
+be used. Only when the whole primary cluster is down would server D be used and
+as soon as any of the primary servers became available, D would stop receiving
+traffic.
+
 ### Listener
 
 The listener defines a port and protocol pair that is used to listen for