GnomeZworc
eee15eb68e
Note de version 0.2.0 (Bael), et reprise des huit pages de docs/ qui parlaient de dnsmasq ou du DHCP. Ajouts de fond : la section Backend DHCP de la page de configuration, avec la procédure de bascule manuelle et l'avertissement qu'elle ne migre rien ; la section du serveur intégré dans les services ; et dans la page de diagnostic comment interroger la socket de contrôle, probe étant le point de départ le plus rapide quand une VM n'obtient pas d'adresse. Le nom de version se déduit du rang, pas du numéro : deuxième release, deuxième nom de codenames.md. Construit avec sphinx-build -W --keep-going, sans avertissement. Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
210 lines
6.7 KiB
ReStructuredText
210 lines
6.7 KiB
ReStructuredText
Configuration
|
|
=============
|
|
|
|
Un seul fichier, ``/etc/two/agent.yml``, partagé par les quatre binaires : ``agent -config``,
|
|
``metadata -conf``, ``db -conf`` et ``dhcp -conf``. Le fichier de référence commenté est
|
|
``conf/agent/config.exemple.yml`` dans le dépôt.
|
|
|
|
Le chargement se fait par **viper** : les clés sont celles ci-dessous, en YAML.
|
|
|
|
.. warning::
|
|
|
|
Un fichier **absent** est toléré : toutes les valeurs par défaut s'appliquent. Un fichier
|
|
**présent mais invalide** fait en revanche échouer le démarrage, volontairement — jusqu'à
|
|
la version 0.1.0 il était ignoré en silence, et l'agent tournait alors entièrement sur les
|
|
défauts sans le dire. Une tabulation d'indentation ou un ``--`` égaré suffisent.
|
|
|
|
.. danger::
|
|
|
|
**L'API de l'agent n'a aucune authentification.** L'exemple livré écoute sur
|
|
``0.0.0.0:8080`` : quiconque atteint ce port peut créer et détruire des VM et des réseaux sur
|
|
l'host KVM, c'est-à-dire en prendre le contrôle.
|
|
|
|
Sur tout déploiement réel : restreindre ``api.address`` à une adresse d'administration, ou
|
|
filtrer le port en amont (pare-feu, réseau dédié). Traiter l'ouverture de ce port comme une
|
|
décision d'architecture, pas comme un réglage.
|
|
|
|
Base de données
|
|
---------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
database:
|
|
path: "/var/lib/two/data/"
|
|
|
|
Répertoire de la base clé-valeur Badger. **Un seul processus l'ouvre** : l'agent. Ni le serveur
|
|
de metadata ni aucun autre outil ne doit être configuré pour ouvrir le même répertoire pendant
|
|
que l'agent tourne.
|
|
|
|
Serveurs
|
|
--------
|
|
|
|
.. code-block:: yaml
|
|
|
|
api:
|
|
address: "0.0.0.0"
|
|
port: 8080
|
|
|
|
prometheus:
|
|
address: "0.0.0.0"
|
|
port: 9090
|
|
|
|
admin:
|
|
enabled: false
|
|
address: "127.0.0.1"
|
|
port: 9091
|
|
|
|
``admin`` expose une inspection en lecture seule de la base (``/db?prefix=…``). Elle est
|
|
désactivée par défaut et prévue pour la boucle locale uniquement.
|
|
|
|
.. warning::
|
|
|
|
Le contenu de la base inclut ``vm/<name>/password``, qui est un hash de mot de passe.
|
|
L'activation de l'API d'administration rend ces valeurs lisibles par tout ce qui atteint le
|
|
port. Ne pas l'exposer hors de la boucle locale.
|
|
|
|
Exécution des commandes
|
|
-----------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
worker:
|
|
count: 4
|
|
buffer_size: 100
|
|
|
|
dispatcher:
|
|
timeout_seconds: 300
|
|
poll_seconds: 2
|
|
|
|
``worker.count`` est le nombre de goroutines qui exécutent les commandes ; ``buffer_size`` le
|
|
nombre de commandes en attente au-delà duquel ``Dispatch`` bloque.
|
|
|
|
``dispatcher.timeout_seconds`` borne les opérations qui attendent une transition d'état, dont
|
|
l'extinction d'une VM.
|
|
|
|
.. warning::
|
|
|
|
À l'expiration de ce délai, une VM qui ne s'est pas éteinte reçoit un ``quit`` QMP — un arrêt
|
|
**brutal**. Pour des charges dont l'extinction est lente (bases de données, construction
|
|
d'images), une valeur confortable évite un système de fichiers invité incohérent.
|
|
|
|
Correspondance des interfaces
|
|
-----------------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
default_interface: br-000000
|
|
|
|
interfaces:
|
|
vms: br-000000
|
|
internet: br-000000
|
|
admin: br-000000
|
|
|
|
Traduit les clés logiques ``iface_type`` de l'API vers les bridges physiques de l'host. Une clé
|
|
inconnue ou omise retombe silencieusement sur ``default_interface`` — ce n'est pas une erreur,
|
|
mais c'est une source de subnets branchés au mauvais endroit sans le dire.
|
|
|
|
Metadata et QEMU
|
|
----------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
metadata:
|
|
run_dir: "/run/two/metadata"
|
|
|
|
qemu:
|
|
ovmf_code_path: "/usr/share/OVMF/OVMF_CODE.fd"
|
|
ovmf_vars_template: "/usr/share/OVMF/OVMF_VARS.fd"
|
|
uefi_vars_dir: "/run/two/vms/efi"
|
|
serial_dir: "/run/two/vms/serial"
|
|
monitor_dir: "/run/two/vms/monitor"
|
|
qmp_dir: "/run/two/vms/qmp"
|
|
|
|
Les chemins OVMF sont nécessaires aux VM démarrées avec ``uefi: true`` (paquet ``ovmf`` sur
|
|
Debian et Ubuntu). ``uefi_vars_dir`` reçoit une copie inscriptible des variables UEFI par VM,
|
|
créée au démarrage et supprimée à l'arrêt.
|
|
|
|
Backend DHCP
|
|
------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
dhcp:
|
|
backend: dnsmasq # ou two
|
|
|
|
Choisit qui sert le DHCP des subnets **créés par cet agent** :
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
:widths: 14 44 42
|
|
|
|
* - Valeur
|
|
- Serveur
|
|
- Unit
|
|
* - ``dnsmasq``
|
|
- dnsmasq, configuré par fichiers dans ``/etc/dnsmasq.d``
|
|
- ``dnsmasq@<netns>_<bridge>``
|
|
* - ``two``
|
|
- le binaire ``dhcp``, piloté par socket Unix
|
|
- ``dhcp@<netns>_<bridge>``
|
|
|
|
Le défaut est ``dnsmasq`` : un fichier de configuration de la 0.1.0, non modifié, se comporte
|
|
exactement comme avant. Toute autre valeur que ``dnsmasq`` ou ``two`` fait échouer le démarrage.
|
|
|
|
Le répertoire d'exécution du backend ``two`` — ``/run/two/dhcp`` — **n'est pas configurable** :
|
|
le script d'enrobage le code en dur, une clé que lui ignorerait serait un mensonge.
|
|
|
|
Ce que le backend ``two`` apporte : la configuration DHCP devient modifiable par VM et non plus
|
|
seulement par subnet, ce qui permet de n'annoncer la route par défaut que sur **une** interface
|
|
d'une VM multi-réseaux. Le watchdog peut en outre interroger le serveur et comparer ce qu'il sert
|
|
à ce que la base dit — voir :doc:`diagnostic`.
|
|
|
|
Bascule d'un backend à l'autre
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. warning::
|
|
|
|
L'option ne décide que du backend des **nouveaux** subnets. Elle ne migre rien : un subnet
|
|
déjà créé continue d'être servi par le serveur qui l'a été. Changer la valeur sans vider
|
|
l'hyperviseur laisse l'agent parler à un serveur qui ne tourne pas — les VM existantes
|
|
continuent, les nouvelles n'obtiennent pas d'adresse.
|
|
|
|
La bascule est **manuelle** et suppose un hyperviseur vide :
|
|
|
|
1. Supprimer toutes les VM, puis tous les subnets, puis les VPC.
|
|
2. Vérifier qu'il ne reste aucune unit DHCP active et aucun résidu :
|
|
|
|
.. code-block:: bash
|
|
|
|
systemctl list-units 'dnsmasq@*' 'dhcp@*'
|
|
ls /etc/dnsmasq.d/ /run/two/dhcp/
|
|
|
|
3. Modifier ``dhcp.backend`` dans ``/etc/two/agent.yml``.
|
|
4. ``systemctl restart agent`` — la valeur est lue au démarrage, pas à chaque commande.
|
|
5. Recréer VPC, subnets et VM.
|
|
6. Sur la première VM, vérifier l'adresse **et les trois routes** : la route par défaut, la
|
|
route vers le CIDR du VPC, et la route ``/32`` vers ``169.254.169.254``. C'est cette
|
|
dernière qui conditionne le provisionnement cloud-init.
|
|
|
|
Le retour arrière suit la même procédure. Il n'y a pas de bascule à chaud, dans un sens ni dans
|
|
l'autre.
|
|
|
|
Watchdog
|
|
--------
|
|
|
|
.. code-block:: yaml
|
|
|
|
watchdog:
|
|
enabled: true
|
|
interval_seconds: 60
|
|
|
|
Vérification périodique **en lecture seule** — voir :doc:`/exploitation/observabilite`.
|
|
|
|
Journalisation
|
|
--------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
logger:
|
|
level: info # debug, info, warn, error
|
|
debug: false # force le niveau debug quel que soit level
|