This commit is contained in:
forgejo-actions 2026-10-31 19:16:38 +00:00
commit 3a7372b546
12 changed files with 249 additions and 70 deletions

View file

@ -1734,6 +1734,129 @@ du contrat : en cas d’écart avec le reste de la documentation, c’est elle q
</dl>
</dd></dl>
<dl class="http get">
<dt class="sig sig-object http" id="get--register">
<span class="sig-name descname"><span class="pre">GET</span> </span><span class="sig-name descname"><span class="pre">/register</span></span><a class="headerlink" href="#get--register" title="Lien vers cette définition">#</a></dt>
<dd><p><strong>Facts of the host that do not change while it runs</strong></p>
<p>Read once when the agent starts and kept in memory. Will also be sent to the broker of the orchestrator at startup.</p>
<p><strong>Example request:</strong></p>
<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="nf">GET</span> <span class="nn">/register</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span>
<span class="na">Host</span><span class="o">:</span> <span class="l">example.com</span>
</pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Codes de statut<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><span><a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/200">200 OK</a></span> – <p>Host facts</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">200</span> <span class="ne">OK</span>
<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
<span class="p">{</span>
<span class="w"> </span><span class="nt">"hostname"</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">"cpu"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="nt">"vendor"</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">"model"</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">"sockets"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"cores"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"threads"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span>
<span class="w"> </span><span class="p">},</span>
<span class="w"> </span><span class="nt">"memory_bytes"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"os"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="nt">"id"</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">"version_id"</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">"pretty_name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span>
<span class="w"> </span><span class="p">},</span>
<span class="w"> </span><span class="nt">"kernel"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span>
<span class="p">}</span>
</pre></div>
</div>
</p></li>
<li><p><span><a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/405">405 Method Not Allowed</a></span> – <p>Method other than GET</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">405</span> <span class="ne">Method Not Allowed</span>
<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
<span class="p">{</span>
<span class="w"> </span><span class="nt">"error"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span>
<span class="p">}</span>
</pre></div>
</div>
</p></li>
<li><p><span><a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/503">503 Service Unavailable</a></span> – <p>Host facts could not be read when the agent started (the error says why)</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">503</span> <span class="ne">Service Unavailable</span>
<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
<span class="p">{</span>
<span class="w"> </span><span class="nt">"error"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span>
<span class="p">}</span>
</pre></div>
</div>
</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="http get">
<dt class="sig sig-object http" id="get--ping">
<span class="sig-name descname"><span class="pre">GET</span> </span><span class="sig-name descname"><span class="pre">/ping</span></span><a class="headerlink" href="#get--ping" title="Lien vers cette définition">#</a></dt>
<dd><p><strong>Current state of the host and of the agent</strong></p>
<p>Last reading, taken when the agent starts then every times.host_state_interval seconds and kept in memory; collected_at gives its age. boot_time and agent_start_time tell a host reboot from an agent restart; boot_time plus uptime_seconds give the clock of the host.</p>
<p><strong>Example request:</strong></p>
<div class="highlight-http notranslate"><div class="highlight"><pre><span></span><span class="nf">GET</span> <span class="nn">/ping</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span>
<span class="na">Host</span><span class="o">:</span> <span class="l">example.com</span>
</pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Codes de statut<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><span><a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/200">200 OK</a></span> – <p>Last host state</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">200</span> <span class="ne">OK</span>
<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
<span class="p">{</span>
<span class="w"> </span><span class="nt">"agent_version"</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">"collected_at"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"boot_time"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"agent_start_time"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"uptime_seconds"</span><span class="p">:</span><span class="w"> </span><span class="mf">1.0</span><span class="p">,</span>
<span class="w"> </span><span class="nt">"load"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
<span class="w"> </span><span class="mf">1.0</span>
<span class="w"> </span><span class="p">]</span>
<span class="p">}</span>
</pre></div>
</div>
</p></li>
<li><p><span><a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/405">405 Method Not Allowed</a></span> – <p>Method other than GET</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">405</span> <span class="ne">Method Not Allowed</span>
<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
<span class="p">{</span>
<span class="w"> </span><span class="nt">"error"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span>
<span class="p">}</span>
</pre></div>
</div>
</p></li>
<li><p><span><a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/503">503 Service Unavailable</a></span> – <p>No reading has succeeded yet</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">503</span> <span class="ne">Service Unavailable</span>
<span class="na">Content-Type</span><span class="o">:</span> <span class="l">application/json</span>
<span class="p">{</span>
<span class="w"> </span><span class="nt">"error"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span>
<span class="p">}</span>
</pre></div>
</div>
</p></li>
</ul>
</dd>
</dl>
</dd></dl>
</section>

