Alertes

Le système d’alertes livre les alertes Prometheus dans des salons Matrix (et par e-mail pour les incidents). Un provisionnement unique du bot suffit : ensuite tout est déclaratif. Le fonctionnement d’ensemble est décrit dans Monitoring & Alertes.

Pré-requis

Pré-requis	Pourquoi
prometheus + monitoring sur le collecteur	porte Alertmanager et les règles
Service matrix joignable	héberge le bot et les salons
Accès ssh à l’hôte Matrix (nix)	crée le compte bot avec dnf-mas
Clé admin sops présente	écrit les secrets du bot

Installer le bot

Une seule commande, idempotente (rejouable sans risque) : elle crée le compte bot, les salons, et écrit l’identité dans var/generated/matrix.nix.

1. Déclarer les administrateurs (parties locales) dans la configuration :

   etc/config.yaml

   network:
     matrix:
       admins: ["alice", "bob"]

2. Lancer le provisionnement :

   just configure-alert-bot

   La commande, en s’appuyant sur la clé admin sops :

   • crée le compte @alertbot:domain.tld (dnf-mas manage register-user sur l’hôte Matrix) ;
   • crée ou résout les salons #alert-warnings et #alert-incidents, y fait entrer le bot et invite les admins ;
   • écrit bot + les ID de salons dans var/generated/matrix.nix ;
   • stocke mot de passe, jeton d’accès et secret de webhook dans sops.

   API admin non publique

   Si /_synapse/admin n’est pas exposé, le script ouvre automatiquement un tunnel SSH vers l’hôte Matrix (via l’utilisateur de déploiement nix).

   Filtre anti-bots de Caddy

   Le vhost Matrix rejette (403) un User-Agent de type curl. Le script envoie donc un agent neutre : ne pas reproduire les appels avec curl brut.

3. Déployer le collecteur :

   just generate
   just apply <collecteur>

   L’alerting s’active tout seul dès que les salons existent (var/generated/matrix.nix rempli). Pour le désactiver malgré tout : darkone.service.prometheus.alerting.enable = false;.

Changer le nom du bot

Le bot s’appelle alertbot par défaut. Pour un autre nom : ALERT_BOT=supervision just configure-alert-bot.

Secrets créés

Le provisionnement dépose trois secrets dans usr/secrets/secrets.yaml :

Clé sops	Rôle
alertmanager-matrix-password	mot de passe du compte bot (reconnexion)
alertmanager-matrix-token	jeton d’accès du bot (envoi des messages)
alertmanager-webhook-secret	authentifie Alertmanager auprès du pont Matrix

Envoyer un message dans un salon

Une fois le bot en place, n’importe quel outil du projet peut écrire dans les salons d’alerte. Le corps du message, en markdown, arrive sur l’entrée standard :

just send-msg warnings < rapport.md
echo "**Sauvegarde nocturne** : 2 dépôts en retard" | just send-msg incidents

La recette lit les salons dans var/generated/matrix.nix et le jeton dans sops, sous l’identité de déploiement nix. L’appelant n’a donc à connaître ni l’un ni l’autre.

Le markdown est converti en HTML avant l’envoi, sans quoi les clients Matrix l’afficheraient tel quel : titres, listes, gras, code et liens. Pas d’italique : un * isolé est un motif d’hôtes (gw-*).

Code de sortie	Signification
0	Message envoyé
10	Rien de configuré ici : salon, jeton ou programme manquant
11	Le serveur Matrix a refusé le message

Qui s’en sert

fleet-update --send-report envoie son rapport par cette recette (voir Déploiement). Le code 10 lui suffit pour savoir qu’insister est inutile.

Tester une alerte

1. Sur un nœud supervisé, couper un service surveillé :

   sudo systemctl stop <unité>

2. Sous une minute, un message ServiceDown (ou SystemdUnitFailed) apparaît dans #alert-warnings, #alert-incidents et un e-mail si le nœud est critique. Le lien de l’alerte pointe vers https://prometheus.<zone>.domain.tld.

