Service registry
################

Le *service registry* est le composant permettant à chaque service de localiser les services dont il dépend ; par conséquent, son bon fonctionnement est particulièrement critique pour le bon fonctionnement de la solution logicielle  :term:`VITAM`.
L'outil de *service registry* utilisé par :term:`VITAM` est `Consul <https://www.consul.io>`_.

Architecture
============

Un déploiement Consul est composé de 2 types de noeuds différents :

* Les noeuds serveurs : ils persistent l'état des données stockées dans Consul ; les données sont répliquées entre eux, et eux seuls participent à l'élection du maître (ils forment un cluster Raft). Un quorum de ces noeuds doit toujours être déclaré ; dans le cas contraire, on entre dans un cas de désastre de cluster (Cf. `la documentation sur l'"outage recovery" <https://www.consul.io/docs/guides/outage.html>`_ ) ; le nombre de serveurs doit être impair, avec un minimum conseillé de 3 noeuds (pour des problématiques de maintien de quorum).
* Les noeuds client : ils exposent les :term:`API` d'accès aux structures de données Consul, et réalisent les *healthchecks* des services dont ils ont la définition. Ils communiquent avec les serveurs.

Un noeud Consul est également appelé un agent.

.. note:: Les noeuds serveurs sont en fait des noeuds clients réifiés, i.e. ils ont également les capacités des clients.

Dans le cadre de  :term:`VITAM`, le déploiement des noeuds Consul doit correspondre aux principes suivants :

* Un cluster de serveurs Consul sur un nombre impair de noeuds dédiés, chacun d'entre eux étant configuré pour exposer l':term:`IHM` de suivi ;
* 1 client par serveur hébergeant un service :term:`VITAM`.

.. hint:: Préconisation : Le fonctionnement de Consul via trois noeuds *master* au minimum nous prémunit de la perte d'un de ces noeuds sans perturbation du service. Un seul noeud Consul est vivement déconseillé.


Résolution DNS
==============

Les résolutions de noms de service se font via l':term:`API` :term:`DNS` de Consul ; un *resolver* externe doit être configuré pour les requêtes externes.

Chaque client agit comme serveur :term:`DNS` local ; il écoute sur le port udp 53 (sur la boucle locale - ``127.0.0.1``), et est configuré comme serveur :term:`DNS` de l':term:`OS` (typiquement dans le fichier ``/etc/resolv.conf``).

.. caution:: Cela rend Consul incompatible avec d'autres implémentations de serveur :term:`DNS` qui seraient lancées sur l':term:`OS`, et en particulier les caches :term:`DNS` installés par défaut dans certaines distributions linux (ex: dnsmasq). En outre, il faut prendre garde à l'écrasement de la configuration du ``resolv.conf``, qui doit garder ``127.0.0.1`` comme premier serveur :term:`DNS`.

.. note:: Pour pouvoir écouter sur le port 53, Consul nécessite la capacité ``CAP_NET_BIND_SERVICE`` (Cf. la section suivante).

Lorsque le système fait une requête :term:`DNS`, cette dernière arrive à l'agent Consul local et la séquence suivante est exécutée :

* Si le nom à résoudre appartient au domaine réservé pour Consul (par défaut ``consul``), il est résolu en tant que nom de service ou de noeud (Cf. `la documentation officielle concernant l'interface DNS <https://www.consul.io/docs/agent/dns.html>`_) ;
* Dans le cas contraire, la requête est transmise aux serveurs :term:`DNS` configurés dans la liste des `recursors <https://www.consul.io/docs/agent/options.html#recursors>`_).

.. note:: Consul a pour l'instant été configuré en mode ``allow_stale = false`` (cf. `la directive de configuration <https://www.consul.io/docs/agent/options.html#allow_stale>`_), ce qui signifie que chaque requête DNS se traduit par un appel RPC au noeud *leader* des serveurs Consul. Cela permet d'assurer la consistance des réponses DNS, mais peut potentiellement poser des problèmes de performance sur des larges déploiements. Il est possible de changer ce comportement (clés de configuration ``allow_stale`` et ``max_stale`` - qui permettent de préciser la durée maximum pendant laquelle le noeud répond aux requêtes DNS sans interroger le *leader*), et également de changer le :term:`TTL` des réponses DNS (qui est par défaut gardé à 0).


Multi-site
==========

En multi-site, la solution logicielle :term:`VITAM` exploite les *datacenters* consul. Un *datacenter* consul est créé par site.

Chaque site doit posséder au moins 3 serveurs consul, qui ne supervisent que les services dans le datacenter auquel ils sont rattachés.


Packaging
=========

La solution logicielle :term:`VITAM` intègre des packages :term:`OS` (rpm & deb) dédiés pour Consul ; ces packages permettent essentiellement :

* De configurer Consul en tant que service systemd ;
* De permettre le lancement de Consul sous l'utilisateur ``vitam`` ;
* Enfin, ils intègrent une directive ``setcap`` de post-install pour attribuer la capacité ``CAP_NET_BIND_SERVICE`` au binaire ``/vitam/bin/consul/consul`` afin de permettre à ce dernier d'exposer une interface :term:`DNS` sur le port 53 sans pour autant nécessiter les droits *root*.


Monitoring
==========

Chaque instance de service doit être déclarée dans Consul ; cette déclaration se fait en déposant un fichier de configuration dans le répertoire de configuration de Consul. Ce fichier contient notamment l'identifiant du service ainsi que son port d'écoute, ainsi qu'une liste de *healthchecks* qui permettent à Consul de connaître l'état du service. Pour les services :term:`VITAM`, ces *healthchecks* s'appuient sur les :term:`API` de supervision qui ont été décrites dans :doc:`la section dédiée <principes/40-principles-monitoring>`.

Consul permet d'exposer une :term:`IHM` Web permettant d'accéder à la topologie des services déployés (i.e. quel service sur quel noeud) et à leur état instantané.
