Set-OPS-Public/docs/supervision-conception.md

# Supervision dérivée des rôles

> **Pour qui :** celui qui ajoute un rôle à Set-OPS et se demande comment sa supervision
> arrive dans Icinga — et celui qui exploite et veut savoir d'où sortent les services
> qu'il voit.

> **La règle en une phrase.** Un rôle déclare les sondes de sa propre supervision ; le
> moteur en dérive les objets Icinga, la permission d'API et les preuves. Comme
> `meta/flux.yml` engendre nftables *et* OPNsense.

## Pourquoi

Le 2026-09-09, mesure du dépôt sur lui-même :

```
au 2026-09-09 :
  39 rôles déclarent leurs flux        -> nftables + OPNsense, dérivés
  32 déclarent leur empreinte          -> ressources des VM, dérivées
  32 déclarent leur authentification   -> habilitations, dérivées
  19 groupes déclarent `surveillance:` -> RIEN
```

Au 2026-09-09, les dix-neuf lignes `surveillance:` de `docs/dependances-groupes.yml` sont écrites,
versionnées, relues — et **aucune n'est exécutée**. Icinga surveillait deux choses :
`sauvegarde` et `sante`.

C'est la classe d'échec que ce dépôt nomme partout ailleurs, en version documentaire : la
carte dit ce qui est surveillé, et personne ne surveille. *Une intention écrite n'est pas
une mesure.*

## Le contrat d'une sonde : c'est celui des greffons Nagios

Une sonde est un **script local**, déposé par le rôle qui la possède, dans
`/usr/local/lib/setops/sondes/<nom>.sh` (0750, root).

| | |
|---|---|
| **sortie standard** | `TEXTE lisible` puis, optionnellement, `\| métriques` |
| **code de sortie** | `0` OK · `1` AVERTISSEMENT · `2` CRITIQUE · `3` INCONNU |
| **réseau** | aucun besoin : c'est le porteur qui pousse le résultat |
| **durée** | courte ; le porteur passe toutes les 15 min |

> **Ce contrat n'est pas de nous.** C'est l'**API des greffons Nagios**, que
> `monitoring-plugins` implémente depuis vingt ans et qu'Icinga parle nativement. La
> première rédaction de ce document la décrivait sans la nommer — autrement dit la
> réinventait. `positionnement.md` dit l'inverse : *adopter aux seuils, ne pas
> réimplémenter*.

**La conséquence pratique est grande.** Un greffon standard **est** une sonde valide, sans
la moindre colle : `check_disk`, `check_load`, `check_procs`, `check_ntp_time`,
`check_file_age`, `check_smtp`, `check_pgsql`… Le paquet en fournit **54**. Une sonde ne
s'écrit à la main que lorsque la vérité à mesurer est propre à Set-OPS — et c'était le cas
pour `client_pki/certificat`, qui compare l'empreinte *servie* à celle du disque : aucun
greffon ne sait ça.

Écrire du shell là où un greffon existe, c'est se donner du code à maintenir *et* se priver
de vingt ans de cas limites déjà rencontrés par d'autres.

Le rôle qui possède la sonde la **déploie lui-même** : il connaît ses chemins, ses
secrets, sa vérité de terrain. Il la **déclare** dans `meta/supervision.yml`, et c'est
cette déclaration que le moteur lit.

```yaml
# roles/<rôle>/meta/supervision.yml
sondes:
  - nom: certificat
    ttl: 5400
    raison: "..."
```

## Passif, et à durée de vie — jamais actif

Un contrôle **actif** ne voit pas la machine **muette** : si elle ne répond plus, la sonde
échoue et on met ça sur le compte du réseau. Ici c'est le nœud qui parle, et le `ttl` de
son envoi fait la fraîcheur — sans nouvelle, Icinga périme le service tout seul.

**Le silence alerte autant que l'échec.** C'est exactement ce qui a manqué à
`openipmi.service` : une unité en échec à chaque démarrage pendant une semaine, et
`systemctl --failed` à zéro partout parce qu'aucune machine n'avait redémarré.

C'est aussi ce qu'impose *la vérification suit la clé* : la sonde tourne là où vit la
vérité, pas sur le superviseur. Un dépôt de sauvegarde chiffré côté client ne peut être
jugé que par qui détient la clé.

## Ce qui n'a rien à faire ici

Une **métrique à seuil** — durée de collecte, volume de journaux, taux d'occupation —
appartient à Prometheus et Grafana. Icinga répond à une seule question : *est-ce cassé ?*
Mélanger les deux rendrait les deux moins lisibles.

## Chaque sonde vient avec son contrôle négatif

