Notifications ArgoCD : alerter sur Slack, Teams ou webhook

Une synchronisation échoue à 3 h du matin et personne ne le sait avant l'ouverture. Les notifications ArgoCD ferment ce trou : elles préviennent sur Slack, Teams, e-mail ou webhook au moment précis où un événement se produit. Ce guide configure une notification de bout en bout (service, template, trigger, abonnement) avec des sorties réelles capturées sur un cluster k3d (ArgoCD v3.4.5). Public : personnes qui exploitent ArgoCD. Prérequis : ArgoCD installé et une Application déployée.

Ce que vous allez apprendre

• Comprendre les quatre briques : service, template, trigger, abonnement
• Configurer un service de notification (Slack, webhook)
• Écrire un template et un trigger corrects (et éviter le piège d'échappement)
• Abonner une Application à un trigger
• Vérifier qu'une notification part réellement

Le moteur de notifications

Depuis ArgoCD 2.x, le moteur de notifications est intégré à l'installation : un pod argocd-notifications-controller tourne dans le namespace argocd (image quay.io/argoproj/argocd:v3.4.5, la même que le reste). Rien à installer à part. Il lit sa configuration dans deux objets :

• argocd-notifications-cm (ConfigMap) : services, templates, triggers.
• argocd-notifications-secret (Secret) : les jetons et identifiants (token Slack, mot de passe SMTP).

Le fonctionnement repose sur quatre briques qui s'enchaînent :

Brique	Rôle	Où
Service	Comment envoyer (Slack, Teams, webhook, e-mail)	service.<type>.<nom>
Template	Quoi envoyer (le message)	template.<nom>
Trigger	Quand envoyer (la condition)	trigger.<nom>
Abonnement	Qui reçoit (quelle Application, quel canal)	annotation sur l'Application

Glissez pour voir

Configurer un service

Le service décrit le canal. Voici un service webhook générique, puis l'exemple Slack qui est le plus courant en équipe.

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
  namespace: argocd
data:
  service.webhook.echo: |
    url: http://mon-recepteur.default.svc.cluster.local:8080/
    headers:
    - name: Content-Type
      value: application/json
  service.slack: |
    token: $slack-token   # référence une clé du Secret argocd-notifications-secret

Le $slack-token ne contient pas le jeton en clair : il pointe vers une clé du Secret. On y met le vrai token :

kubectl -n argocd patch secret argocd-notifications-secret \
  --type merge -p '{"stringData":{"slack-token":"xoxb-votre-token"}}'

Jamais de secret dans la ConfigMap

La ConfigMap est lisible par tout le monde qui a accès au namespace. Le token, le mot de passe SMTP ou l'URL de webhook privée vont dans le Secret (argocd-notifications-secret), référencés par $nom-de-cle depuis la ConfigMap. C'est la séparation config/secret de base.

Écrire un template (et éviter le piège d'échappement)

Le template définit le corps du message. Pour un webhook JSON, le body doit être du JSON valide, écrit tel quel :

  template.app-synced: |
    webhook:
      echo:
        method: POST
        body: |
          {"texte": "Application {{.app.metadata.name}} synchronisee, revision {{.app.status.sync.revision}}, statut {{.app.status.sync.status}}"}

Le piège classique : les guillemets sur-échappés

Un réflexe fréquent est d'échapper les guillemets du JSON avec des backslashes ({\"texte\": ...}) parce qu'on édite la ConfigMap depuis un kubectl patch en ligne de commande. Le contrôleur reçoit alors des backslashes littéraux et échoue au parsing avec une erreur du type unrecognized character U+005C. La bonne pratique : éditer la config dans un fichier YAML (kubectl apply -f), où le JSON s'écrit sans échappement. Le shell est le coupable, pas ArgoCD.

Les variables {{.app.*}} viennent de l'objet Application : metadata.name, status.sync.revision, status.sync.status, status.health.status, etc.

Écrire un trigger

Le trigger associe une condition à un ou plusieurs templates. La condition est une expression évaluée sur l'Application :

  trigger.on-sync-ok: |
    - when: app.status.operationState.phase in ['Succeeded']
      send: [app-synced]

La condition attend une liste avec des chaînes quotées

La syntaxe correcte est in ['Succeeded'] : une liste, avec la valeur entre guillemets simples. Écrire in [Succeeded] (sans quotes) fonctionne parfois mais reste fragile ; toujours quoter les chaînes. Les phases utiles : Succeeded, Failed, Error, Running.

ArgoCD fournit aussi des triggers prêts à l'emploi qu'il suffit d'activer : on-sync-succeeded, on-sync-failed, on-health-degraded, on-sync-running. En production, on-sync-failed et on-health-degraded sont les deux à brancher en priorité.

Abonner une Application

Un trigger ne fait rien tant qu'une Application ne s'y abonne pas. L'abonnement est une annotation sur l'Application, de la forme notifications.argoproj.io/subscribe.<trigger>.<service> :

kubectl -n argocd annotate app guestbook \
  notifications.argoproj.io/subscribe.on-sync-ok.echo=""

Pour Slack, on met le nom du canal en valeur :

kubectl -n argocd annotate app guestbook \
  notifications.argoproj.io/subscribe.on-sync-failed.slack="equipe-ops"

Vérifier qu'une notification part

C'est l'étape qu'on oublie et qui fait perdre des heures. Après avoir configuré et abonné, on déclenche l'événement (une synchro) et on lit les logs du contrôleur. Voici la sortie réelle sur le cluster, une fois la config correcte :

Start processing                                        resource=argocd/guestbook
Trigger 'on-sync-ok' TRIGGERED | templates: [app-synced]   resource=argocd/guestbook
Sending notification about condition 'on-sync-ok.[0]...' to '{echo}'
  using the configuration in namespace argocd            resource=argocd/guestbook

Ces trois lignes prouvent que la chaîne complète fonctionne : la condition est évaluée (TRIGGERED), le template est résolu ([app-synced]) et l'envoi part vers le service (to '{echo}'). Si le service distant est injoignable, une ligne d'erreur suit (request failed: ... connection timed out) : le trigger est bon, c'est le réseau ou l'URL qu'il faut corriger.

kubectl -n argocd logs deploy/argocd-notifications-controller --tail=20

Dépannage

Symptôme	Cause probable	Solution
unrecognized character U+005C	Guillemets sur-échappés dans le template	Éditer la config dans un fichier YAML (apply -f), JSON sans backslashes
Trigger jamais déclenché	Application non abonnée	Ajouter l'annotation notifications.argoproj.io/subscribe.<trigger>.<service>
TRIGGERED mais rien reçu	Service distant injoignable	Vérifier l'URL / le token / le réseau (connection timed out dans les logs)
Token Slack refusé	Secret mal référencé	Vérifier $slack-token dans la CM et la clé dans argocd-notifications-secret
Aucune ligne dans les logs	Contrôleur pas rechargé	kubectl -n argocd rollout restart deploy/argocd-notifications-controller

Glissez pour voir

À retenir

• Le moteur de notifications est intégré à ArgoCD : le pod argocd-notifications-controller tourne déjà.
• Quatre briques : service (comment), template (quoi), trigger (quand), abonnement (qui).
• Les secrets (token Slack, SMTP) vont dans argocd-notifications-secret, jamais dans la ConfigMap.
• Piège n°1 : éditer la config en ligne de commande sur-échappe les guillemets JSON (U+005C). Passer par un fichier YAML.
• Piège n°2 : un trigger sans abonnement ne fait rien. L'abonnement est une annotation sur l'Application.
• Pour valider, lire les logs du contrôleur : Trigger ... TRIGGERED + Sending notification prouvent que la chaîne marche.
• En production, brancher d'abord on-sync-failed et on-health-degraded.

Pour aller plus loin

• Dépannage ArgoCD : traiter les synchros en échec que vos notifications remontent.
• Sécuriser ArgoCD : gérer les secrets et le RBAC autour de vos notifications.

×

📖 Voir la documentation →