329 lines
12 KiB
ReStructuredText
329 lines
12 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
|
||
|
||
times:
|
||
timeout_vms_stop: 300
|
||
next_vms_shutdown: 30
|
||
timeout_subnet_stop: 360
|
||
timeout_vpc_stop: 420
|
||
timeout_subnet_start: 300
|
||
timeout_vms_start: 300
|
||
poll_interval: 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.
|
||
|
||
La section ``times`` règle, en secondes, les attentes des commandes asynchrones :
|
||
|
||
``timeout_vms_stop``
|
||
arrêt propre d'une VM : au-delà, QEMU reçoit un ``quit`` QMP.
|
||
``next_vms_shutdown``
|
||
intervalle entre deux ``system_powerdown`` pendant cet arrêt. Un invité qui n'écoutait pas
|
||
encore l'ACPI au premier appui (firmware, chargeur de démarrage) s'éteint au suivant.
|
||
``timeout_subnet_stop``
|
||
suppression d'un subnet : attente de ses VM encore en ``deleting``.
|
||
``timeout_vpc_stop``
|
||
suppression d'un VPC : attente de ses subnets encore en ``deleting``.
|
||
``timeout_subnet_start``
|
||
création d'un subnet : attente de son VPC ``running``.
|
||
``timeout_vms_start``
|
||
création d'une VM : attente des subnets de ses interfaces ``running``.
|
||
``poll_interval``
|
||
pas de toutes ces attentes.
|
||
|
||
Chaque valeur doit être strictement positive, et ``next_vms_shutdown`` inférieur à
|
||
``timeout_vms_stop`` ; sinon l'agent refuse de démarrer. Les attentes s'enchaînent — une VM,
|
||
puis son subnet, puis le VPC : garder ``timeout_vms_stop`` < ``timeout_subnet_stop`` <
|
||
``timeout_vpc_stop`` pour qu'une suppression en cascade envoyée d'un coup aboutisse.
|
||
|
||
L'ancienne section ``dispatcher`` (``timeout_seconds``, ``poll_seconds``) n'est plus lue : restée
|
||
dans un fichier, elle est ignorée.
|
||
|
||
.. warning::
|
||
|
||
À l'expiration de ``timeout_vms_stop``, 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-public
|
||
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.
|
||
|
||
``internet`` désigne aussi le **bridge public**, celui qui porte ``vxlan-public`` et où chaque
|
||
VPC raccorde son veth ``vp-<id>-e`` (:doc:`/concepts/vpc-subnet-vm`). Pour lui, une clé absente
|
||
ou vide vaut ``br-public``, **jamais** ``default_interface`` : le segment public ne doit pas
|
||
tomber sur l'underlay. À garder égal au ``-P`` de ``deploy.sh``.
|
||
|
||
MTU
|
||
---
|
||
|
||
.. code-block:: yaml
|
||
|
||
network:
|
||
mtu_vm: 1500
|
||
allow_mtu_vm_below_1500: false
|
||
allow_mtu_underlay_below_9000: false
|
||
|
||
* ``mtu_vm`` — le MTU de toutes les VM, et de tous les bridges, veth, taps et interfaces VXLAN
|
||
que l'agent crée. Il est annoncé aux VM par l'option DHCP 26 et par ``host_mtu``. **Il doit
|
||
être identique sur tous les hyperviseurs.** 1500 au plus ; en dessous, seulement avec
|
||
``allow_mtu_vm_below_1500``, et jamais sous 1280. Une valeur hors de ces bornes fait échouer
|
||
le démarrage de l'agent.
|
||
* ``allow_mtu_underlay_below_9000`` — l'underlay est attendu à exactement 9000. Sans cette
|
||
option, un subnet ``vxlan`` dont l'interface (celle de ``iface_type``, ou
|
||
``default_interface``) n'est pas à 9000 est refusé (422), comme un VPC avec ``l3vni`` si
|
||
``default_interface`` ne l'est pas (409). Dans tous les cas, l'underlay doit faire au moins
|
||
``mtu_vm`` + 50 (en-tête VXLAN).
|
||
|
||
Un subnet ``bridge`` est refusé (422) si son bridge est sous ``mtu_vm`` ; il n'y a pas
|
||
d'encapsulation, donc pas de marge à prévoir. Les interfaces sont créées au MTU en vigueur à la
|
||
création du subnet : changer ``mtu_vm`` ne modifie pas les subnets existants, il faut les
|
||
recréer.
|
||
|
||
Plan de contrôle BGP
|
||
--------------------
|
||
|
||
.. code-block:: yaml
|
||
|
||
bgp:
|
||
asn: 64600
|
||
route_reflectors: [10.255.255.1, 10.255.255.2]
|
||
|
||
Section **facultative**. Absente, l'agent ne touche pas à FRR : sa configuration reste à poser
|
||
à la main, comme avant. Présente, l'agent **pilote la configuration BGP de l'hyperviseur** :
|
||
à chaque démarrage, avant d'ouvrir son API, il applique par ``vtysh`` la base décrite dans
|
||
:doc:`/deploiement/premier-hyperviseur`, puis l'enregistre par ``write memory``.
|
||
|
||
* ``asn`` — l'AS de l'hyperviseur, commun à tous les hyperviseurs du cluster (iBGP vers le
|
||
route reflector). Obligatoire dès que la section existe.
|
||
* ``route_reflectors`` — au moins une adresse IPv4, sans doublon. Un route reflector retiré de
|
||
la liste est retiré de FRR au démarrage suivant.
|
||
|
||
Le ``router-id`` n'est pas configurable : c'est l'adresse IPv4 primaire de
|
||
``default_interface``, celle qui sert de VTEP.
|
||
|
||
Le démarrage **échoue** si la section est incomplète, si ``default_interface`` n'a pas
|
||
d'adresse IPv4 primaire, si ``vtysh`` refuse une commande, ou si FRR tourne déjà sous un autre
|
||
AS : changer d'``asn`` suppose de retirer l'ancienne instance à la main.
|
||
|
||
.. warning::
|
||
|
||
``/etc/frr/frr.conf`` devient un fichier **généré** : ``write memory`` le réécrit à partir de
|
||
la configuration en mémoire de FRR. Une modification faite dans le fichier sans être
|
||
rechargée est perdue au prochain démarrage de l'agent.
|
||
|
||
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/uefi"
|
||
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: two # ou dnsmasq
|
||
|
||
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 ``two``. Un hyperviseur mis à jour depuis la 0.1.0 avec des subnets existants doit
|
||
déclarer ``backend: dnsmasq`` avant la mise à jour, ou être vidé puis basculé (voir plus bas) : ses
|
||
subnets restent servis par dnsmasq. 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.
|
||
|
||
Relais DNS et NTP
|
||
-----------------
|
||
|
||
.. code-block:: yaml
|
||
|
||
hostsvc:
|
||
dns_upstream: []
|
||
ntp_upstream: []
|
||
rate_limit_per_vpc: 100
|
||
|
||
Lue par ``two-hostsvc`` (voir :doc:`../concepts/dns-ntp`), au démarrage du service.
|
||
|
||
``dns_upstream``
|
||
résolveurs interrogés en premier, sous la forme ``ip`` ou ``ip:port`` (port 53 par défaut).
|
||
Ceux de ``/etc/resolv.conf`` de l'hôte viennent ensuite ; liste vide : l'hôte seul.
|
||
``ntp_upstream``
|
||
serveurs NTP relayés en premier, ``ip`` ou ``ip:port`` (port 123 par défaut). Sans serveur ou
|
||
sans réponse, l'horloge de l'hôte répond.
|
||
``rate_limit_per_vpc``
|
||
requêtes par seconde, DNS et NTP confondus, pour chaque VPC.
|
||
|
||
Un nom d'hôte, un port hors de 1–65535 ou une limite nulle ou négative font échouer le
|
||
démarrage de l'agent comme de ``two-hostsvc``, qui lisent le même fichier. Une modification prend
|
||
effet au redémarrage de ``two-hostsvc``.
|
||
|
||
Watchdog
|
||
--------
|
||
|
||
.. code-block:: yaml
|
||
|
||
watchdog:
|
||
enabled: true
|
||
interval_seconds: 60
|
||
|
||
Vérification périodique **en lecture seule** — voir :doc:`/exploitation/observabilite`.
|
||
**Désactivée par défaut** (``enabled: false``) : sans cette section, aucun contrôle ne tourne.
|
||
|
||
Journalisation
|
||
--------------
|
||
|
||
.. code-block:: yaml
|
||
|
||
logger:
|
||
level: info # debug, info, warn, error
|
||
debug: false # force le niveau debug quel que soit level
|