docs: premiere creation de documentation

Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>

docs/deploiement/architecture-cluster.rst

@@ -0,0 +1,98 @@
+Architecture du cluster
+=======================
+
+Topologie
+---------
+
+.. figure:: /schemas/topologie-cluster.svg
+   :alt: Topologie du cluster : routeurs, route reflector et hyperviseurs
+   :align: center
+   :width: 100%
+   :class: only-light
+
+   Topologie cible. Trait plein : plan de données. Trait pointillé : plan de contrôle.
+
+.. figure:: /schemas/topologie-cluster-dark.svg
+   :alt: Topologie du cluster : routeurs, route reflector et hyperviseurs
+   :align: center
+   :width: 100%
+   :class: only-dark
+
+   Topologie cible. Trait plein : plan de données. Trait pointillé : plan de contrôle.
+
+Deux plans distincts, à ne pas confondre au moment du diagnostic :
+
+Plan de données
+   les tunnels VXLAN entre hyperviseurs, encapsulés sur le réseau qui les relie.
+
+Plan de contrôle
+   ce qui dit à chaque hyperviseur où se trouvent les adresses MAC des autres. C'est le rôle de
+   FRR et du route reflector.
+
+Ce que l'agent suppose déjà en place
+------------------------------------
+
+L'agent ne configure **que** son propre hyperviseur, et seulement à partir du bridge d'uplink.
+Tout ce qui est en amont — adressage des hyperviseurs, routage entre eux, plan de contrôle — lui
+préexiste et n'est jamais créé ni vérifié par lui.
+
+Concrètement, il attend :
+
+* le bridge d'uplink de la configuration (``br-000000`` par défaut), avec l'interface physique
+  esclave et l'adresse de l'hyperviseur portée par le bridge — c'est ce que fait
+  ``deploy.sh --bootstrap``, voir :doc:`/demarrage/installation` ;
+* une connectivité IP entre hyperviseurs sur cette adresse, port UDP **4789** ouvert dans les
+  deux sens ;
+* un plan de contrôle qui peuple la table de transfert VXLAN — voir ci-dessous.
+
+Pourquoi un plan de contrôle est nécessaire
+-------------------------------------------
+
+L'agent crée les interfaces VXLAN sur le port 4789 **sans groupe multicast et avec
+l'apprentissage désactivé** (``Learning: false``). Il n'y a donc ni inondation multicast, ni
+apprentissage des adresses MAC depuis le trafic, ni voisin statique configuré.
+
+.. important::
+
+   Conséquence directe : sur un même VNI, **rien ne traverse d'un hyperviseur à l'autre** tant
+   qu'un composant externe n'a pas peuplé la table de transfert (FDB) du VXLAN. Sur un nœud
+   isolé le trafic reste sur le bridge local et cette absence ne se voit pas ; elle apparaît dès
+   le deuxième nœud.
+
+C'est exactement le rôle que remplissent FRR sur chaque hyperviseur et le route reflector qui
+les fait converger.
+
+MTU
+---
+
+.. warning::
+
+   L'agent crée bridges, veth et interfaces VXLAN avec un **MTU figé à 1500**. VXLAN ajoute 50
+   octets d'encapsulation : le réseau qui relie les hyperviseurs doit donc accepter au moins
+   **1550 octets** de MTU, sinon les paquets pleine taille des VM sont perdus.
+
+   Le symptôme est trompeur : le ping passe, les petites requêtes passent, les transferts
+   volumineux et les poignées de main TLS échouent.
+
+Hyperviseurs sans état
+----------------------
+
+L'hyperviseur est **stateless** — sa racine est en tmpfs, rien de ce que pose
+``deploy.sh --bootstrap`` ne survit à un redémarrage, et le script est rejoué à chaque démarrage.
+
+Toute configuration ajoutée à un hyperviseur — FRR compris — doit donc être posée par un
+mécanisme rejouable au démarrage, jamais par une modification manuelle d'un fichier sous
+``/etc``.
+
+Adressage
+---------
+
+.. note::
+
+   **À rédiger** — cette page ne décrit pas encore le plan d'adressage du cluster. À documenter :
+
+   * la plage utilisée pour les adresses d'hyperviseurs, et son rapport avec ``br-000000`` ;
+   * l'allocation des VNI VXLAN : qui la tient, et comment on évite les collisions, puisque
+     l'agent ne valide pas ``vxlan_id`` ;
+   * l'usage prévu de ``br-public``, créé vide et réservé par le bootstrap ;
+   * le plan d'adressage des VPC, et ce qui garantit qu'ils ne se recouvrent pas entre clients.

