Ce que fait ce module #

Une instance a beaucoup de choses à raconter : fail2ban a banni une IP, aide a vu changer un fichier système, la sauvegarde de la nuit a échoué, le disque racine est à 95 %. Si chaque module prévient à sa façon —un e-mail ici, une ligne de log là— personne n'apprend rien, et avec dix instances le problème est multiplié par dix.

Le module global-alerts est le bus central d'alertes d'imaxe : une seule commande par laquelle passent tous ces avis et une seule destination où ils arrivent, un topic Amazon SNS partagé par toute ta flotte. De là, SNS distribue comme tu veux : e-mail, SMS, une fonction Lambda, une file SQS, ton système d'astreinte. Il publie avec le rôle IAM de l'instance (permission sns:Publish), donc il n'y a aucune identification à stocker. Et il filtre le bruit avant d'envoyer : un seuil de sévérité écarte ce qui n'atteint pas le niveau qui t'intéresse et une fenêtre de déduplication évite que la même alerte te réveille quarante fois.

Si SNS n'est pas disponible —réseau coupé, rôle sans permissions encore, région inaccessible— l'alerte n'est pas perdue : elle est mise en file sur disque et un timer systemd la réessaie toutes les 5 minutes.

Avant de commencer

Il te faut l'ARN d'un topic SNS (arn:aws:sns:région:compte:topic) et que l'instance puisse y publier. Si tu as lancé l'AMI depuis le lanceur, le modèle CloudFormation crée déjà le topic, abonne ton e-mail, crée le rôle IAM avec sns:Publish et passe l'ARN à l'instance sous forme de tag : le module se configure tout seul et il n'y a rien à faire ici.

Démarrage rapidetâches pas à pas

Tâches courantes #

Choisis ce que tu veux faire. Chaque recette apporte la commande déjà écrite — remplace l'ARN et le texte par les tiens, et clique sur Copier.

Définir le topic SNS Envoyer une alerte de test Envoyer une alerte depuis un script Voir l'état du bus Baisser le bruit Voir la file et réessayer Rendre le module muet

1

Définir le topic SNS

Dis à l'instance où elle doit publier ses avis.

Connecte-toi en SSH à ton serveur avec l'utilisateur ubuntu.

Pointe le module vers l'ARN de ton topic. La région se déduit de l'ARN lui-même, donc normalement il n'est pas nécessaire de l'indiquer :

terminal

$ sudo imaxe global-alerts configure \
    --topic-arn arn:aws:sns:eu-west-1:123456789012:imaxe-alerts

Plusieurs instances publient dans le même topic ? Donne à chacune une étiquette d'origine reconnaissable avec --source (par défaut le hostname est utilisé) :

terminal

$ sudo imaxe global-alerts configure --source web-production-1

La configuration reste dans /etc/imaxe/global-alerts.yml et l'envoi est activé. Continue avec la recette Envoyer une alerte de test.

2

Envoyer une alerte de test

Vérifie que le rôle IAM publie vraiment avant de faire confiance au canal.

Publie une alerte de test dans le topic configuré :

terminal

$ sudo imaxe global-alerts test

Le test saute le seuil et la déduplication —il part toujours— et, si quelque chose échoue, il te rend l'erreur réelle d'AWS au lieu de mettre en file en silence. Vérifie la boîte de l'adresse abonnée au topic (et le dossier spam).

Si tu vois le MessageId et que l'avis arrive, le canal fonctionne. Si tu obtiens AuthorizationError, il manque à l'instance la permission sns:Publish sur ce topic.

3

Envoyer une alerte depuis un script

Le même canal que les modules, disponible pour ce qui est à toi.

Une alerte avec sa sévérité et son origine :

terminal

$ sudo imaxe global-alerts send --severity critical \
    --source backup --subject "sauvegarde échouée" \
    "la sauvegarde nocturne de la base de données s'est terminée en erreur"

Si le texte est produit par une autre commande, passe-le par stdin en utilisant - comme message :

terminal

$ df -h / | sudo imaxe global-alerts send --severity warning -

Dans quelque chose qui s'exécute toutes les quelques minutes, donne-lui une clé de déduplication stable : dans la fenêtre configurée, seule la première partira :

terminal

$ sudo imaxe global-alerts send --severity warning \
    --dedup-key disque-racine-plein "disque racine à 95%"

