This commit is contained in:
forgejo-actions 2026-10-24 14:45:23 +00:00
commit b20e16ee62
28 changed files with 289 additions and 180 deletions

View file

@ -834,9 +834,10 @@ un état stable.</p>
borne les opérations qui attendent une transition ; l’appelant doit avoir sa propre borne.</p></li>
<li><p><strong>Traiter ``error`` comme terminal, pas comme un échec transitoire.</strong> Un <code class="docutils literal notranslate"><span class="pre">Execute</span></code> en échec
ne se rejoue pas tout seul.</p></li>
<li><p><strong>Ne pas enchaîner sans vérifier.</strong> Créer un subnet dont le VPC est encore en <code class="docutils literal notranslate"><span class="pre">creating</span></code>
échoue en 422 ; démarrer une VM sur un subnet en <code class="docutils literal notranslate"><span class="pre">creating</span></code> ou <code class="docutils literal notranslate"><span class="pre">running</span></code> est en revanche
accepté.</p></li>
<li><p><strong>Savoir ce qui s’enchaîne.</strong> Créer un subnet dont le VPC est encore en <code class="docutils literal notranslate"><span class="pre">creating</span></code>, ou
démarrer une VM sur un subnet en <code class="docutils literal notranslate"><span class="pre">creating</span></code>, est accepté : l”<code class="docutils literal notranslate"><span class="pre">Execute</span></code> attend que le parent
passe <code class="docutils literal notranslate"><span class="pre">running</span></code>, dans la limite de <code class="docutils literal notranslate"><span class="pre">dispatcher.timeout_seconds</span></code> ; au-delà, la ressource passe
en <code class="docutils literal notranslate"><span class="pre">error</span></code>. Le refus en 422 ne vaut que pour un parent absent, en <code class="docutils literal notranslate"><span class="pre">error</span></code> ou en <code class="docutils literal notranslate"><span class="pre">deleting</span></code>.</p></li>
</ul>
</section>
<section id="codes-de-retour">
@ -859,20 +860,29 @@ accepté.</p></li>
<td><p>lecture réussie (<code class="docutils literal notranslate"><span class="pre">GET</span></code>)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">400</span></code></p></td>
<td><p>champ obligatoire manquant, corps invalide, <code class="docutils literal notranslate"><span class="pre">iface_type</span></code> inconnu, base64 invalide</p></td>
<td><p>champ obligatoire manquant, corps invalide, base64 invalide ; CIDR de VPC invalide,
<code class="docutils literal notranslate"><span class="pre">l3vni</span></code> hors plage ; <code class="docutils literal notranslate"><span class="pre">interface_ip</span></code> absent (<code class="docutils literal notranslate"><span class="pre">bridge</span></code>, <code class="docutils literal notranslate"><span class="pre">public_ip</span></code>) ou fourni
(<code class="docutils literal notranslate"><span class="pre">vxlan</span></code>) ; interface de VM sans <code class="docutils literal notranslate"><span class="pre">mac</span></code>, nombre d’interfaces <code class="docutils literal notranslate"><span class="pre">primary</span></code> différent de 1</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">404</span></code></p></td>
<td><p>ressource inexistante</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">409</span></code></p></td>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">405</span></code></p></td>
<td><p>méthode non prise en charge ; corps <code class="docutils literal notranslate"><span class="pre">{&quot;error&quot;:</span> <span class="pre">&quot;method</span> <span class="pre">not</span> <span class="pre">allowed&quot;}</span></code>, mais servi en
<code class="docutils literal notranslate"><span class="pre">text/plain</span></code> par <code class="docutils literal notranslate"><span class="pre">/vpcs</span></code> et <code class="docutils literal notranslate"><span class="pre">/subnets</span></code> (et leurs <code class="docutils literal notranslate"><span class="pre">/{name}</span></code>), en JSON par <code class="docutils literal notranslate"><span class="pre">/vms</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">409</span></code></p></td>
<td><p>conflit d’existence ou d’état : ressource déjà créée, ou suppression depuis un état qui
ne l’autorise pas ; pour un VPC, subnets encore présents ; pour un subnet, VM non
supprimées qui l’utilisent encore</p></td>
ne l’autorise pas ; pour un VPC, subnets encore présents, <code class="docutils literal notranslate"><span class="pre">l3vni</span></code> déjà utilisée par un
autre VPC, ou <code class="docutils literal notranslate"><span class="pre">l3vni</span></code> demandée sans section <code class="docutils literal notranslate"><span class="pre">bgp</span></code> ; pour un subnet, VM non supprimées
qui l’utilisent encore</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">422</span></code></p></td>
<td><p>dépendance absente ou pas prête : VPC parent d’un subnet, subnet d’une VM</p></td>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">422</span></code></p></td>
<td><p>dépendance absente ou inutilisable : VPC parent d’un subnet, subnet d’une VM, absent, en
<code class="docutils literal notranslate"><span class="pre">error</span></code> ou en <code class="docutils literal notranslate"><span class="pre">deleting</span></code> ; <code class="docutils literal notranslate"><span class="pre">mode</span></code> de subnet inconnu ; CIDR <code class="docutils literal notranslate"><span class="pre">vxlan</span></code> invalide ou plus
petit que <code class="docutils literal notranslate"><span class="pre">/29</span></code> ; IP de VM hors du CIDR du subnet ou réservée</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">500</span></code></p></td>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">500</span></code></p></td>
<td><p>erreur interne</p></td>
</tr>
</tbody>