docs/deploiement/frr-hyperviseur.rst

@@ -0,0 +1,43 @@
+FRR sur les hyperviseurs
+========================
+
+FRR tourne sur chaque hyperviseur et peuple la table de transfert (FDB) des interfaces VXLAN
+créées par l'agent — c'est ce qui rend un subnet utilisable au-delà d'un seul nœud, puisque
+l'agent désactive l'apprentissage et ne configure aucun voisin.
+
+.. note::
+
+   **À rédiger.** À documenter :
+
+   * la version de FRR de référence et son mode d'installation, sachant que l'hyperviseur est
+     sans état : le paquet et la configuration doivent être posés à chaque démarrage, par le
+     bootstrap ou par un mécanisme équivalent ;
+   * les démons activés dans ``/etc/frr/daemons`` ;
+   * la configuration de référence : numéro d'AS, session vers le route reflector, famille
+     d'adresses utilisée pour annoncer les MAC et les VNI ;
+   * l'articulation avec les interfaces créées par l'agent : comment FRR découvre une interface
+     VXLAN qui apparaît à la création d'un subnet, et si une action est nécessaire ensuite ;
+   * ce qui se passe au démarrage à froid, quand FRR démarre avant ou après l'agent ;
+   * les commandes de vérification à utiliser en exploitation.
+
+Vérifier le plan de données
+---------------------------
+
+Indépendamment de la configuration retenue, deux vérifications restent valables et méritent
+d'être dans toute procédure de diagnostic :
+
+.. code-block:: bash
+
+   # La FDB du VXLAN doit contenir des entrées vers les autres hyperviseurs.
+   # Vide, c'est le plan de contrôle qui ne fonctionne pas, pas l'agent.
+   ip netns exec <vpc> bridge fdb show dev <interface-vxlan>
+
+   # L'interface VXLAN telle que l'agent l'a créée : port 4789, learning off,
+   # aucun groupe multicast, aucun remote.
+   ip netns exec <vpc> ip -d link show <interface-vxlan>
+
+.. important::
+
+   Une FDB vide alors que le subnet est en ``running`` n'est **pas** un défaut de l'agent : il
+   crée délibérément l'interface sans apprentissage ni voisin, et laisse le peuplement au plan
+   de contrôle. Cf. :doc:`architecture-cluster`.

docs/deploiement/index.rst

@@ -0,0 +1,26 @@
+Déploiement d'un cluster
+========================
+
+Le :doc:`/demarrage/index` couvre un hyperviseur isolé : un VPC, un subnet, une VM, tout sur le
+même nœud. Cette section couvre ce qu'il faut mettre en place pour qu'un **parc** d'hyperviseurs
+fonctionne ensemble — c'est-à-dire pour qu'un subnet s'étende à plusieurs nœuds.
+
+Ce n'est pas une extension du quickstart : le réseau du cluster doit exister **avant** que
+l'agent serve à quelque chose au-delà d'un nœud.
+
+Ordre de mise en place
+----------------------
+
+#. :doc:`architecture-cluster` — la topologie cible et ce que l'agent suppose déjà en place
+#. :doc:`routeurs-cluster` — le routage entre hyperviseurs et vers l'extérieur
+#. :doc:`route-reflector` — la VM route reflector, point de rendez-vous du plan de contrôle
+#. :doc:`frr-hyperviseur` — FRR sur chaque hyperviseur, qui peuple le plan de données
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   architecture-cluster
+   routeurs-cluster
+   route-reflector
+   frr-hyperviseur

