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
|