View file

@ -425,7 +425,7 @@ du contrat : en cas d’écart avec le reste de la documentation, c’est elle q
</pre></div>
</div>
</p></li>
<li><p><span><a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/400">400 Bad Request</a></span> – <p>Missing required field, invalid request body, or l3vni out of range</p>
<li><p><span><a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/400">400 Bad Request</a></span> – <p>Missing required field, invalid request body, invalid CIDR, or l3vni out of range</p>
<p><strong>Example response:</strong></p>
<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">400</span> <span class="ne">Bad Request</span>
<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>

View file

@ -521,7 +521,7 @@ rechargée est perdue au prochain démarrage de l’agent.</p>
<span class="nt">qemu</span><span class="p">:</span>
<span class="w"> </span><span class="nt">ovmf_code_path</span><span class="p">:</span><span class="w"> </span><span class="s">"/usr/share/OVMF/OVMF_CODE.fd"</span>
<span class="w"> </span><span class="nt">ovmf_vars_template</span><span class="p">:</span><span class="w"> </span><span class="s">"/usr/share/OVMF/OVMF_VARS.fd"</span>
<span class="w"> </span><span class="nt">uefi_vars_dir</span><span class="p">:</span><span class="w"> </span><span class="s">"/run/two/vms/efi"</span>
<span class="w"> </span><span class="nt">uefi_vars_dir</span><span class="p">:</span><span class="w"> </span><span class="s">"/run/two/vms/uefi"</span>
<span class="w"> </span><span class="nt">serial_dir</span><span class="p">:</span><span class="w"> </span><span class="s">"/run/two/vms/serial"</span>
<span class="w"> </span><span class="nt">monitor_dir</span><span class="p">:</span><span class="w"> </span><span class="s">"/run/two/vms/monitor"</span>
<span class="w"> </span><span class="nt">qmp_dir</span><span class="p">:</span><span class="w"> </span><span class="s">"/run/two/vms/qmp"</span>
@ -606,7 +606,8 @@ l’autre.</p>
<span class="w"> </span><span class="nt">interval_seconds</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">60</span>
</pre></div>
</div>
<p>Vérification périodique <strong>en lecture seule</strong> — voir <a class="reference internal" href="observabilite.html"><span class="doc">Observabilité</span></a>.</p>
<p>Vérification périodique <strong>en lecture seule</strong> — voir <a class="reference internal" href="observabilite.html"><span class="doc">Observabilité</span></a>.
<strong>Désactivée par défaut</strong> (<code class="docutils literal notranslate"><span class="pre">enabled:</span> <span class="pre">false</span></code>) : sans cette section, aucun contrôle ne tourne.</p>
</section>
<section id="journalisation">
<h2>Journalisation<a class="headerlink" href="#journalisation" title="Lien vers cette rubrique">#</a></h2>