3. Relancer le service : l’alerte se résout (notification de résolution). Pour SystemdUnitFailed, la résolution n’arrive qu’après 30 minutes sans échec (pourquoi).

   sudo systemctl start <unité>

Silencer pendant un rebuild

Le flux de déploiement pose un drapeau de maintenance pour ne pas déclencher de fausses alertes pendant un nixos-rebuild. Manuellement :

dnf-maintenance on    # inhibe les alertes du nœud
dnf-maintenance off   # les réactive

Silencer une alerte connue

Certaines alertes sont exactes mais non actionnables : un disque de sauvegarde volontairement rempli franchit DiskSpaceLow en permanence. silences les empêche de notifier.

usr/modules/alerts.nix

{
  darkone.service.prometheus.alerting.silences = [
    {
      alert = "DiskSpaceLow";
      host = "srv-backup";
      matchers.device = "/dev/sdb";
      reason = ''
        Disque de sauvegarde volontairement rempli, seuil structurellement
        franchi. Retirer si la rétention est réduite.
      '';
    }
  ];
}

Champ	Rôle
alert	Nom de l’alerte à taire (alertname)
host	Nom d’hôte à cibler (label host), null pour tout le parc
matchers	Labels supplémentaires en égalité stricte, combinés en ET
reason	Obligatoire : pourquoi l’alerte est acceptée

Chaque entrée devient une route Alertmanager vers le receiver null. L’alerte continue de se déclencher et reste visible dans Prometheus, Alertmanager et Grafana, elle cesse simplement de notifier.

Un silence est chirurgical, pas global

Seul l’alertname cité est concerné : taire DiskSpaceLow sur une partition laisse DiskSpaceCritical et DiskWillFillSoon pleinement armés sur cette même partition. Le vrai remplissage alerte toujours.

Viser une partition, pas un point de montage

Les règles disque alertent une fois par partition, quel que soit le nombre de points de montage qu’elle porte (sous-volumes btrfs /, /nix, /home, /.swapfile : une seule alerte). Ces alertes n’ont donc pas de label mountpoint : un matchers.mountpoint ne matcherait jamais. Cibler matchers.device, lu dans la description de l’alerte ou avec df -h.

Où déclarer ces silences

Les règles et routes d’une zone sont générées sur l’hôte qui fait tourner Prometheus, pas sur la machine concernée. Chaque hôte étant évalué indépendamment, usr/machines/<hôte>/ n’y suffit pas. Un module consumer (usr/modules/alerts.nix) est importé partout et regroupe en un seul fichier ce qui est volontairement ignoré, toutes zones confondues.

Vérifier le routage sur l’hôte Prometheus :

amtool config routes test --config.file=/etc/alertmanager.yml \
  alertname=DiskSpaceLow host=srv-backup device=/dev/sdb

Pour taire un mode de défaillance systémique plutôt qu’un cas ponctuel, voir ignoredUnits (dnf/config/alerts.nix), qui exclut une unité systemd de SystemdUnitFailed sur tout le parc.

Dépannage

Symptôme	Cause probable	Remède
Aucun message dans un salon	bot absent du salon ou jeton expiré	rejouer just configure-alert-bot
Création de salon en 403	filtre anti-bots de Caddy	déjà géré (agent neutre) ; ne pas utiliser curl brut
admin API not public	/_synapse/admin fermé	laisser le tunnel SSH automatique opérer (hôte Matrix joignable)
Lien d’alerte non résolu	DNS ou certificat du vhost prometheus absent	déployer la passerelle / le HCS pour le nouveau sous-domaine
matrix.nix ignoré au déploiement	fichier non lisible par nix	le script fait un chmod 644 ; vérifier les permissions de var/generated/
Pas de mail d’incident	relais Postfix local inactif	l’alerting l’active par défaut ; vérifier darkone.service.prometheus.alerting.email