two/docs/demarrage/installation.rst
GnomeZworc d43067c013
All checks were successful
Documentation / publish (push) Successful in 1m42s
Release Pipeline / set-release-target (push) Successful in 3s
Release Pipeline / upload-assets (agent.service, systemd/agent.service) (push) Successful in 8s
Release Pipeline / upload-assets (run-dnsmasq-in-netns.sh, scripts/run-dnsmasq-in-netns.sh) (push) Successful in 8s
Release Pipeline / upload-assets (dhcp@.service, systemd/dhcp@.service) (push) Successful in 8s
Release Pipeline / upload-assets (dnsmasq@.service, systemd/dnsmasq@.service) (push) Successful in 8s
Release Pipeline / upload-assets (metadata@.service, systemd/metadata@.service) (push) Successful in 8s
Release Pipeline / upload-assets (run-dhcp-in-netns.sh, scripts/run-dhcp-in-netns.sh) (push) Successful in 8s
Release Pipeline / build (agent, amd64, linux) (push) Successful in 0s
Release Pipeline / build (dhcp, amd64, linux) (push) Successful in 0s
Release Pipeline / build (metadata, amd64, linux) (push) Successful in 0s
Release Pipeline / checksums (push) Successful in 8s
Release Pipeline / release (push) Successful in 30s
Release Pipeline / publish (push) Successful in 0s
Release Pipeline / build (push) Successful in 2m17s
0.2.0: release
Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
2026-10-24 20:38:41 +02:00

168 lines
6.9 KiB
ReStructuredText