Une sonde qu'on n'a jamais vue échouer n'est pas une sonde, c'est une habitude. Dix-neuf
voyants verts non éprouvés seraient un recul par rapport à deux voyants prouvés : ils
rassureraient.

Toute sonde ajoutée doit donc être accompagnée de la manière de la faire échouer
**pour de vrai**, et cette manière doit être rejouée au moins une fois, sur une machine
réelle. Le CHANGELOG en porte la trace.

**Et contre un état sain, tout autant.** La première version de la sonde du certificat a
rendu **14 machines sur 14 en CRITIQUE** — sur une PKI qui se portait très bien. Elle
utilisait `openssl verify -CAfile racine`, alors que nos certificats sont signés par un
*intermédiaire* que seul `step certificate verify` sait retrouver. Une alarme toujours
allumée ne vaut pas mieux qu'une alarme jamais allumée : elle apprend à ne plus regarder.
Une sonde se prouve donc **deux fois** — verte sur le sain, rouge sur le cassé.

## Combien de sondes : une par CAUSE D'ACTION

Ni une par rôle, ni une par vérification. **Une par geste que le verdict appelle.**

Les quatorze premières sondes agrègent chacune de deux à six chemins d'échec, et ce choix
avait été fait **sans être écrit** — d'où cette section, ajoutée le 2026-09-10 après la
question : *« est-ce parce qu'elles agrègent plusieurs vérifications ? »*

**Ce que coûte une agrégation abusive**, dans le modèle d'Icinga : un service = **un état,
un historique, un acquittement**. Fondre deux causes qui appellent des gestes différents,
c'est ne plus pouvoir acquitter l'une pendant que l'autre alerte — et lire comme *un
service instable* ce qui est en réalité *deux faits distincts qui alternent*.

**Ce que coûte l'excès inverse** : un voyant de plus est un voyant de moins regardé. Le
dépôt le répète assez — *une supervision creuse est pire qu'aucune*.

Le test pratique, à appliquer sans état d'âme :

> Les deux échecs appellent-ils **le même geste, de la même personne, dans le même délai** ?
> Si oui, une seule sonde, et le message nomme lequel des deux a parlé.
> Si non, deux sondes.

**Exemple d'agrégation légitime** — `moteur` : `icinga2` mort, `icingadb` mort, état figé en
base. Trois causes, un seul geste : *va regarder la supervision*. Le message dit laquelle.

**Exemple d'agrégation abusive** — `cache-apt` : « ne répond pas » arrête tout `apt` de
l'écosystème, « volume à 90 % » est un billet pour demain. Même personne, gestes et
**délais** différents : deux sondes.

## Une sonde doit pouvoir être mise en défaut *par paramètre*

Corollaire des deux règles précédentes, et c'est ce qui rend la discipline tenable à
l'échelle : une sonde dont on ne peut prouver le rouge qu'en **cassant un service** ne sera
prouvée qu'une fois, puis plus jamais.

Chaque sonde expose donc sa cible et ses seuils en variables du rôle. On la met en défaut
en lui donnant un port fermé, un nom qui n'existe pas, un seuil impossible — sur une
machine réelle, sans rien abîmer, et aussi souvent qu'on veut.

## Où vit la sonde : là où vit la vérité, pas là où vit le symptôme

*« La vérification suit la clé. »* Un nœud sait qu'il a **lancé** sa sauvegarde ; seul le
dépôt sait qu'elle a **abouti**. Un nœud sait qu'il **expose** ses métriques ; seul
Prometheus sait qu'il les **collecte**.

D'où un choix qui peut surprendre : *« ce nœud est-il bien collecté ? »* est une sonde de
**`serveur_prometheus`**, pas de `client_metrique`. Une seule sonde y voit les N nœuds à la
fois — et surtout, elle voit le cas **silencieux** : celui qui a cessé d'être collecté et
qui, par définition, ne peut pas s'en plaindre lui-même.

## Un contrôle négatif ne doit pas pouvoir abîmer

Éprouver la sonde du certificat, le 2026-09-09, a consisté à **remplacer le certificat
d'hôte** par un auto-signé. La sonde a bien viré au rouge — et le script de synchronisation
a propagé ce certificat vers `node_exporter`, dont la clé était restée l'ancienne :

```
failed to load X509KeyPair: tls: private key does not match public key
```

Un service réel est tombé pour éprouver une sonde. Le contrôle avait un **rayon d'action**
que je ne lui avais pas donné volontairement.

La règle qui en découle : un contrôle négatif se fait sur une **copie**, ou sur un chemin
que la sonde accepte en paramètre — jamais en substituant l'artefact que d'autres
consomment. Quand c'est impossible, on le fait sur la machine la moins critique, on
l'annonce, et on vérifie l'état des consommateurs **après**, pas seulement celui de la
sonde.