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>