Canaux de notification

Bêta

Fonctionnalité en cours de déploiement. L'interface décrite ici est celle de la prochaine livraison : elle peut encore évoluer, et n'est pas forcément activée sur votre tenant.

La supervision est en cours de déploiement ; les canaux e-mail ne sont pas encore disponibles.

Un canal de notification est une destination d'alertes : un webhook, Slack, Discord, Microsoft Teams ou une adresse e-mail. Vous le déclarez une fois, puis chaque moniteur dit quels canaux prévenir quand il tombe et quand il revient.

Prérequis

• Une session de tenant (sng tenant use acme) et le droit deploy:write.
• Un moniteur, ou l'intention d'en créer un.
• L'URL de webhook entrant fournie par votre outil (Slack, Discord, Teams) ou par votre service.

1. Déclarer un canal webhook

infra/NotificationChannel/ops.yml

apiVersion: monitoring.stackngo.io/v1alpha1
kind: NotificationChannel
metadata:
  name: ops
spec:
  type: Webhook
  webhook:
    url: https://hooks.example.com/uptime    # https obligatoire
  sendResolved: true                         # prévient aussi du retour à la normale (défaut)
  repeatInterval: 4h                         # rappel tant que l'incident dure (défaut)

sng apply infra/NotificationChannel/ops.yml

Il n'y a pas de commande sng dédiée aux canaux : partez du gabarit sng template gen NotificationChannel ops > ops.yml, puis sng apply.

2. Relier un moniteur au canal

sng monitor create api --http https://api.example.com/health --interval 5m --channel ops

ou, dans le manifeste du moniteur :

spec:
  notificationChannelRefs:
    - name: ops          # 10 canaux au plus par moniteur

Un moniteur qui référence un canal inexistant ou refusé reste sondé : seule son alerte attend (Ready=False, WaitingForChannel) et part dès que le canal existe, sans nouvelle action.

3. Les types de canaux