docs/deploiement/route-reflector.rst

@@ -0,0 +1,40 @@
+VM route reflector
+==================
+
+Le route reflector est le point de rendez-vous du plan de contrôle : plutôt que de maintenir une
+session entre chaque paire d'hyperviseurs, chaque hyperviseur ouvre une session vers le route
+reflector, qui redistribue.
+
+Il tourne lui-même en machine virtuelle, ce qui crée une dépendance circulaire à traiter
+explicitement : la VM qui porte le plan de contrôle du cluster est hébergée par le cluster.
+
+.. note::
+
+   **À rédiger.** À documenter :
+
+   * la création de la VM : image de base, ressources, subnet et mode utilisés, s'il s'agit d'une
+     VM créée par l'agent comme les autres ou d'un cas particulier ;
+   * son adressage, et comment les hyperviseurs le connaissent ;
+   * la configuration du démon de routage qu'elle héberge ;
+   * la redondance : une seule VM route reflector, ou deux, et sur quels hyperviseurs ;
+   * la procédure de reconstruction, et l'état du cluster pendant que le route reflector est
+     absent — les tunnels déjà établis continuent-ils de fonctionner, et pendant combien de
+     temps ;
+   * la procédure d'amorçage : ce qui fonctionne, et dans quel ordre, quand on démarre un cluster
+     entier depuis zéro.
+
+Points de vigilance
+-------------------
+
+.. warning::
+
+   L'agent **ne réattache pas** les VM existantes à son démarrage, et les processus QEMU ne
+   survivent pas à un redémarrage de l'hyperviseur. Le redémarrage de l'hyperviseur qui héberge
+   le route reflector est donc un événement à part entière : la procédure de remise en service
+   doit être écrite, et testée.
+
+.. warning::
+
+   ``instance-id`` valant le nom de la VM, recréer la VM route reflector sous le même nom sur le
+   même disque fait que cloud-init **ne rejoue pas** le user-data. Cf.
+   :doc:`/concepts/metadata-cloud-init`.

docs/deploiement/routeurs-cluster.rst

@@ -0,0 +1,31 @@
+Routeurs de cluster
+===================
+
+Les routeurs de cluster raccordent les hyperviseurs entre eux et au monde extérieur. Ils
+préexistent à l'agent : celui-ci ne les configure pas et n'en a aucune connaissance.
+
+.. note::
+
+   **À rédiger.** Cette page attend les éléments de terrain. À documenter :
+
+   * le rôle exact des routeurs dans la topologie : passerelle du réseau d'hyperviseurs,
+     terminaison du routage externe, ou les deux ;
+   * le matériel ou le logiciel employé, et la version de référence ;
+   * la configuration de référence : interfaces, adressage, protocole de routage employé avec
+     les hyperviseurs, numéros d'AS si BGP ;
+   * la redondance : combien de routeurs, quel mécanisme de bascule, quel comportement attendu
+     pendant une bascule ;
+   * le MTU configuré sur les liens vers les hyperviseurs — il doit tenir compte des 50 octets
+     d'encapsulation VXLAN, cf. :doc:`architecture-cluster` ;
+   * le filtrage : ce qui est autorisé entre hyperviseurs (au minimum UDP 4789), et ce qui est
+     autorisé depuis l'extérieur.
+
+Points de vigilance
+-------------------
+
+.. warning::
+
+   L'API de l'agent n'a **aucune authentification**. Le filtrage réalisé par les routeurs de
+   cluster est aujourd'hui l'une des rares barrières entre cette API et le reste du réseau : le
+   port de l'API ne doit être joignable que depuis le réseau d'administration.
+   Cf. :doc:`/exploitation/configuration`.