Flux CD — Monitoring, alertes et observabilité

Flux expose des métriques Prometheus et un système de notifications natif pour chaque événement de réconciliation (succès, échec, drift détecté). Ce guide explique comment configurer les alertes Slack ou Teams, lire les métriques Prometheus, et utiliser les dashboards Grafana officiels pour surveiller l’état de tous vos déploiements GitOps en temps réel.

Ce que vous allez apprendre

Lire les événements de réconciliation avec flux events et kubectl
Configurer un Provider (canal de notification) — Slack, Teams, webhook
Créer des Alert pour les événements qui vous intéressent
Comprendre les métriques Prometheus exposées par Flux
Importer les dashboards Grafana officiels Flux
Configurer des Receivers pour les webhooks entrants GitHub/GitLab

Prérequis

Flux bootstrappé avec notification-controller (inclus par défaut)
Pour la partie métriques : Prometheus et Grafana déployés dans le cluster (via kube-prometheus-stack par exemple)
Un workspace Slack ou un endpoint Teams pour tester les alertes

Lire les événements Flux

Avant de configurer des alertes, sachez lire les événements directement :

# Tous les événements récents
flux events

# Événements d'une Kustomization spécifique
flux events --for kustomization/apps

# Événements en temps réel (watch)
flux events --watch

# Via kubectl (plus verbeux)
kubectl events -n flux-system

# Logs d'un contrôleur spécifique
flux logs --kind=kustomization --name=apps --tail=20

Événements types à surveiller :

Événement	Type	Signification
`ReconciliationSucceeded`	Normal	Réconciliation réussie
`ReconciliationFailed`	Warning	Erreur lors de la réconciliation
`DependencyNotReady`	Warning	Dépend d’un objet qui n’est pas prêt
`ArtifactUpToDate`	Normal	La source n’a pas changé
`NewArtifact`	Normal	Nouvelle révision détectée dans la source
`PrunedObject`	Normal	Ressource supprimée de Git, pruned du cluster

Configurer les alertes Slack

Étape 1 — Créer le Secret Slack

Créez un webhook Slack (dans les paramètres de votre workspace Slack > Applications > Incoming Webhooks) et stockez l’URL dans un Secret Kubernetes :

kubectl create secret generic slack-webhook \
  --from-literal=address=https://hooks.slack.com/services/T000/B000/XXXXXXXX \
  --namespace=flux-system

Ne mettez jamais l’URL du webhook directement dans le manifeste YAML — elle serait versionnée dans Git en clair.

Étape 2 — Créer le Provider

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
metadata:
  name: slack
  namespace: flux-system
spec:
  type: slack
  channel: "#flux-alerts"   # Canal Slack où envoyer les messages
  secretRef:
    name: slack-webhook

Étape 3 — Créer les règles d’alerte

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Alert
metadata:
  name: on-call-alerts
  namespace: flux-system
spec:
  summary: "Alertes Flux — cluster my-cluster"
  providerRef:
    name: slack
  eventSeverity: error   # "info" pour tout, "error" pour les échecs seulement
  eventSources:
    - kind: GitRepository
      name: "*"         # Tous les GitRepository dans flux-system
    - kind: Kustomization
      name: "*"         # Toutes les Kustomizations
    - kind: HelmRelease
      name: "*"         # Toutes les HelmRelease

eventSeverity: error envoie les alertes uniquement en cas d’échec. eventSeverity: info envoie toutes les réconciliations (verbeux mais utile pour l’audit).

Pour n’alerter que sur des objets dans un namespace spécifique, ajoutez namespace: my-app dans chaque eventSources :

eventSources:
  - kind: Kustomization
    name: "*"
    namespace: production

Configurer les alertes Teams

Créez un webhook dans Teams (canal > Connecteurs > Incoming Webhook) :

kubectl create secret generic teams-webhook \
  --from-literal=address=https://my-org.webhook.office.com/webhookb2/.../IncomingWebhook/... \
  --namespace=flux-system

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
metadata:
  name: teams
  namespace: flux-system
spec:
  type: msteams
  secretRef:
    name: teams-webhook

kubectl create secret generic pagerduty-token \
  --from-literal=token=<integration-key> \
  --namespace=flux-system

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
metadata:
  name: pagerduty
  namespace: flux-system
spec:
  type: pagerduty
  address: https://events.pagerduty.com
  secretRef:
    name: pagerduty-token

Pour n’importe quel endpoint HTTP :

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
metadata:
  name: generic-webhook
  namespace: flux-system
spec:
  type: generic
  address: https://my-webhook-endpoint.example.com/flux

Métriques Prometheus

Flux expose des métriques Prometheus sur le port 8080 de chaque contrôleur. Si vous avez kube-prometheus-stack installé, vous pouvez les collecter en créant un ServiceMonitor :

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: flux-system
  namespace: monitoring