type	Bloc	Destination
Webhook	webhook	url: https://… ou urlSecretRef
Discord	discord	url ou urlSecretRef (URL de webhook Discord)
MSTeams	msteams	url ou urlSecretRef (URL de webhook entrant Teams)
Slack	slack	webhookSecretRef obligatoire (l'URL Slack est un secret), channel optionnel (#ops)
Email	email	to: [ops@example.com] (10 adresses au plus) — pas encore disponible

Le bloc doit correspondre au type : type: Slack exige slack et interdit les autres.

infra/NotificationChannel/discord.yml

apiVersion: monitoring.stackngo.io/v1alpha1
kind: NotificationChannel
metadata:
  name: discord
spec:
  type: Discord
  discord:
    url: https://discord.com/api/webhooks/123/abc

4. Garder l'URL hors du manifeste

Une URL de webhook donne le droit de poster dans votre canal : traitez-la comme un secret. urlSecretRef (et webhookSecretRef pour Slack) désigne un secret du tenant et la clé qui contient l'URL. Ce secret doit être déclaré avec materialize: true, qui le rend utilisable par vos canaux de notification (voir Déclarer un secret par manifeste) :

infra/SSMSecret/slack-webhook.yml

apiVersion: ssm.stackngo.io/v1alpha1
kind: SSMSecret
metadata:
  name: slack-webhook
spec:
  length: 0          # vous posez la valeur vous-même
  materialize: true  # utilisable par le canal de notification

sng apply infra/SSMSecret/slack-webhook.yml
printf '%s' 'https://hooks.slack.com/services/T000/B000/XXXX' > /tmp/slack-url
sng secret set slack-webhook --from-file /tmp/slack-url
rm /tmp/slack-url

infra/NotificationChannel/slack.yml

apiVersion: monitoring.stackngo.io/v1alpha1
kind: NotificationChannel
metadata:
  name: slack
spec:
  type: Slack
  slack:
    webhookSecretRef: { name: slack-webhook, key: value }
    channel: "#ops"

Si le secret est introuvable, n'a pas la clé indiquée ou ne contient pas une URL https://, seul ce canal est écarté : il passe Accepted=False avec la raison SecretNotFound (ou Invalid pour une URL qui n'est pas en https://), et vos autres canaux continuent d'envoyer leurs alertes. Le canal reprend tout seul dès que le secret est corrigé.

Comptez jusqu'à 15 minutes entre le sng secret set et la prise en compte de l'URL par le canal ; un changement ultérieur de la valeur, rotation comprise, est pris en compte dans le même délai.

5. Ce que vous recevez

Alerte	Quand	Gravité
MonitorDown — « <moniteur> est indisponible »	le moniteur passe Down	critical
TLSCertificateExpiring	le certificat expire dans moins de tls.expiryWarningDays jours (14 par défaut), pendant 10 min	warning
TLSCertificateExpiryCritical	moins de tls.expiryCriticalDays jours (3 par défaut)	critical
Retour à la normale	l'alerte cesse, si sendResolved: true	—

Les alertes d'un même moniteur sont regroupées : la première part après 30 secondes, et un rappel est envoyé toutes les repeatInterval (4 h par défaut) tant que l'incident dure. Les alertes TLS ne concernent que les moniteurs avec tls (HTTPS, ou TCP avec tcp.tls: true).

Le message suit le format de chaque outil (Slack, Discord, Teams). Pour un Webhook, le corps est un JSON ("version": "4", liste alerts, chaque alerte avec status, labels et annotations) ; le nom du moniteur est dans le label sng_monitor.

Vérification

Créez un moniteur de test sur une adresse qui ne répond pas, relié au canal, avec --threshold 1 et l'intervalle minimal de votre tier :

sng monitor create test-alerte --http https://does-not-exist.example.com/ --interval 5m --threshold 1 --channel ops

Vous devez recevoir MonitorDown dans les minutes qui suivent. Pour vérifier aussi la notification de retour, relancez la commande avec une URL qui répond (--http https://example.com/) et attendez le message de résolution. Supprimez ensuite le moniteur : sng monitor delete test-alerte --yes. Supprimer ou suspendre un moniteur en panne n'envoie pas forcément de notification de retour : il n'est plus rattaché au canal.

Pour aller plus loin

• Nombre de canaux : borné par le tier (2 en 3XS, 5 en 2XS, 10 en XS…). Au-delà, les canaux les plus récents sont refusés (QuotaExceeded), ainsi que les moniteurs qui les référencent.
• Un canal sans moniteur n'envoie rien.
• Format de repeatInterval : un entier suivi de m ou h (30m, 4h, 24h).
• Fenêtres de maintenance : pas encore actives ; voir Page de statut.

Erreurs fréquentes

Symptôme	Cause	Correction
sng apply refuse : slack : requis pour le type Slack, interdit sinon	Bloc absent ou bloc d'un autre type	Un seul bloc, celui du type
sng apply refuse : url ou urlSecretRef : exactement un des deux	Les deux donnés, ou aucun	En garder un
sng apply refuse : url : https:// requis	URL en http://	URL https://
Canal e-mail sans effet, moniteurs qui le référencent refusés	Les canaux e-mail ne sont pas encore disponibles (NotSupported)	Utiliser un webhook en attendant
Canal Accepted=False, SecretNotFound ; les autres canaux fonctionnent	Secret de urlSecretRef / webhookSecretRef introuvable, clé absente, ou secret déclaré sans materialize: true	Déclarer le secret avec materialize: true (section 4) ; vérifier la clé avec sng secret describe
Canal Accepted=False, Invalid	La valeur du secret ne commence pas par https://	Corriger la valeur avec sng secret set
Moniteur en WaitingForChannel (sondé, sans alerte)	Nom de canal mal orthographié, ou canal refusé (quota, e-mail)	Corriger le nom ; vérifier le canal

Voir aussi

• Moniteurs d'uptime
• Page de statut
• Créer et lire un secret
• Référence : NotificationChannel et Monitor