This commit is contained in:
forgejo-actions 2026-10-19 22:59:46 +00:00
commit 565eacdfaa
8 changed files with 48 additions and 13 deletions

View file

@ -372,11 +372,11 @@ subnet/<name>/relay_ip → <ip> (mode vxlan, calcul
subnet/<name>/local_iface → <bridge-name>
subnet/<name>/default_route → "true" | "false"
subnet/<name>/gateway → <ip> (optionnel)
subnet/<name>/dhcp/<ip> → <mac>
vm/<name>/state → creating | running | error | deleting | deleted
vm/<name>/nic/<i>/subnet → <subnet-name> (une interface par index, ordre du tableau interfaces)
vm/<name>/nic/<i>/ip → <ip>
vm/<name>/nic/<i>/mac → <mac> (fournie par l'appelant, conservée telle quelle)
vm/<name>/nic/<i>/primary → "true" (exactement une interface ; absent sur les autres)
vm/<name>/nic/<i>/tap_id → <int> (alloué au premier démarrage, puis conservé)
vm/<name>/metadata_port → <port>
@ -398,6 +398,12 @@ lus depuis le subnet, leur source canonique. De même, la L3VNI d’un VPC n’e
<p><strong>Ancien schéma des VM.</strong> Avant le multi-interfaces, une VM portait directement <code class="docutils literal notranslate"><span class="pre">subnet</span></code>, <code class="docutils literal notranslate"><span class="pre">ip</span></code>
et <code class="docutils literal notranslate"><span class="pre">tap_id</span></code>. L’agent les migre au démarrage vers <code class="docutils literal notranslate"><span class="pre">nic/0/…</span></code>, marquée <code class="docutils literal notranslate"><span class="pre">primary</span></code>, avant
d’ouvrir son API ; une VM qui a déjà des clés <code class="docutils literal notranslate"><span class="pre">nic/</span></code> est laissée telle quelle.</p>
<p><strong>Ancienne table des MAC.</strong> Jusqu’en 0.1.0, la MAC d’une interface était dérivée du rang de son IP
et préchargée pour tout le <code class="docutils literal notranslate"><span class="pre">cidr</span></code> sous <code class="docutils literal notranslate"><span class="pre">subnet/&lt;name&gt;/dhcp/&lt;ip&gt;</span></code>. Au démarrage, l’agent
recopie la MAC de chaque interface existante dans <code class="docutils literal notranslate"><span class="pre">vm/&lt;name&gt;/nic/&lt;i&gt;/mac</span></code>, puis supprime ces
clés. Les VM <code class="docutils literal notranslate"><span class="pre">deleted</span></code> sont ignorées. Une interface dont la MAC est introuvable fait échouer le
démarrage en la nommant, et la table reste en place tant que toutes les interfaces ne sont pas
migrées.</p>
<p><strong>Les états passent par ``state``.</strong> Toujours <code class="docutils literal notranslate"><span class="pre">state.Set</span></code> / <code class="docutils literal notranslate"><span class="pre">state.Get</span></code> : <code class="docutils literal notranslate"><span class="pre">Set</span></code> refuse une
valeur hors énumération, <code class="docutils literal notranslate"><span class="pre">Get</span></code> refuse de retourner une valeur non reconnue. <code class="docutils literal notranslate"><span class="pre">error</span></code> n’est
écrit que par <code class="docutils literal notranslate"><span class="pre">Dispatcher.Dispatch</span></code>, via <code class="docutils literal notranslate"><span class="pre">cmd.Key()</span></code>.</p>

View file

@ -864,6 +864,9 @@ filet qui couvre une VM tant que son <code class="docutils literal notranslate">
le nom de l’interface dans le guest. Exactement une interface doit être <code class="docutils literal notranslate"><span class="pre">primary</span></code> : elle porte
la route par défaut et le serveur de metadata. Tous les subnets d’une VM doivent appartenir au
<strong>même VPC</strong>.</p>
<p><strong>MAC.</strong> Chaque interface porte la MAC choisie par l’appelant, comme son IP. L’agent la donne
telle quelle à QEMU et à la réservation DHCP, sans en vérifier le format ni l’unicité : c’est à
l’appelant de garantir qu’elle est unique sur le segment L2.</p>
<p><strong>Routes.</strong> Dans un VPC routé par <code class="docutils literal notranslate"><span class="pre">l3vni</span></code>, chaque interface sur un subnet <code class="docutils literal notranslate"><span class="pre">vxlan</span></code> est annoncée
en <code class="docutils literal notranslate"><span class="pre">/32</span></code> dans la VRF du VPC une fois QEMU démarré, juste avant le passage en <code class="docutils literal notranslate"><span class="pre">running</span></code>. À la
suppression, ces <code class="docutils literal notranslate"><span class="pre">/32</span></code> sont retirés <strong>avant</strong> l’arrêt de QEMU. Comme un subnet ne peut être
@ -876,7 +879,7 @@ par le contrôleur SCSI (<code class="docutils literal notranslate"><span class=
<section id="ce-qui-est-stocke-et-ou">
<h2>Ce qui est stocké, et où<a class="headerlink" href="#ce-qui-est-stocke-et-ou" title="Lien vers cette rubrique">#</a></h2>
<p>Une ressource ne porte en base que ce qui lui est propre. Une VM stocke le <strong>lien</strong> vers son
subnet (<code class="docutils literal notranslate"><span class="pre">vm/&lt;name&gt;/subnet</span></code>), pas le VPC ni le bridge ni la gateway : ces valeurs sont lues
subnet (<code class="docutils literal notranslate"><span class="pre">vm/&lt;name&gt;/nic/&lt;i&gt;/subnet</span></code>), pas le VPC ni le bridge ni la gateway : ces valeurs sont lues
depuis le subnet, leur source canonique. Le schéma complet des clés est dans
<a class="reference internal" href="../architecture/stockage.html"><span class="doc">Schéma des clés</span></a>.</p>
</section>

View file

@ -870,7 +870,7 @@ obligatoire.</p>
<span class="s1"> "uefi": true,</span>
<span class="s1"> "metadata": {"sshkey": "ssh-ed25519 AAAA…",</span>
<span class="s1"> "user_data": "'</span><span class="s2">"</span><span class="k">$(</span>base64<span class="w"> </span>&lt;<span class="w"> </span>user-data.yml<span class="w"> </span><span class="p">|</span><span class="w"> </span>tr<span class="w"> </span>-d<span class="w"> </span><span class="s1">'\n'</span><span class="k">)</span><span class="s2">"</span><span class="s1">'"},</span>
<span class="s1"> "interfaces": [{"subnet": "sn-000001", "ip": "10.1.1.2", "primary": true}],</span>
<span class="s1"> "interfaces": [{"subnet": "sn-000001", "ip": "10.1.1.2", "mac": "52:54:00:01:01:02", "primary": true}],</span>
<span class="s1"> "storage": [{"path": "/var/lib/two/volumes/i-web.qcow2", "dev": "vda"}]}'</span>
</pre></div>
</div>
@ -882,6 +882,9 @@ contenu.</p>
<dt><code class="docutils literal notranslate"><span class="pre">password</span></code> est un <strong>hash</strong>, pas un mot de passe</dt><dd><p>Le champ attend la valeur de la clé <code class="docutils literal notranslate"><span class="pre">passwd</span></code> de cloud-config (<code class="docutils literal notranslate"><span class="pre">$6$…</span></code>). Sans <code class="docutils literal notranslate"><span class="pre">password</span></code>
ni <code class="docutils literal notranslate"><span class="pre">sshkey</span></code>, aucun compte n’est créé.</p>
</dd>
<dt>Chaque interface a sa <code class="docutils literal notranslate"><span class="pre">mac</span></code></dt><dd><p>Choisie par l’appelant, obligatoire (400 sinon) et jamais vérifiée : deux interfaces sur le
même segment L2 doivent avoir des MAC distinctes.</p>
</dd>
<dt>Exactement une interface est <code class="docutils literal notranslate"><span class="pre">primary</span></code></dt><dd><p>Elle porte la route par défaut et le serveur de metadata. L’ordre du tableau détermine le
slot PCI (<code class="docutils literal notranslate"><span class="pre">0x03</span> <span class="pre">+</span> <span class="pre">index</span></code>), donc le nom de l’interface dans le guest. Tous les subnets d’une
VM doivent appartenir au même VPC.</p>

View file

@ -754,7 +754,7 @@ fait en fermant le ticket. Chaque ticket concerné liste ses marqueurs en commen
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">11-validation</span></code></p></td>
<td><p>validation de l’API — refus synchrones (400, 409, 422) des VPC, subnets et VM, sans trace en base</p></td>
<td><p>hv1</p></td>
<td><p>#41, #57, #33</p></td>
<td><p>#41, #57, #33, #62</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">12-etats</span></code></p></td>
<td><p>machine d’états — 409 pendant creating, suppression depuis error, dépendances VM → subnet → VPC, recréation sous le même nom</p></td>
@ -764,7 +764,7 @@ fait en fermant le ticket. Chaque ticket concerné liste ses marqueurs en commen
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">21-dhcp-two</span></code></p></td>
<td><p>DHCP par le serveur intégré (backend two) — bail, server-id, renouvellement, option 121, un serveur par subnet, démarrages simultanés</p></td>
<td><p>hv1</p></td>
<td><p>#46, #57</p></td>
<td><p>#46, #57, #62</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">22-dhcp-dnsmasq</span></code></p></td>
<td><p>DHCP par dnsmasq (backend dnsmasq) — bail, server-id, renouvellement, option 121, une instance par subnet écoutant sur la gateway anycast</p></td>
@ -919,7 +919,9 @@ Chaque bloc est précédé des bibliothèques de <code class="docutils literal n
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">core.sh</span></code> : <code class="docutils literal notranslate"><span class="pre">check</span></code>, <code class="docutils literal notranslate"><span class="pre">known</span></code>, <code class="docutils literal notranslate"><span class="pre">info</span></code>, appels à l’API, attente des états ;</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">vm.sh</span></code> : image Debian compatible two, clé SSH, <code class="docutils literal notranslate"><span class="pre">vm_launch</span></code> (plusieurs NIC et disques, UEFI,
<code class="docutils literal notranslate"><span class="pre">user_data</span></code>, mot de passe), SSH, bail, métadonnées ;</p></li>
<code class="docutils literal notranslate"><span class="pre">user_data</span></code>, mot de passe), SSH, bail, métadonnées. La MAC de chaque NIC est fournie à l’API :
<code class="docutils literal notranslate"><span class="pre">52:54:00</span></code> suivi des trois derniers octets de l’IP (<code class="docutils literal notranslate"><span class="pre">mac_for_ip</span></code>), unique dans la suite
puisque chaque test a sa plage ; <code class="docutils literal notranslate"><span class="pre">--nic</span> <span class="pre">sn=ip=mac</span></code> en impose une autre ;</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">net.sh</span></code> : VPC, subnets, MAC anycast, trames brutes, règles ebtables, VRRP ;</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">evpn.sh</span></code> : VRF, BGP, L3VNI, watchdog ;</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fixture.sh</span></code> : nettoyage et <code class="docutils literal notranslate"><span class="pre">assert_clean</span></code>, appelés par le runner.</p></li>
@ -947,8 +949,9 @@ on<span class="w"> </span>hv1<span class="w"> </span><span class="s">&lt;&lt;'NO
la cible est vivante et que le chemin du test fonctionne ;</p></li>
<li><p><strong>``vm_fails`` pour le négatif</strong>, jamais <code class="docutils literal notranslate"><span class="pre">!</span></code> devant un <code class="docutils literal notranslate"><span class="pre">vm_ssh</span></code> : un SSH en panne doit
échouer, pas passer pour une isolation ;</p></li>
<li><p><strong>une donnée qui distingue réellement les cas</strong> : two dérive la MAC du rang de l’IP, donc deux
subnets ont les mêmes MAC ; comparer des couples MAC/IP, pas des MAC ;</p></li>
<li><p><strong>une donnée qui distingue réellement les cas</strong> : rien n’empêche deux subnets de porter les
mêmes MAC (c’était le cas quand two les dérivait du rang de l’IP) ; comparer des couples MAC/IP,
pas des MAC ;</p></li>
<li><p><strong>les mesures en ``INFO``</strong>, les attentes en <code class="docutils literal notranslate"><span class="pre">check</span></code> : un temps de reconvergence se mesure,
il ne se décrète pas ;</p></li>
<li><p><strong>l’en-tête ``# hôtes:`` liste exactement les hôtes où le test crée des ressources</strong> : ce sont
@ -981,7 +984,7 @@ INFO: retour du VTEP distant et du trafic 31 s après le redémarrage de FRR
</pre></div>
</div>
<p>Dans ce run, le contrôle « uniquement les MAC de son subnet » de <code class="docutils literal notranslate"><span class="pre">s1</span></code> ne prouvait rien : two
dérive la MAC du rang de l’IP, et les VM <code class="docutils literal notranslate"><span class="pre">.10</span></code>/<code class="docutils literal notranslate"><span class="pre">.11</span></code> des deux subnets avaient les mêmes MAC.
dérivait alors la MAC du rang de l’IP, et les VM <code class="docutils literal notranslate"><span class="pre">.10</span></code>/<code class="docutils literal notranslate"><span class="pre">.11</span></code> des deux subnets avaient les mêmes MAC.
Vérifié à la main sur le lab, chaque serveur DHCP ne connaissait que les couples MAC/IP de son
subnet ; le scénario compare désormais ces couples.</p>
<p><code class="docutils literal notranslate"><span class="pre">s7-l3vni</span></code> le 2026-10-05, même lab, FRR 10.7.1 : <strong>46 réussi(s), 0 échoué(s)</strong> au dernier run.

View file

@ -615,6 +615,7 @@ du contrat : en cas d’écart avec le reste de la documentation, c’est elle q
<span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="nt">"subnet"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"ip"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"mac"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"primary"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
<span class="w"> </span><span class="p">}</span>
<span class="w"> </span><span class="p">],</span>
@ -668,6 +669,7 @@ du contrat : en cas d’écart avec le reste de la documentation, c’est elle q
<span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="nt">"subnet"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"ip"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"mac"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"primary"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
<span class="w"> </span><span class="p">}</span>
<span class="w"> </span><span class="p">],</span>
@ -699,6 +701,7 @@ du contrat : en cas d’écart avec le reste de la documentation, c’est elle q
<span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="nt">"subnet"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"ip"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"mac"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"primary"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
<span class="w"> </span><span class="p">}</span>
<span class="w"> </span><span class="p">],</span>
@ -796,6 +799,7 @@ du contrat : en cas d’écart avec le reste de la documentation, c’est elle q
<span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="nt">"subnet"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"ip"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"mac"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"primary"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
<span class="w"> </span><span class="p">}</span>
<span class="w"> </span><span class="p">],</span>
@ -864,6 +868,7 @@ du contrat : en cas d’écart avec le reste de la documentation, c’est elle q
<span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="nt">"subnet"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"ip"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"mac"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"primary"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span>
<span class="w"> </span><span class="p">}</span>
<span class="w"> </span><span class="p">],</span>