spec:
  namespaceSelector:
    matchNames:
      - flux-system
  selector:
    matchExpressions:
      - key: app
        operator: In
        values:
          - helm-controller
          - kustomize-controller
          - notification-controller
          - source-controller
          - image-automation-controller
          - image-reflector-controller
  endpoints:
    - port: http-prom
      path: /metrics
      interval: 30s

Métriques clés à surveiller

Métrique	Type	Description
`gotk_reconcile_duration_seconds`	Histogram	Durée des réconciliations par contrôleur/kind
`gotk_resource_info`	Gauge	Informations sur chaque ressource Flux (suspended, ready)
`controller_runtime_reconcile_total`	Counter	Nombre total de réconciliations par résultat (success/error)
`controller_runtime_reconcile_errors_total`	Counter	Nombre d’erreurs de réconciliation

Requête PromQL utile — taux d’erreurs de réconciliation :

rate(controller_runtime_reconcile_errors_total[5m])

Requête PromQL — ressources Flux non prêtes :

gotk_resource_info{ready="False"}

Dashboards Grafana officiels

L’équipe Flux maintient des dashboards Grafana officiels dans le dépôt fluxcd/flux2-monitoring-example. Vous pouvez les importer depuis Grafana.com :

Dashboard	ID Grafana	Description
Flux Cluster Stats	16714	Vue globale de l’état du cluster
Flux Control Plane	16715	Métriques des contrôleurs Flux

Importation via Grafana :

Ouvrez Grafana > Dashboards > Import
Entrez l’ID 16714 ou 16715
Sélectionnez votre datasource Prometheus

Ou via un ConfigMap Kubernetes si vous utilisez le sidecar de provisioning Grafana :

apiVersion: v1
kind: ConfigMap
metadata:
  name: flux-dashboards
  namespace: monitoring
  labels:
    grafana_dashboard: "1"
data:
  flux-cluster.json: |
    <contenu du dashboard JSON téléchargé depuis grafana.com>

Configurer un Receiver pour les webhooks entrants

Un Receiver permet à GitHub ou GitLab de notifier Flux immédiatement lors d’un push, plutôt que d’attendre l’intervalle de polling :

Créer le token secret pour valider les webhooks

TOKEN=$(head -c 12 /dev/urandom | shasum | cut -d ' ' -f1)
kubectl create secret generic webhook-token \
  --from-literal=token=${TOKEN} \
  --namespace=flux-system

Créer le Receiver

apiVersion: notification.toolkit.fluxcd.io/v1
kind: Receiver
metadata:
  name: github-receiver
  namespace: flux-system
spec:
  type: github
  events:
    - "ping"
    - "push"
  secretRef:
    name: webhook-token
  resources:
    - apiVersion: source.toolkit.fluxcd.io/v1
      kind: GitRepository
      name: flux-system

Récupérer l’URL du Receiver

kubectl get receiver github-receiver -n flux-system
# NAME              READY  STATUS
# L'URL complète est dans le status
kubectl get receiver github-receiver -n flux-system \
  -o jsonpath='{.status.webhookPath}'

Configurer le webhook dans GitHub

Dans votre dépôt GitHub > Settings > Webhooks > Add webhook :

URL : https://flux-webhook.example.com<chemin-du-status>
Content type : application/json
Secret : le ${TOKEN} créé à l’étape 1
Events : Push events

Alertes par équipe (multi-tenant)

Dans un contexte multi-tenant, vous pouvez créer des alertes spécifiques par namespace pour que chaque équipe reçoive uniquement ses propres alertes :

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Alert
metadata:
  name: frontend-alerts
  namespace: frontend
spec:
  summary: "Alertes GitOps — équipe frontend"
  providerRef:
    name: slack-frontend   # Provider dans le namespace frontend
  eventSeverity: error
  eventSources:
    - kind: Kustomization
      name: "*"
      namespace: frontend
    - kind: HelmRelease
      name: "*"
      namespace: frontend

Chaque équipe crée son propre Provider avec son webhook Slack dédié.

Checklist observabilité Flux

flux events retourne des événements récents sans erreurs persistantes
flux get all affiche READY: True pour tous les objets
Au moins un Alert configuré pour les erreurs de réconciliation
Les métriques Flux sont collectées par Prometheus
Un dashboard Grafana affiche l’état des réconciliations
Un Receiver webhook accélère la détection des nouveaux commits
Les alertes critical (HelmRelease échec, drift persistant) vont sur un canal avec astreinte

À retenir

flux events et flux logs sont les premières commandes à utiliser pour diagnostiquer un problème.
Le notification-controller gère les alertes sortantes (Alert + Provider) et les webhooks entrants (Receiver).
Ne jamais mettre une URL de webhook en clair dans le YAML — toujours via un Secret Kubernetes.
gotk_resource_info{ready="False"} est la requête Prometheus à surveiller en priorité.
Les Receiver webhooks réduisent la latence de déploiement de 1 minute (polling) à quelques secondes.

Prochaines étapes

Multi-tenancy Alertes par équipe dans un contexte multi-tenant Flux

Vue d'ensemble Flux CD Retour à la page de formation complète

Formation ArgoCD Comparer les deux approches GitOps