View file

@ -401,7 +401,7 @@ journalctl<span class="w"> </span>-u<span class="w"> </span><span class="s1">'dh
<span class="c1"># Ce qu'il enverrait à une MAC donnée, sans effet de bord</span>
<span class="nb">echo</span><span class="w"> </span><span class="s1">'{"verb":"probe","mac":"00:22:33:00:00:0A"}'</span><span class="w"> </span><span class="se">\</span>
<span class="w"> </span><span class="p">|</span><span class="w"> </span>socat<span class="w"> </span>-<span class="w"> </span>UNIX-CONNECT:/run/two/dhcp/&lt;netns&gt;_&lt;bridge&gt;.sock<span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span>.lease
<span class="w"> </span><span class="p">|</span><span class="w"> </span>socat<span class="w"> </span>-<span class="w"> </span>UNIX-CONNECT:/run/two/dhcp/&lt;netns&gt;_&lt;bridge&gt;.sock<span class="w"> </span><span class="p">|</span><span class="w"> </span>jq<span class="w"> </span><span class="s1">'{served, lease}'</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">probe</span></code> est le point de départ le plus rapide : il montre l’adresse, le masque, le routeur, les
@ -454,9 +454,11 @@ user-data. Vérification dans le guest :</p>
ls<span class="w"> </span>/var/lib/cloud/instances/
</pre></div>
</div>
<p><strong>2. Le serveur de metadata est injoignable.</strong> Depuis le guest :</p>
<p><strong>2. Le serveur de metadata est injoignable.</strong> Depuis le guest — le serveur ne sert que
<code class="docutils literal notranslate"><span class="pre">/meta-data</span></code>, <code class="docutils literal notranslate"><span class="pre">/user-data</span></code>, <code class="docutils literal notranslate"><span class="pre">/network-config</span></code> et <code class="docutils literal notranslate"><span class="pre">/vendor-data</span></code>, tout autre chemin
renvoie 404 :</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>ip<span class="w"> </span>route
curl<span class="w"> </span>-s<span class="w"> </span>http://169.254.169.254/latest/meta-data/
curl<span class="w"> </span>-s<span class="w"> </span>http://169.254.169.254/meta-data
</pre></div>
</div>
<p>La route <code class="docutils literal notranslate"><span class="pre">169.254.169.254/32</span></code> doit être présente, avec l”<code class="docutils literal notranslate"><span class="pre">interface_ip</span></code> du subnet comme
@ -471,8 +473,9 @@ ls<span class="w"> </span>-l<span class="w"> </span>/run/two/metadata/&lt;vm&gt;
</section>
<section id="le-user-data-est-servi-vide">
<h2>Le user-data est servi vide<a class="headerlink" href="#le-user-data-est-servi-vide" title="Lien vers cette rubrique">#</a></h2>
<p>Un document fourni explicitement vide est servi vide — ce n’est pas la même chose qu’un document
absent, qui retombe sur le template. Vérifier le contenu réellement écrit :</p>
<p>C’est le comportement attendu quand <code class="docutils literal notranslate"><span class="pre">user_data</span></code> est absent ou vide à la création : les deux cas
sont équivalents, et aucun template ne prend le relais pour <code class="docutils literal notranslate"><span class="pre">user-data</span></code>. Vérifier le contenu
réellement écrit :</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>cat<span class="w"> </span>/run/two/metadata/&lt;vm&gt;/user-data
</pre></div>
</div>
@ -482,7 +485,7 @@ absent, qui retombe sur le template. Vérifier le contenu réellement écrit :</
<h2>La VM ne démarre pas (UEFI)<a class="headerlink" href="#la-vm-ne-demarre-pas-uefi" title="Lien vers cette rubrique">#</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">uefi:</span> <span class="pre">true</span></code> exige les fichiers OVMF déclarés dans la configuration :</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>ls<span class="w"> </span>-l<span class="w"> </span>/usr/share/OVMF/OVMF_CODE.fd<span class="w"> </span>/usr/share/OVMF/OVMF_VARS.fd
ls<span class="w"> </span>-l<span class="w"> </span>/run/two/vms/efi/
ls<span class="w"> </span>-l<span class="w"> </span>/run/two/vms/uefi/
</pre></div>
</div>
<p>Sur Debian et Ubuntu, le paquet est <code class="docutils literal notranslate"><span class="pre">ovmf</span></code>.</p>

