Invariants et pièges ==================== Contraintes découvertes en production ou en corrigeant des bugs. Les enfreindre casse quelque chose qui fonctionne, souvent en silence. Réseau ------ * **Ne pas retirer la route ``/32`` vers ``169.254.169.254``** de l'option 121, même quand elle paraît redondante avec la route par défaut. La DNAT vers le serveur de metadata est posée dans le netns du VPC en ``PREROUTING`` : le paquet n'y est traité en L3 que si son next-hop est ``interface_ip``. Avec un autre next-hop, la trame est commutée en L2 sans traverser ``PREROUTING``, et le provisionnement cloud-init échoue. * **RFC 3442** : un client qui lit l'option 121 **ignore l'option 3**. Toute route par défaut doit donc figurer dans la 121 ; l'option 3 ne sert que les clients qui n'implémentent pas la 121. * **La route vers le CIDR du VPC garde ``interface_ip`` comme next-hop** dans tous les modes sauf ``bridge`` : sur un subnet à IP publique, le trafic interne ne doit pas sortir par la gateway publique. * **La MAC anycast d'une gateway ``vxlan`` ne sort jamais du netns** : règles nftables sur le veth du subnet (source anycast rejetée en entrée et en sortie) **et** entrée FDB locale dans le bridge du netns. Sans l'entrée FDB, que le macvlan ne crée pas, toute trame d'une VM vers sa gateway est inondée vers le fabric et traitée par la gateway de chaque hôte. * **La gateway ``vxlan`` n'est jamais sur le bridge** : ``arp_ignore=1`` sur ``br-``, la gateway en ``/32`` sur ``gw-``, l'adresse d'émission seule sur le bridge. Posée sur le bridge, la gateway répondrait aux VM avec la MAC de l'hôte et l'anycast serait contourné sans autre symptôme. * **La route du subnet garde la gateway pour source** (``src``) : le netns parle à ses VM depuis la gateway, leurs réponses reviennent à l'hôte local. Depuis l'adresse d'émission, partagée par tous les hôtes, une réponse peut partir vers un autre hôte. * **Chaque VRF de VPC porte une route ``unreachable default`` de métrique maximale.** Sans elle, une recherche manquée dans la VRF retombe dans la table ``main`` de l'hôte et le paquet du locataire sort par l'underlay. Elle survit à la suppression de la VRF (aucune interface) : la retirer explicitement au démontage. * **``default_route: true`` sans ``gateway`` est réservé au mode ``bridge``** : en ``vxlan``, la gateway de l'hôte n'est pas sur le subnet, la route par défaut serait inutilisable, et jointe elle contournerait le netns et la VRF. * ``169.254.169.254`` est centralisé dans ``metadata.ServiceIP`` — ne pas le réécrire en dur. * **Tout travail dans un netns passe par ``netns.Call``.** ``setns`` ne change que le thread courant : ``netns.Call`` verrouille la goroutine sur son thread, revient ensuite au netns de ce thread (``/proc/thread-self``, jamais ``/proc/self``, qui désigne le thread principal) et détruit un thread qui ne peut pas y revenir (#91). * **Une socket appartient au netns du thread qui la crée** : un listener destiné à un VPC est créé dans ``netns.Call``, puis servi hors du netns. Après un ``setns`` suivi d'un déverrouillage du thread, rien ne garantit que la socket soit créée sur le bon thread (#92). QEMU et VM ---------- * **Un seul disque virtio, ``vda``, le disque racine** ; les disques additionnels passent par le SCSI (``xvdX``, cible X). La carte PCI en dépend : NIC en ``0x03``, contrôleur SCSI en ``0x1e``, virtio-blk en ``0x1f``. * ``bus=pci.0`` est explicite sur les trois ``-device`` : un passage de la machine en **q35** casserait le démarrage (``Bus 'pci.0' not found``). * QEMU est lancé par ``systemd-run --scope``, **jamais** en unit transitoire : le scope est exécuté par le processus appelant et hérite du netns posé par ``netns.Call``. Une unit transitoire, forkée par PID 1, démarrerait dans le netns racine et ne verrait pas le tap. * **Un tap n'existe jamais sans ses règles** : la chaîne ``pre-tap`` est posée avant la création du tap et retirée après sa suppression. Dans l'autre ordre, une VM pourrait émettre sans filtre entre deux étapes. * L'arrêt d'une VM ne touche **jamais** aux fichiers disque. En revanche, un ``quit`` brutal est envoyé à l'expiration de ``times.timeout_vms_stop``. ``system_powerdown`` est renvoyé toutes les ``times.next_vms_shutdown`` : un appui ACPI arrivé avant que l'invité sache le traiter est perdu. Arrêt de l'agent ---------------- * Ordre imposé : serveurs HTTP → drainage des workers → fermeture de la base. L'inverser crée une course. * Budget d'arrêt dépassé ⇒ **la base n'est pas fermée** : fermer Badger sous un écrivain concurrent est pire qu'un rejeu du journal au démarrage suivant. * Jamais de ``log.Fatal`` dans une goroutine : ``os.Exit`` n'exécute aucun ``defer``. cloud-init ---------- * ``network-config.tmpl`` cible ``eth0`` alors que les guests sont en ``ens3`` : il ne s'applique donc à rien, et le réseau vient du DHCP. **Ne pas le « corriger » ni le supprimer** — le rendre opérant ferait remplacer par cloud-init la configuration réseau de l'image sur toutes les VM. * Un document fourni par l'appelant est servi **verbatim** ; un document absent retombe sur le template ; un document explicitement vide est servi vide. Les trois cas sont distincts. * ``metadata.password`` est un **hash**, pas un mot de passe en clair. * ``instance-id`` vaut le nom de la VM : recréer une VM du même nom sur le même disque fait que cloud-init la reconnaît et **n'applique pas** le user-data. Configuration ------------- * Le chargement se fait par **viper** : tags ``mapstructure``, jamais ``yaml``. * Un chemin configurable se propage par les signatures de fonction, jamais par une variable ou un setter de paquet. Sécurité connue et acceptée --------------------------- Ces points sont documentés parce qu'ils sont **assumés en l'état**, pas parce qu'ils sont sans conséquence. Ils doivent être réévalués avant toute exposition élargie de l'API. * **L'API n'a aucune authentification** et l'exemple de configuration l'expose sur ``0.0.0.0:8080``. Quiconque atteint ce port pilote le host KVM. * ``vm//password`` est stocké tel quel (c'est un hash) et restitué par ``/db?prefix=vm/`` du serveur d'administration — contenu par ``admin.enabled: false`` et l'écoute en boucle locale. * ``/run/two/metadata//vendor-data`` est en ``0644`` et contient ce hash : tout compte local du host peut le lire. * ``pkg/systemd.New()`` n'a **pas de timeout** : si le socket D-Bus accepte sans répondre, l'appelant se fige. Concerne le watchdog, la création et la suppression de subnets, et le serveur de metadata. * Il n'y a **pas de rollback** : un échec partiel de création laisse des objets réseau orphelins jusqu'à un ``DELETE`` explicite.