L'alerte voyage en JSON vers le topic, avec l'instance, la région et l'horodatage déjà inclus. Sans --dedup-key, le module en dérive une à partir de l'origine + la sévérité + le sujet.

4

Voir l'état du bus

Topic, région, CLI d'AWS et alertes en attente, d'un coup d'œil.

Résumé de l'état actuel :

terminal

$ sudo imaxe global-alerts status

Pour vérifier quelle configuration commande réellement —y compris celle qui arrive par les tags de l'instance, qui ont priorité sur le fichier— :

terminal

$ sudo imaxe global-alerts show
$ sudo imaxe global-alerts status --json

Tu sauras s'il y a un topic configuré, dans quelle région on publie et combien d'alertes attendent dans la file. Avec --json, prêt pour un tableau de bord ou un script.

5

Baisser le bruit

Monte le seuil de sévérité et élargis la fenêtre de déduplication.

Si tu veux seulement être au courant de ce qui compte, écarte tout ce qui est en dessous de warning :

terminal

$ sudo imaxe global-alerts configure --min-severity warning

La fenêtre de déduplication n'a pas de flag : elle se règle dans le fichier de configuration. Monte-la si une même alerte se répète beaucoup :

/etc/imaxe/global-alerts.yml

dedup_window: 1h   # 30s, 5m, 1h… (5m par défaut)

Les alertes sous le seuil sont écartées avant de partir (elles ne sont pas mises en file) et les répétitions dans la fenêtre sont supprimées. test publie toujours, donc tu ne perds pas le moyen de vérifier le canal.

6

Voir la file et réessayer

Ce qui est resté en attente quand SNS n'a pas répondu, et comment forcer l'envoi.

Regarde ce qui est en attente et les dernières clés envoyées :

terminal

$ sudo imaxe global-alerts history

Le réessai est déjà fait par un timer systemd toutes les 5 minutes, mais tu peux le forcer après avoir corrigé la permission ou le réseau :

terminal

$ sudo imaxe global-alerts flush
$ systemctl status imaxe-global-alerts-flush.timer

Tu verras combien sont parties et combien attendent encore. Si la première échoue à nouveau, la passe s'arrête là et laisse le reste pour la tentative suivante : rien n'est jeté.

7

Rendre le module muet

Arrête de publier sans perdre la configuration.

Désactive l'envoi d'alertes et retire le timer de réessai :

terminal

$ sudo imaxe global-alerts remove

Le topic, la région et le reste des réglages sont conservés dans le fichier : pour le réactiver, un configure suffit, il réhabilite le module.

L'instance cesse de publier. Les send suivants n'échouent pas : ils préviennent par stderr que le module est désactivé et terminent avec le code 0.

Sans rôle IAM, pas d'alertes

Le module publie avec les identifiants du rôle de l'instance, pas avec des clés stockées. Si le rôle ne permet pas sns:Publish sur ce topic, les alertes s'accumuleront en file les unes après les autres sans jamais arriver. Un imaxe global-alerts test te le dit sur le moment, avec l'erreur telle qu'AWS la renvoie.

Référence CLIcommandes, flags et fichiers

Synopsis #

usage

imaxe global-alerts <sous-commande> [--topic-arn ARN] [--severity NIVEAU] [flags]

Toutes les sous-commandes exigent les privilèges root (utilise sudo) parce qu'elles écrivent dans /etc/imaxe/, gardent l'état dans /var/lib/imaxe/ et gèrent une unité systemd. Il n'y a pas de secrets à manipuler : la publication passe par le rôle IAM de l'instance. Ajoute --json à status, show, history ou flush pour obtenir une sortie lisible par une machine.

Sous-commandes #