View file

@ -442,6 +442,7 @@ port. Ne pas l’exposer hors de la boucle locale.</p>
<span class="w"> </span><span class="nt">timeout_subnet_start</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">300</span>
<span class="w"> </span><span class="nt">timeout_vms_start</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">300</span>
<span class="w"> </span><span class="nt">poll_interval</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2</span>
<span class="w"> </span><span class="nt">host_state_interval</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">worker.count</span></code> est le nombre de goroutines qui exécutent les commandes ; <code class="docutils literal notranslate"><span class="pre">buffer_size</span></code> le
@ -463,6 +464,9 @@ encore l’ACPI au premier appui (firmware, chargeur de démarrage) s’éteint
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">poll_interval</span></code></dt><dd><p>pas de toutes ces attentes.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">host_state_interval</span></code></dt><dd><p>intervalle entre deux mesures de l’état de l’hôte servi par <code class="docutils literal notranslate"><span class="pre">GET</span> <span class="pre">/ping</span></code> (voir
<a class="reference internal" href="observabilite.html"><span class="doc">Observabilité</span></a>).</p>
</dd>
</dl>
<p>Chaque valeur doit être strictement positive, et <code class="docutils literal notranslate"><span class="pre">next_vms_shutdown</span></code> inférieur à
<code class="docutils literal notranslate"><span class="pre">timeout_vms_stop</span></code> ; sinon l’agent refuse de démarrer. Les attentes s’enchaînent — une VM,

View file

