Extension du cluster : ajouter un ou n ``Shards``
#################################################

Lorsque la volumétrie des données gérées par un seul ``Shard`` devient trop importante, il faut ajouter de nouveaux ``Shards`` dans le cluster. Des lors que les nouveaux ``Shards`` sont opérationnels, une opération de migration des données (voir ``balancing``) est réalisée en tâche de fond afin d'équilibrer l'ensemble des ``Shards``.

Les éléments déplacés entre ``Shard`` sont des regroupements de données par collection. Ce regroupement est nommé ``Chunk`` et le composant MongoDB qui réalise ce déplacement est nommé ``balancer``.

Le mécanisme interne du ``balancer`` n'est pas paramétrable. Une opération de transfert de ``Chunk`` est réalisée exclusivement entre un ``Shard`` et un autre ``Shard``. Si le cluster contient 4 ``Shards``, 2 opérations, au maximum, pourront être réalisées en parallèle à un instant donné.

.. note:: il est recommandé de favoriser un grand nombre de ``Shards`` (avec un nombre pair), déployés sur des 'petites' machines, afin de favoriser le re-équilibrages des ``Shards``.

.. note:: Dans Vitam, les clés de ``Sharding`` implémentées permettent une répartition uniforme des données. En régime de croisière, les ``Shards`` n'ont donc pas besoin d'être équilibrés et l'opération de ``balancing`` ne devrait pas logué une activité.

Pour ajouter un nouveau ``Shard`` au cluster, il faut exécuter les opérations suivantes :

* Créer les machines qui seront utilisées comme membre des nouveaux shards.
* Ajouter ces machines dans le fichier d'inventaire ansible.
* se connecter à un service ``vitam-mongos`` :

  Depuis une machine ou l’utilitaire mongo est installé et pour laquelle le flux réseau vers le service est ouvert. Le cas échéant, se connecter en ssh sur la machine pour utiliser l’utilitaire mongo en spécifiant le hostname de la machine (pas localhost) :

.. code-block:: bash

  mongo --host <hostname> --port 27017 --username vitamdb-admin --password <password> --authenticationDatabase admin

* Vérifier l'état du sharding dans le cluster en tappant la commande suivante :

.. code-block:: javascript

  sh.status()
..

  La commande retourne un ensemble d'informations dont 2 sont importantes pour cette opération d'exploitation. La première détaille la composition des shards opérationnels, dont voici un exemple :

.. code-block:: javascript

  shards:
      {  "_id" : "shard0",  "host" : "shard0/<ipMember1>:27019,<ipMember2>:27019,<ipMember3>:27019",  "state" : 1 }
      {  "_id" : "shard1",  "host" : "shard1/<ipMember1>:27019,<ipMember2>:27019,<ipMember3>:27019",  "state" : 1 }
..

  La seconde détaille les activités de balancing des ``Chunks``, dont voici un exemple :

.. code-block:: javascript

  balancer:
        Currently enabled:  yes
        Currently running:  no
        Failed balancer rounds in last 5 attempts:  0
        Last reported error: 
        Time of Reported error:  Tue Jul 30 2019 09:05:45 GMT+0000 (UTC)
        Migration Results for the last 24 hours: 
                No recent migrations
..

  Dans ces informations, on constate que le service de ``balancing`` est actif et qu'aucune migration n'est en cours. De plus, aucune migration n'a été réalisée au cours des dernières 24 heures.

* Ajouter les shards en récupérant les adresses Ip de chacun des membres, en conservant le regroupement qui a été configuré dans l'ansiblerie Vitam, et en executant la commande suivante pour chaque shard :

.. code-block:: javascript

  sh.addShard("shard2/<ipMember1>:27019,<ipMember2>:27019,<ipMember3>:27019")
..

* Vérifier que le balancing a démarré en récupérant l'état du sharding via la commande :

.. code-block:: javascript

  sh.status()
..

  Voici un exemple d'information que l'on peut récupérer :

.. code-block:: javascript

  balancer:
        Currently enabled:  yes
        Currently running:  yes
        Collections with active migrations: 
                logbook.LogbookLifeCycleObjectGroup started at Wed Jul 31 2019 12:43:19 GMT+0000 (UTC)
        Failed balancer rounds in last 5 attempts:  0
        Migration Results for the last 24 hours: 
                22 : Success
..

.. Note:: cette opération a été testée dans l'environnement de performance Vitam, qui contenait environ 200 millions d'AU. Le temps de migration des ``Chunks`` depuis les 2 ``Shards`` existants vers les 2 nouveaux ``Shards`` a été d'une trentaine de jours.