Sous-commande	Ce qu'elle fait	Flags pertinents
status	État : topic configuré, région effective, CLI d'AWS disponible et alertes en file.	--json
configure	Fixe le topic SNS et les options d'envoi. Réhabilite le module s'il était désactivé.	--topic-arn, --region, --source, --min-severity
send	Publie une alerte. C'est le canal qu'utilisent l'opérateur et les autres modules.	--severity, --source, --subject, --dedup-key
test	Publie une alerte de test en sautant seuil et déduplication, et rapporte l'erreur réelle en cas d'échec.	--severity
show	Montre la configuration effective (fichier + tags de l'instance déjà appliqués).	--json
history	Alertes en attente dans la file et clés de déduplication envoyées récemment.	--json
flush	Réessaie les alertes mises en file. Le timer systemd l'exécute aussi.	--json
remove	Désactive l'envoi et retire le timer. Conserve la configuration.	—

Arguments et flags #

Flag	Type	Par défaut	Description
--topic-arn req.	string	—	ARN du topic SNS de destination (`arn:aws:sns:région:compte:topic`). Sans lui, le module ne peut pas publier.
--region	string	de l'ARN	Région AWS. Si elle est omise, elle est dérivée de l'ARN du topic ; sinon, d'IMDS ou de `AWS_REGION`.
--source	string	hostname	Étiquette d'origine. Dans `configure`, celle de l'instance ; dans `send`, celle de cette alerte précise (p. ex. le module qui l'émet).
--min-severity	string	info	Seuil : écarte les alertes en dessous de ce niveau. Valeurs : `info`, `warning`, `critical`.
--severity	string	info	Dans `send`/`test` : niveau de cette alerte. Les formes courtes `warn` et `crit` sont acceptées.
--subject	string	du message	Sujet court. S'il est omis, il est dérivé du message lui-même.
--dedup-key	string	dérivée	Clé de déduplication : supprime les répétitions dans `dedup_window`. Par défaut elle est calculée avec origine + sévérité + sujet.
<message> req.	positionnel	—	Dans `send` : le texte de l'alerte, ou `-` pour le lire depuis `stdin`.
--json	bool	false	Dans `status`, `show`, `history` et `flush`, émet le résultat en JSON sur `stdout`.

Écarter n'est pas échouer

Quand une alerte est écartée —module désactivé, sévérité sous le seuil ou doublon dans la fenêtre— send l'explique par stderr et termine avec le code 0. Ainsi le script qui l'a émise ne casse pas à cause d'un filtre que tu as toi-même configuré.

Configuration par tags d'instance #

Chaque déploiement doit pointer vers son topic, et reconstruire l'AMI pour ça n'aurait pas de sens. C'est pourquoi le module lit, en plus du fichier, les tags de l'instance préfixés par imaxe.global-alerts. via IMDSv2 : s'ils existent, ils l'emportent sur le YAML. C'est ce que fait le modèle CloudFormation du lanceur, qui exige en plus MetadataOptions.InstanceMetadataTags: enabled pour qu'ils puissent être lus.

Tag	Équivaut à	Valeurs
imaxe.global-alerts.topic_arn	topic_arn	ARN du topic SNS de destination.
imaxe.global-alerts.region	region	Région AWS ; vide = dérivée de l'ARN ou d'IMDS.
imaxe.global-alerts.source	source	Étiquette d'origine ; vide = hostname.
imaxe.global-alerts.min_severity	min_severity	`info` · `warning` · `critical`
imaxe.global-alerts.dedup_window	dedup_window	Durée : `30s`, `5m`, `1h`…
imaxe.global-alerts.enabled	enabled	`true`/`false` (aussi `1`/`0`, `yes`/`no`, `on`/`off`).

Hors d'AWS, ou avec IMDS bloqué, la lecture échoue en millisecondes et le module continue avec ce que dit le fichier. Pour voir ce qui est réellement actif, imaxe global-alerts show.

Fichiers et chemins #

Chemin	Contenu
/etc/imaxe/global-alerts.yml	Configuration du module : topic, région, origine, seuil et fenêtre de déduplication.
/var/lib/imaxe/state/global-alerts/spool/	File des alertes en attente, une par fichier `.json`, par ordre chronologique.
/var/lib/imaxe/state/global-alerts/sent.json	Registre des clés de déduplication avec l'heure du dernier envoi.
/etc/systemd/system/imaxe-global-alerts-flush.timer	Timer de réessai : démarre 2 min après le boot et se répète toutes les 5 min.

Exemple de global-alerts.yml :

/etc/imaxe/global-alerts.yml

enabled: true
topic_arn: arn:aws:sns:eu-west-1:123456789012:imaxe-alerts
region: ""            # vide = dérivée de l'ARN ou d'IMDS
source: ""            # vide = hostname de l'instance
min_severity: info
dedup_window: 5m

L'état (file et registre de déduplication) vit dans /var/lib/imaxe/ et non dans /etc/ à dessein : c'est de l'état, pas de la configuration. Les deux chemins peuvent être déplacés avec les variables d'environnement IMAXE_CONFIG_DIR et IMAXE_STATE_DIR.

Format de l'alerte #

Le corps du message SNS est du JSON versionné (schema: 1), pour que l'abonné puisse le traiter avec une Lambda ou une file en plus de le lire par e-mail :

corps du message

{
  "schema": 1,
  "severity": "critical",
  "source": "backup",
  "subject": "sauvegarde échouée",
  "message": "la sauvegarde nocturne de la base de données s'est terminée en erreur",
  "host": "web-production-1",
  "instance_id": "i-0abc123def4567890",
  "region": "eu-west-1",
  "ts": "2026-07-25T03:14:07Z",
  "dedup_key": "9f2c1b7e44a0d513"
}

Le sujet du message SNS est composé comme [imaxe][sévérité] host: sujet, assaini en ASCII imprimable et coupé à 100 caractères, qui est la limite qu'impose SNS.

Codes de sortie et logs #

Chaque exécution renvoie un code que tu peux vérifier avec echo $? — utile pour enchaîner dans des scripts :

0OKOpération terminée. Aussi quand l'alerte est écartée ou mise en file volontairement.

1ERRErreur générique : le test n'a pas pu être publié, ou il n'a pu ni être publié ni mis en file.

2USAGEArguments invalides : flag inconnu, message manquant ou sévérité non valide.

64NO TOPICAucun topic SNS configuré, ni par fichier ni par tag.

Le module répond aussi au contrôle de santé d'imaxe : s'il est activé mais sans topic, le health échoue, de sorte qu'un imaxe health le trahit avant que la première alerte soit nécessaire.

terminal

$ sudo imaxe global-alerts test; echo "sortie : $?"
$ journalctl -u imaxe-global-alerts-flush.service -n 50

Dépannage #

Symptôme	Cause probable	Solution
Tu obtiens NO TOPIC (code 64)	Ni le fichier ni les tags n'apportent d'ARN de topic.	Lance `configure --topic-arn …`, ou vérifie que l'instance a le tag `imaxe.global-alerts.topic_arn` et les tags activés dans les métadonnées.
« SNS indisponible ; alerte mise en file » encore et encore	Il manque au rôle de l'instance `sns:Publish` sur ce topic, ou l'ARN est d'un autre compte ou d'une autre région.	Lance `test` pour voir l'erreur exacte d'AWS, corrige la politique du rôle puis `flush`.
« CLI aws disponible : false » dans le status	L'instance n'a pas le CLI d'AWS installé ; le module publie à travers lui.	Installe le CLI d'AWS. Les AMI d'imaxe l'apportent d'origine ; sur ton propre hôte il faut l'ajouter.
Tu configures quelque chose et show continue d'afficher une autre valeur	Un tag `imaxe.global-alerts.*` écrase le fichier : il a la priorité par conception.	Change le tag de l'instance (ou le paramètre de la pile CloudFormation) au lieu du YAML.
Seule la première de plusieurs alertes identiques arrive	La fenêtre de déduplication les supprime.	C'est le comportement attendu. Baisse `dedup_window`, ou utilise des `--dedup-key` différentes si ce sont vraiment des événements distincts.
Rien n'arrive et il n'y a pas d'erreurs	Le module est désactivé, ou la sévérité est sous `min_severity`.	`show` te montre `enabled` et le seuil ; `configure` réhabilite l'envoi.
Les alertes sont publiées mais ne t'arrivent pas par e-mail	L'abonnement au topic SNS n'est pas confirmé.	Cherche l'e-mail de confirmation d'AWS (vérifie le spam) et accepte l'abonnement dans la console SNS.

Bloqué sur le module Alertes ?

Écrivez-nous avec la sortie de « imaxe <module> status --json » et nous vous répondons rapidement.

Contacter le support

Un seul endroit pour écouter toute ta flotte

Ce que fait ce module #

Tâches courantes #

Définir le topic SNS

Envoyer une alerte de test

Envoyer une alerte depuis un script

Voir l'état du bus

Baisser le bruit

Voir la file et réessayer

Rendre le module muet

Synopsis #

Sous-commandes #

Arguments et flags #

Configuration par tags d'instance #

Fichiers et chemins #

Format de l'alerte #

Codes de sortie et logs #

Dépannage #

Bloqué sur le module Alertes ?