View file

@ -410,7 +410,9 @@ la MAC n’est pas réservée — l’ordre <code class="docutils literal notran
été créée par cet agent.</p>
<p>Le watchdog signale ces écarts de lui-même, à chaque tick, en comparant l’état servi à la base :
<code class="docutils literal notranslate"><span class="pre">dhcp</span> <span class="pre">reservation</span> <span class="pre">missing</span> <span class="pre">on</span> <span class="pre">the</span> <span class="pre">server</span></code>, <code class="docutils literal notranslate"><span class="pre">stale</span> <span class="pre">dhcp</span> <span class="pre">reservation</span></code>, <code class="docutils literal notranslate"><span class="pre">dhcp</span> <span class="pre">reservation</span>
<span class="pre">diverges</span></code>. Regarder ses notifications avant de sonder à la main.</p>
<span class="pre">diverges</span></code>. Regarder ses notifications avant de sonder à la main. Seules les VM <code class="docutils literal notranslate"><span class="pre">running</span></code> sont
comparées : pendant une création ou une suppression, ou pour une VM en <code class="docutils literal notranslate"><span class="pre">error</span></code>, la réservation
peut être présente ou absente sans alerte.</p>
<p>Si le serveur ne voit passer aucune requête, le problème est en amont : tap absent, bridge non
raccordé, VM dans le mauvais netns.</p>
</section>