Installation d'un hyperviseur
=============================
Cette page installe l'agent sur **un** hyperviseur. Le réseau du cluster — routage entre nœuds,
plan de contrôle — est traité à part : voir :doc:`/deploiement/index`.
Prérequis
---------
Un host Linux avec KVM, sur lequel vous avez ``root``. Les opérations réseau (network
namespaces, netlink, VXLAN, ebtables, iptables) et QEMU ne fonctionnent que sous Linux.
Déploiement
-----------
.. code-block:: bash
curl -O https://git.g3e.fr/syonad/two/raw/branch/main/scripts/deploy.sh
bash ./deploy.sh -t 0.2.0 -i
``deploy.sh`` se met à jour lui-même depuis la branche avant toute action — s'il diffère, il se
réécrit et demande d'être relancé. Il télécharge ensuite binaires, units systemd et scripts
depuis la release, et les vérifie contre le manifeste ``SHA256SUMS``.
.. list-table::
:header-rows: 1
:widths: 26 54 20
* - Option
- Effet
- Défaut
* - ``-t <tag>``
- déployer une release donnée
- dernière publiée, **préversions comprises**
* - ``-b <branche>/``
- branche d'où viennent l'auto-mise à jour du script et les scripts de ``-i`` ; les
binaires viennent toujours d'une release. Le ``/`` final est **obligatoire** : l'URL est
concaténée sans séparateur (``-b dev`` donne ``…/branch/devscripts/…``)
- ``main/``
* - ``-p <profil>``
- profil d'host ; seul ``kvm`` installe les units de l'agent
- ``kvm``
* - ``-i``
- préparer l'host : paquets, noyau, réseau
- désactivé
* - ``-u <iface>``
- interface physique d'uplink
- ``eno1``
* - ``-B <bridge>``
- bridge principal, auquel l'uplink est rattaché
- ``br-000000``
* - ``-P <bridge>``
- bridge supplémentaire, créé vide et réservé ; garder ``br-public``, nom attendu par
l'agent (voir ci-dessous)
- ``br-public``
* - ``-R <secondes>``
- délai avant le redémarrage de secours pendant la migration réseau
- ``120``
* - ``-d``
- dry-run : affiche les commandes sans les exécuter
- désactivé
Les options booléennes actives par défaut se **désactivent** par leur forme longue négative :
``--nopackages``, ``--nonetwork``, ``--noverify``, ``--noup_script``.
.. warning::
``--noverify`` désactive la seule vérification d'intégrité des artefacts téléchargés. Ne
l'utiliser que pour diagnostiquer un manifeste cassé, jamais en déploiement courant.
Ce que fait ``-i``
------------------
**Paquets** — ``qemu-system-x86``, ``qemu-utils``, ``ovmf``, ``dnsmasq``, ``ebtables``,
``iptables``, ``nfs-common``, ``jq``, ``curl``, **sans les paquets recommandés** : ceux de
``qemu-system-x86`` (interface graphique, gtk, gstreamer, pilotes de stockage réseau) ne servent
pas à un hyperviseur sans écran, et l'installation passe d'environ 270 à 65 Mo — rejouée à chaque
démarrage, la racine étant en tmpfs. ``qemu-utils`` est demandé explicitement : ``qemu-img`` sert
à la construction de l'image (:doc:`/deploiement/image-qcow2`). Le service ``dnsmasq`` du système est ensuite désactivé et
**masqué** : il prendrait le port 53 en concurrence des instances ``dnsmasq@`` que l'agent lance
dans les netns.
``dnsmasq`` reste installé bien que ``dhcp.backend`` vaille ``two`` par défaut : le paquet sert
aux hyperviseurs qui déclarent ``dhcp.backend: dnsmasq``, et tant qu'un hyperviseur peut revenir
en arrière. Voir :doc:`/exploitation/configuration`.
**Noyau** — chargement de ``br_netfilter``, puis ``net.ipv4.ip_forward = 1`` et
``net.bridge.bridge-nf-call-iptables = 1``. Cette dernière clé est **requise** par la DNAT vers
le serveur de metadata : sans elle, iptables ne voit pas le trafic bridgé des VM et cloud-init
ne se provisionne pas. Contrepartie assumée : tout le trafic inter-VM traverse les tables NAT.
**Réseau** — création du bridge réservé, puis rattachement de l'uplink au bridge principal,
l'adresse et la route par défaut étant déplacées de l'interface physique vers le bridge.
Le nom ``br-public`` est **en dur dans l'agent** : chaque VPC ``vp-<id>`` y raccorde un veth
``vp-<id>-e`` côté host, dont l'autre extrémité ``vp-<id>-i`` rejoint un ``br-public`` créé dans
le netns du VPC. Avec un autre nom passé à ``-P``, toute création de VPC échoue.
.. danger::
La migration réseau **coupe le réseau de l'host si elle échoue à mi-parcours**, sans console
de secours. Deux garde-fous sont en place : un redémarrage de secours armé avant l'opération
(``-R``, 120 s par défaut) qui ramène la configuration d'origine puisque rien n'est écrit sur
disque, et l'exécution de la séquence sous systemd plutôt que dans la session SSH, pour
qu'une coupure de SSH ne l'interrompe pas.
Le désarmement n'a lieu **qu'après** un ping réussi vers la passerelle. Prévoir un accès
physique ou console avant de lancer un ``-i`` à distance sur un host de production.
Host sans état
--------------
L'hyperviseur est **stateless** : sa racine est en tmpfs, rien de ce que pose ``-i`` ne survit à
un redémarrage. ``deploy.sh --bootstrap`` est donc rejoué à chaque démarrage — c'est le
mécanisme normal, pas une réparation.
Binaires installés
------------------
.. list-table::
:header-rows: 1
:widths: 20 60 20
* - Binaire
- Rôle
- Drapeau de config
* - ``agent``
- processus principal : API, dispatcher, exécution, watchdog
- ``-config``
* - ``metadata``
- serveur de metadata cloud-init, une instance par VM dans le netns du VPC
- ``-conf``
* - ``db``
- inspection de la base clé-valeur en ligne de commande ; **ni publié ni déployé** par
``deploy.sh``, à compiler depuis les sources (:doc:`/exploitation/observabilite`)
- ``-conf``
* - ``dhcp``
- serveur DHCP intégré, une instance par subnet dans le netns du VPC ; démarré uniquement
avec ``dhcp.backend: two``
- ``-conf``
Les quatre lisent le même fichier, ``/etc/two/agent.yml`` — voir
:doc:`/exploitation/configuration`. ``dhcp`` reçoit en plus son bridge et ses deux chemins de
fichiers en paramètres, posés par son script d'enrobage.
Mise à jour
-----------
``deploy.sh`` relève les instances ``dnsmasq@``, ``dhcp@`` et ``metadata@`` actives **avant**
d'arrêter les services, et les redémarre ensuite : c'est la seule façon de savoir lesquelles
relancer. Arrêter les services à la main avant de lancer le script fait perdre cette liste.
Vérifier l'installation
-----------------------
.. code-block:: bash
systemctl status agent
curl -s http://127.0.0.1:8080/vpcs
Une liste JSON — vide au premier démarrage — signifie que l'API répond. Passez à
:doc:`/demarrage/premier-vpc`.
.. important::
L'API de l'agent **n'a aucune authentification**. Avant d'ouvrir le port au-delà de la boucle
locale, lisez l'avertissement de :doc:`/exploitation/configuration` : quiconque atteint ce
port pilote la totalité de l'hyperviseur.