@ -489,6 +489,7 @@ n’est jamais traversée : la trame est commutée en L2 et le serveur reste inj
<p>Depuis l’host, l’instance correspondante :</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>systemctl<span class="w"> </span>status<span class="w"> </span><span class="s1">'metadata@&lt;vm&gt;'</span>
ls<span class="w"> </span>-l<span class="w"> </span>/run/two/metadata/&lt;vm&gt;/
ip<span class="w"> </span>netns<span class="w"> </span><span class="nb">exec</span><span class="w"> </span>&lt;vpc&gt;<span class="w"> </span>nft<span class="w"> </span>list<span class="w"> </span>chain<span class="w"> </span>ip<span class="w"> </span>two<span class="w"> </span>md-&lt;vm&gt;<span class="w"> </span><span class="c1"># une dnat par IP de la VM</span>
</pre></div>
</div>
</section>
@ -513,8 +514,7 @@ sudo<span class="w"> </span>cat<span class="w"> </span>/run/systemd/netif/leases
systemctl<span class="w"> </span>status<span class="w"> </span>two-hostsvc
cat<span class="w"> </span>/run/two/hostsvc/hostsvc.state<span class="w"> </span><span class="c1"># le VPC doit y figurer</span>
ip<span class="w"> </span>-n<span class="w"> </span>&lt;vpc&gt;<span class="w"> </span>-4<span class="w"> </span>addr<span class="w"> </span>show<span class="w"> </span>dev<span class="w"> </span>hostsvc<span class="w"> </span><span class="c1"># 169.254.169.253/32</span>
ip<span class="w"> </span>netns<span class="w"> </span><span class="nb">exec</span><span class="w"> </span>&lt;vpc&gt;<span class="w"> </span>iptables<span class="w"> </span>-t<span class="w"> </span>nat<span class="w"> </span>-S<span class="w"> </span>TWO-HOSTSVC<span class="w"> </span><span class="c1"># 2 RETURN puis 3 DNAT</span>
ip<span class="w"> </span>netns<span class="w"> </span><span class="nb">exec</span><span class="w"> </span>&lt;vpc&gt;<span class="w"> </span>iptables<span class="w"> </span>-t<span class="w"> </span>nat<span class="w"> </span>-L<span class="w"> </span>TWO-HOSTSVC<span class="w"> </span>-v<span class="w"> </span>-n<span class="w"> </span><span class="c1"># compteurs des redirections</span>
ip<span class="w"> </span>netns<span class="w"> </span><span class="nb">exec</span><span class="w"> </span>&lt;vpc&gt;<span class="w"> </span>nft<span class="w"> </span>list<span class="w"> </span>chain<span class="w"> </span>ip<span class="w"> </span>two<span class="w"> </span>hostsvc<span class="w"> </span><span class="c1"># 2 return puis 3 dnat</span>
ip<span class="w"> </span>netns<span class="w"> </span><span class="nb">exec</span><span class="w"> </span>&lt;vpc&gt;<span class="w"> </span>ss<span class="w"> </span>-lntu<span class="w"> </span><span class="p">|</span><span class="w"> </span>grep<span class="w"> </span><span class="m">169</span>.254.169.253<span class="w"> </span><span class="c1"># 53/udp, 53/tcp, 123/udp</span>
journalctl<span class="w"> </span>-u<span class="w"> </span>two-hostsvc<span class="w"> </span>-n<span class="w"> </span><span class="m">50</span>
</pre></div>

View file

