docs: build de df6c90d216
This commit is contained in:
forgejo-actions
commit
4419d6ef68
193 changed files with 33340 additions and 0 deletions
210
_sources/exploitation/configuration.rst
Normal file
210
_sources/exploitation/configuration.rst
Normal file
|
|
@ -0,0 +1,210 @@
|
|||
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
|
||||
Loading…
Add table
Add a link
Reference in a new issue