View file

@ -392,7 +392,8 @@ ou <code class="docutils literal notranslate"><span class="pre">deleting</span><
<section id="watchdog">
<h2>Watchdog<a class="headerlink" href="#watchdog" title="Lien vers cette rubrique">#</a></h2>
<p>Une goroutine périodique vérifie que les ressources marquées <code class="docutils literal notranslate"><span class="pre">running</span></code> en base existent
toujours sur le système, et <strong>notifie les écarts sans jamais réparer</strong>.</p>
toujours sur le système, et <strong>notifie les écarts sans jamais réparer</strong>. Il est <strong>désactivé par
défaut</strong> (<code class="docutils literal notranslate"><span class="pre">enabled:</span> <span class="pre">false</span></code>) ; l’activer explicitement :</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">watchdog</span><span class="p">:</span>
<span class="w"> </span><span class="nt">enabled</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w"> </span><span class="nt">interval_seconds</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">60</span>
@ -429,15 +430,18 @@ subsiste jusqu’à une action explicite (<code class="docutils literal notransl
<code class="docutils literal notranslate"><span class="pre">logger.debug:</span> <span class="pre">true</span></code> forçant <code class="docutils literal notranslate"><span class="pre">debug</span></code>.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>journalctl<span class="w"> </span>-u<span class="w"> </span>agent<span class="w"> </span>-f
journalctl<span class="w"> </span>-u<span class="w"> </span><span class="s1">'metadata@i-web'</span><span class="w"> </span>-n<span class="w"> </span><span class="m">50</span>
tail<span class="w"> </span>-f<span class="w"> </span>/var/log/dnsmasq-vp-admin_br-sn000001.log<span class="w"> </span><span class="c1"># backend dnsmasq</span>
journalctl<span class="w"> </span>-fu<span class="w"> </span><span class="s1">'dhcp@vp-admin_br-sn000001'</span><span class="w"> </span><span class="c1"># backend two</span>
tail<span class="w"> </span>-f<span class="w"> </span>/var/log/dnsmasq-vp-admin_br-000001.log<span class="w"> </span><span class="c1"># backend dnsmasq</span>
journalctl<span class="w"> </span>-fu<span class="w"> </span><span class="s1">'dhcp@vp-admin_br-000001'</span><span class="w"> </span><span class="c1"># backend two</span>
</pre></div>
</div>
</section>
<section id="inspection-de-la-base">
<h2>Inspection de la base<a class="headerlink" href="#inspection-de-la-base" title="Lien vers cette rubrique">#</a></h2>
<p>En ligne de commande, sur l’host :</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>/opt/two/bin/db<span class="w"> </span>-conf<span class="w"> </span>/etc/two/agent.yml
<p>En ligne de commande, sur l’host. Le binaire <code class="docutils literal notranslate"><span class="pre">db</span></code> n’est <strong>ni publié dans les releases ni
déployé</strong> par <code class="docutils literal notranslate"><span class="pre">deploy.sh</span></code> : il se compile depuis les sources, puis se copie sur l’host. Sans
sous-commande, il n’affiche que son usage ; <code class="docutils literal notranslate"><span class="pre">print</span></code> liste toute la base :</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">CGO_ENABLED</span><span class="o">=</span><span class="m">0</span><span class="w"> </span><span class="nv">GOOS</span><span class="o">=</span>linux<span class="w"> </span><span class="nv">GOARCH</span><span class="o">=</span>amd64<span class="w"> </span>go<span class="w"> </span>build<span class="w"> </span>-o<span class="w"> </span>db<span class="w"> </span>./cmd/db
./db<span class="w"> </span>-conf<span class="w"> </span>/etc/two/agent.yml<span class="w"> </span>print
</pre></div>
</div>
<div class="admonition warning">

View file

@ -361,7 +361,8 @@
<section id="services-systemd">
<h1>Services systemd<a class="headerlink" href="#services-systemd" title="Lien vers cette rubrique">#</a></h1>
<p>Quatre units, installées sous <code class="docutils literal notranslate"><span class="pre">/opt/two/bin</span></code> par <code class="docutils literal notranslate"><span class="pre">deploy.sh</span></code>. Les deux units DHCP
<p>Quatre units, installées dans <code class="docutils literal notranslate"><span class="pre">/etc/systemd/system</span></code> par <code class="docutils literal notranslate"><span class="pre">deploy.sh</span></code> ; les binaires et scripts
qu’elles lancent sont sous <code class="docutils literal notranslate"><span class="pre">/opt/two/bin</span></code>. Les deux units DHCP
s’excluent : celle qui tourne dépend de <code class="docutils literal notranslate"><span class="pre">dhcp.backend</span></code> (voir <a class="reference internal" href="configuration.html"><span class="doc">Configuration</span></a>).</p>
<div class="pst-scrollable-table-container"><table class="table">
<colgroup>
@ -398,8 +399,8 @@ s’excluent : celle qui tourne dépend de <code class="docutils literal notrans
<p>Les instances sont créées et pilotées par l’agent au fil des créations de subnets et de VM : il
n’y a pas à les démarrer à la main en fonctionnement normal.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>systemctl<span class="w"> </span>status<span class="w"> </span>agent
systemctl<span class="w"> </span>status<span class="w"> </span><span class="s1">'dnsmasq@vp-admin_br-sn000001'</span><span class="w"> </span><span class="c1"># backend dnsmasq</span>
systemctl<span class="w"> </span>status<span class="w"> </span><span class="s1">'dhcp@vp-admin_br-sn000001'</span><span class="w"> </span><span class="c1"># backend two</span>
systemctl<span class="w"> </span>status<span class="w"> </span><span class="s1">'dnsmasq@vp-admin_br-000001'</span><span class="w"> </span><span class="c1"># backend dnsmasq</span>
systemctl<span class="w"> </span>status<span class="w"> </span><span class="s1">'dhcp@vp-admin_br-000001'</span><span class="w"> </span><span class="c1"># backend two</span>
systemctl<span class="w"> </span>status<span class="w"> </span><span class="s1">'metadata@i-web'</span>
</pre></div>
</div>
@ -437,9 +438,9 @@ pas d’adresse.</p>
<code class="docutils literal notranslate"><span class="pre">dhcp</span></code>, à qui il passe le bridge à servir et ses deux chemins de fichiers — il ne déduit rien et
ignore le netns dans lequel il tourne :</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>/opt/two/bin/dhcp<span class="w"> </span>-conf<span class="w"> </span>/etc/two/agent.yml<span class="w"> </span><span class="se">\</span>
<span class="w"> </span>-interface<span class="w"> </span>br-sn000001<span class="w"> </span><span class="se">\</span>
<span class="w"> </span>-state<span class="w"> </span>/run/two/dhcp/vp-admin_br-sn000001.state<span class="w"> </span><span class="se">\</span>
<span class="w"> </span>-socket<span class="w"> </span>/run/two/dhcp/vp-admin_br-sn000001.sock
<span class="w"> </span>-interface<span class="w"> </span>br-000001<span class="w"> </span><span class="se">\</span>
<span class="w"> </span>-state<span class="w"> </span>/run/two/dhcp/vp-admin_br-000001.state<span class="w"> </span><span class="se">\</span>
<span class="w"> </span>-socket<span class="w"> </span>/run/two/dhcp/vp-admin_br-000001.sock
</pre></div>
</div>
<div class="pst-scrollable-table-container"><table class="table">