@ -347,6 +347,7 @@
<nav aria-label="Page">
<ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#metriques-prometheus">Métriques Prometheus</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#connaissance-de-l-hote">Connaissance de l’hôte</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#watchdog">Watchdog</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#journaux">Journaux</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#inspection-de-la-base">Inspection de la base</a></li>
@ -399,6 +400,29 @@
durable sur <code class="docutils literal notranslate"><span class="pre">error</span></code> est l’alerte la plus utile à poser ; une valeur durable sur <code class="docutils literal notranslate"><span class="pre">creating</span></code>
ou <code class="docutils literal notranslate"><span class="pre">deleting</span></code> signale une opération qui n’aboutit pas.</p>
</section>
<section id="connaissance-de-l-hote">
<h2>Connaissance de l’hôte<a class="headerlink" href="#connaissance-de-l-hote" title="Lien vers cette rubrique">#</a></h2>
<p>Deux routes de l’API de l’agent, en lecture seule (voir <a class="reference internal" href="api-agent/reference.html"><span class="doc">Référence</span></a>) :</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">GET</span> <span class="pre">/register</span></code></dt><dd><p>ce qui ne change pas tant que l’hôte tourne : hostname, CPU (fabricant, modèle, sockets,
cœurs, threads), RAM totale, OS (<code class="docutils literal notranslate"><span class="pre">/etc/os-release</span></code>) et noyau. Lu une fois au démarrage de
l’agent ; si la lecture échoue, l’agent démarre quand même, journalise <code class="docutils literal notranslate"><span class="pre">host</span> <span class="pre">facts</span>
<span class="pre">unavailable</span></code> et la route répond 503 avec l’erreur.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">GET</span> <span class="pre">/ping</span></code></dt><dd><p>l’état courant : version de l’agent, démarrage de l’hôte (<code class="docutils literal notranslate"><span class="pre">boot_time</span></code>) et de l’agent
(<code class="docutils literal notranslate"><span class="pre">agent_start_time</span></code>), uptime de l’hôte et load sur 1, 5 et 15 minutes. Mesuré au démarrage
puis toutes les <code class="docutils literal notranslate"><span class="pre">times.host_state_interval</span></code> secondes (10 par défaut), gardé en mémoire ;
<code class="docutils literal notranslate"><span class="pre">collected_at</span></code> donne l’heure de la mesure. 503 tant qu’aucune mesure n’a réussi ; une mesure
en échec est journalisée (<code class="docutils literal notranslate"><span class="pre">host</span> <span class="pre">state</span> <span class="pre">collection</span> <span class="pre">failed</span></code>) et la précédente reste servie.</p>
</dd>
</dl>
<p>Les dates sont des timestamps Unix en secondes. Un <code class="docutils literal notranslate"><span class="pre">boot_time</span></code> qui change signale un
redémarrage de l’hôte, un <code class="docutils literal notranslate"><span class="pre">agent_start_time</span></code> seul un redémarrage de l’agent ;
<code class="docutils literal notranslate"><span class="pre">boot_time</span></code> + <code class="docutils literal notranslate"><span class="pre">uptime_seconds</span></code> donne l’horloge de l’hôte au moment de la mesure.</p>
<p>La version de l’agent est injectée au build : le tag pour une release, le commit court
(suffixé <code class="docutils literal notranslate"><span class="pre">-dirty</span></code> si l’arbre avait des modifications) pour les binaires de test du lab,
<code class="docutils literal notranslate"><span class="pre">undefined</span></code> sinon. Elle figure aussi dans la ligne <code class="docutils literal notranslate"><span class="pre">starting</span> <span class="pre">agent</span></code> du journal.</p>
</section>
<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
@ -420,8 +444,8 @@ numéro du VNI.</p>
<li><p><code class="docutils literal notranslate"><span class="pre">two-hostsvc</span></code> injoignable sur sa socket de contrôle : une notification, aucun VPC de
l’hyperviseur n’a plus de DNS ni de NTP ;</p></li>
<li><p>pour chaque VPC <code class="docutils literal notranslate"><span class="pre">running</span></code> : VPC absent de la liste servie par <code class="docutils literal notranslate"><span class="pre">two-hostsvc</span></code>,
<code class="docutils literal notranslate"><span class="pre">169.254.169.253</span></code> absente de la <code class="docutils literal notranslate"><span class="pre">dummy</span></code> <code class="docutils literal notranslate"><span class="pre">hostsvc</span></code>, ou chaîne <code class="docutils literal notranslate"><span class="pre">TWO-HOSTSVC</span></code> absente ou
incomplète dans son netns. Un VPC créé par une version antérieure à la 0.3.0 n’a rien de tout
<code class="docutils literal notranslate"><span class="pre">169.254.169.253</span></code> absente de la <code class="docutils literal notranslate"><span class="pre">dummy</span></code> <code class="docutils literal notranslate"><span class="pre">hostsvc</span></code>, ou chaîne <code class="docutils literal notranslate"><span class="pre">hostsvc</span></code> de la table
<code class="docutils literal notranslate"><span class="pre">ip</span> <span class="pre">two</span></code> absente ou incomplète dans son netns. Un VPC créé par une version antérieure à la 0.3.0 n’a rien de tout
cela : il est signalé à chaque tick jusqu’à sa recréation.</p></li>
</ul>
<p>Avec une section <code class="docutils literal notranslate"><span class="pre">bgp</span></code> dans la configuration, il contrôle aussi le plan de contrôle :</p>
@ -533,6 +557,7 @@ deux processus ne doivent pas ouvrir la même instance.</p>
<nav id="pst-page-toc-nav" class="page-toc" aria-labelledby="pst-page-navigation-heading-2">
<ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#metriques-prometheus">Métriques Prometheus</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#connaissance-de-l-hote">Connaissance de l’hôte</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#watchdog">Watchdog</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#journaux">Journaux</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#inspection-de-la-base">Inspection de la base</a></li>