File diff suppressed because one or more lines are too long

View file

@ -437,6 +437,15 @@ route du subnet a la gateway pour source</p></li>
l’adresse de réseau ou de broadcast du subnet, ni une adresse hors de son <code class="docutils literal notranslate"><span class="pre">cidr</span></code> (422)</p></li>
<li><p>Le watchdog contrôle le macvlan, sa MAC, les deux adresses et l’entrée FDB</p></li>
</ul>
<p><strong>MAC des VM fournie à la création (#62)</strong></p>
<ul class="simple">
<li><p>Champ <code class="docutils literal notranslate"><span class="pre">mac</span></code> obligatoire par interface dans <code class="docutils literal notranslate"><span class="pre">POST</span> <span class="pre">/vms</span></code>, rendu par <code class="docutils literal notranslate"><span class="pre">GET</span> <span class="pre">/vms/{name}</span></code>. Il est
passé tel quel à QEMU et à la réservation DHCP ; son format et son unicité relèvent de l’appelant</p></li>
<li><p>Fin de la table <code class="docutils literal notranslate"><span class="pre">subnet/&lt;name&gt;/dhcp/&lt;ip&gt;</span></code>, qui préchargeait une MAC par adresse du <code class="docutils literal notranslate"><span class="pre">cidr</span></code> : la
MAC dérivée du rang de l’IP donnait la même MAC à deux interfaces d’une VM de même rang dans
leurs subnets (VM injoignable), et n’était pas tenable en IPv6</p></li>
<li><p>Migration au démarrage : les VM existantes gardent leur MAC, recopiée sur chaque interface</p></li>
</ul>
<p><strong>Exploitation</strong></p>
<ul class="simple">
<li><p>Le watchdog contrôle aussi, avec une section <code class="docutils literal notranslate"><span class="pre">bgp</span></code> : les sessions vers les route reflectors ;
@ -445,7 +454,9 @@ de routeur) ; la cohérence entre routes exportées et ressources <code class="d
sans propriétaire est signalée comme <strong>trou noir</strong>, une route attendue absente comme manquante</p></li>
<li><p>Le watchdog interroge le serveur DHCP intégré et compare les réservations servies à celles que
la base implique. Il nomme ce qui diverge — ordre perdu à la création, ordre perdu à la
suppression, adresse ou route par défaut divergente — et reste en lecture seule</p></li>
suppression, adresse ou route par défaut divergente — et reste en lecture seule. Une VM en
<code class="docutils literal notranslate"><span class="pre">creating</span></code>, <code class="docutils literal notranslate"><span class="pre">deleting</span></code> ou <code class="docutils literal notranslate"><span class="pre">error</span></code> n’est pas comparée : sa réservation peut être présente ou
absente sans alerte, le temps que la création ou la suppression aboutisse (#78)</p></li>
<li><p>La socket de contrôle répond à <code class="docutils literal notranslate"><span class="pre">get-state</span></code> et à <code class="docutils literal notranslate"><span class="pre">probe</span></code>, ce dernier montrant sans effet de bord
ce qui serait envoyé à une MAC donnée : adresse, masque, routeur, DNS et routes</p></li>
<li><p>Documentation Sphinx du projet : concepts, architecture, déploiement et exploitation</p></li>
@ -517,12 +528,14 @@ bash<span class="w"> </span>./deploy.sh<span class="w"> </span>-t<span class="w"
</pre></div>
</div>
<p>Sans <code class="docutils literal notranslate"><span class="pre">dhcp.backend</span></code> ni <code class="docutils literal notranslate"><span class="pre">bgp</span></code> dans <code class="docutils literal notranslate"><span class="pre">/etc/two/agent.yml</span></code>, le comportement est celui de la 0.1.0, à
deux exceptions près, qui touchent les appelants de l’API :</p>
trois exceptions près, qui touchent les appelants de l’API :</p>
<ul class="simple">
<li><p><strong><code class="docutils literal notranslate"><span class="pre">interface_ip</span></code> ne se fournit plus pour un subnet <code class="docutils literal notranslate"><span class="pre">vxlan</span></code></strong> : il est refusé (400), l’agent le
calcule. Le retirer des appels de création, et ne plus placer de VM sur les deux dernières
adresses utilisables du subnet. Il reste obligatoire en <code class="docutils literal notranslate"><span class="pre">bridge</span></code> et <code class="docutils literal notranslate"><span class="pre">public_ip</span></code></p></li>
<li><p><strong>un subnet encore utilisé par une VM ne se supprime plus</strong> : supprimer les VM d’abord</p></li>
<li><p><strong>chaque interface d’une VM doit porter sa <code class="docutils literal notranslate"><span class="pre">mac</span></code></strong> (400 sinon) : l’appelant la choisit et en
garantit l’unicité. Les VM existantes gardent la leur, recopiée au premier démarrage de l’agent</p></li>
</ul>
<p>Les subnets <code class="docutils literal notranslate"><span class="pre">vxlan</span></code> existants gardent leur adressage et le modèle précédent (gateway sur le
bridge) jusqu’à leur recréation.</p>