From f184f94360e189a7cee4ddc52d90cc6e165d5197 Mon Sep 17 00:00:00 2001
From: Michal Arbet <michal.arbet@ultimum.io>
Date: Wed, 7 Apr 2021 15:03:52 +0200
Subject: [PATCH] Mariadb shards documentation
Change-Id: Id9a24c54db9a70c777e51ea10504159d5090f9a7
---
doc/source/reference/databases/index.rst | 1 +
.../reference/databases/mariadb-guide.rst | 70 +++++++++++++++++++
2 files changed, 71 insertions(+)
create mode 100644 doc/source/reference/databases/mariadb-guide.rst
diff --git a/doc/source/reference/databases/index.rst b/doc/source/reference/databases/index.rst
index d9c135f04a..613082ea6c 100644
--- a/doc/source/reference/databases/index.rst
+++ b/doc/source/reference/databases/index.rst
@@ -8,3 +8,4 @@ This section describes configuration of database services.
:maxdepth: 1
external-mariadb-guide
+ mariadb-guide
diff --git a/doc/source/reference/databases/mariadb-guide.rst b/doc/source/reference/databases/mariadb-guide.rst
new file mode 100644
index 0000000000..305bc67123
--- /dev/null
+++ b/doc/source/reference/databases/mariadb-guide.rst
@@ -0,0 +1,70 @@
+.. _mariadb-guide:
+
+=============
+MariaDB Guide
+=============
+
+Kolla Ansible supports deployment of a MariaDB/Galera cluster
+for use by OpenStack and other services.
+
+MariaDB Shards
+~~~~~~~~~~~~~~
+
+A database shard, or simply a shard, is a horizontal partition of data
+in a database or search engine. Each shard is held on a separate database
+server/cluster, to spread load. Some data within a database remains present
+in all shards, but some appears only in a single shard.
+Each shard acts as the single source for this subset of data.
+
+Kolla supports sharding on service's database level, so every database
+can be hosted on different shard. Each shard is implemented as
+an independent Galera cluster.
+
+This section explains how to configure multiple database shards. Currently,
+only one shard is accessible via the HAProxy load balancer and supported
+by the ``kolla-ansible mariadb_backup`` command. This will be improved
+in future by using ProxySQL, allowing load balanced access to all shards.
+
+Deployment
+----------
+
+Each shard is identified by an integer ID, defined by ``mariadb_shard_id``.
+The default shard, defined by ``mariadb_default_database_shard_id`` (default 0),
+identifies the shard that will be accessible via HAProxy and available for backing up.
+
+In order to deploy several MariaDB cluster, you will need to edit
+inventory file in the way described below:
+
+ .. code-block:: ini
+
+ [mariadb]
+ server1ofcluster0
+ server2ofcluster0
+ server3ofcluster0
+ server1ofcluster1 mariadb_shard_id=1
+ server2ofcluster1 mariadb_shard_id=1
+ server3ofcluster1 mariadb_shard_id=1
+ server1ofcluster2 mariadb_shard_id=2
+ server2ofcluster2 mariadb_shard_id=2
+ server3ofcluster2 mariadb_shard_id=2
+
+.. note::
+
+ If ``mariadb_shard_id`` is not defined for host in inventory file it will be set automatically
+ to ``mariadb_default_database_shard_id`` (default 0) from ``group_vars/all.yml`` and can be
+ overwritten in ``/etc/kolla/globals.yml``. Shard which is marked as default is special in case
+ of backup or loadbalance, as it is described below.
+
+Loadbalancer
+------------
+Kolla currently supports balancing only for default shard. This will be
+changed in future by replacement of HAProxy with ProxySQL. This results in
+certain limitations as described below.
+
+Backup and restore
+------------------
+
+Backup and restore is working only for default shard as kolla currently
+using HAProxy solution for MariaDB loadbalancer which is simple TCP and
+has configured only default shard hosts as backends, therefore backup
+script will reach only default shard on ``kolla_internal_vip_address``.
--
GitLab