Flux CD, Monitoring, alertes et observabilité

Superviser Flux, c'est répondre à trois questions distinctes : que se passe-t-il maintenant, qui doit être prévenu quand ça échoue, et comment ça évolue dans le temps. Cette leçon y répond avec trois outils : les commandes flux get et flux events pour observer, les objets Provider et Alert du notification-controller pour alerter, et les métriques Prometheus pour mesurer. Elle ajoute le Receiver, qui déclenche une réconciliation dès un push. Les sorties et messages cités viennent d'un cluster de test en Flux 2.9.6.

Ce que vous allez apprendre

• Observer l'état des objets Flux et la chronologie de leurs actions
• Envoyer une alerte sur un échec, avec un Provider et une Alert
• Lire le message exact que Flux envoie à un outil externe
• Déclencher une réconciliation immédiate avec un Receiver
• Collecter les métriques des contrôleurs et l'état des objets dans Prometheus

Prérequis

Cette leçon suppose une installation Flux qui déploie déjà quelque chose, pour avoir des événements à lire.

• La leçon Première application
• Le notification-controller, installé par défaut
• Pour la partie métriques, un Prometheus avec l'opérateur, par exemple kube-prometheus-stack

Observer : que fait Flux en ce moment ?

L'observation part toujours de flux get, qui donne pour chaque objet son état READY et son dernier message, puis descend vers flux events pour la chronologie et flux logs pour le détail d'un contrôleur. L'option --status-selector isole les objets en échec :

flux get all -A                                  # état de tous les objets Flux
flux get kustomizations -A --status-selector ready=false
flux events --for kustomization/podinfo          # chronologie d'un objet
flux logs --kind=Kustomization --name=podinfo    # journaux du contrôleur, filtrés

NAMESPACE    NAME     REVISION              SUSPENDED  READY  MESSAGE
flux-system  podinfo  6.15.0@sha1:dd507173  False      False  HorizontalPodAutoscaler/default/podinfo dry-run failed (Forbidden): …
team-a       borrow   main@sha1:01996ce7    False      False  can't access 'GitRepository/flux-system/fleet-infra', cross-namespace references have been blocked

Le message suffit presque toujours à orienter le diagnostic : il nomme l'objet refusé, l'identité utilisée ou la source introuvable. Les mêmes informations sont lisibles avec kubectl, dans les conditions de l'objet, dont la condition Ready porte un champ reason stable, comme ReconciliationFailed ou DependencyNotReady, plus facile à filtrer qu'un message.

Alerter : prévenir quand une réconciliation échoue

Le notification-controller envoie les événements des objets Flux vers un outil externe. Deux objets suffisent : un Provider décrit le canal (Slack, Teams, un webhook générique), une Alert choisit quels événements lui envoyer. En Flux 2.9, ces deux objets sont en version v1beta3.

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
metadata:
  name: echo
  namespace: flux-system
spec:
  type: generic
  address: http://echo.flux-system.svc.cluster.local/
---
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Alert
metadata:
  name: echecs
  namespace: flux-system
spec:
  summary: "cluster flux-lab"
  providerRef:
    name: echo
  eventSeverity: error
  eventSources:
    - kind: Kustomization
      name: "*"

Avec eventSeverity: error, seuls les échecs partent ; info envoie aussi chaque réconciliation réussie, utile pour l'audit mais bruyant sur un canal d'astreinte. Le nom "*" couvre tous les objets du namespace de l'Alert ; ajoutez namespace: dans une source pour viser un autre namespace.

Ce que Flux envoie réellement

Sur le cluster de test, le Provider générique pointe vers un petit serveur HTTP qui journalise chaque requête reçue. Une réconciliation en échec a produit ce message JSON, celui qu'un outil d'astreinte devra interpréter :

{
  "involvedObject": {
    "kind": "Kustomization",
    "namespace": "flux-system",
    "name": "podinfo",
    "apiVersion": "kustomize.toolkit.fluxcd.io/v1"
  },
  "severity": "error",
  "timestamp": "2026-10-02T14:02:49Z",
  "message": "Service/default/podinfo dry-run failed (Forbidden): …",
  "reason": "ReconciliationFailed",
  "metadata": {
    "revision": "6.15.0@sha1:dd507173b7b75b2312a36cabe0de5f09c1ce69c8",
    "summary": "cluster flux-lab"
  },
  "reportingController": "kustomize-controller"
}

Le summary de l'Alert arrive dans les métadonnées : c'est l'endroit pour nommer le cluster ou l'environnement, faute de quoi un message reçu de trois clusters est impossible à situer. La révision indique quel commit a échoué.

Pas de statut Ready sur Provider et Alert

En v1beta3, Provider et Alert sont des objets statiques : ils n'ont pas de condition Ready, et un kubectl wait --for=condition=ready sur eux expire. Une erreur d'adresse ou de jeton ne se voit qu'à l'envoi, dans les événements et les journaux du notification-controller.

Envoyer vers Slack ou un autre outil

Pour un vrai canal, la structure est la même ; seuls le type et l'adresse changent. L'URL d'un webhook est un secret : elle donne le droit d'écrire dans le canal. Elle se range dans un Secret, sous la clé address, jamais dans le manifeste versionné.

kubectl -n flux-system create secret generic slack-webhook \
  --from-literal=address=https://hooks.slack.com/services/<identifiants>

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

Dans un cluster partagé, chaque tenant déclare son propre Provider et sa propre Alert dans son namespace : il ne reçoit que les événements de ses objets. Sous le verrouillage vu dans la leçon multi-tenancy, une Alert ne peut d'ailleurs plus viser les objets d'un autre namespace.

Déclencher une réconciliation dès un push

Sans webhook, un nouveau commit attend l'intervalle de la source avant d'être vu. Un Receiver expose un point d'entrée HTTP : la forge l'appelle à chaque push, et Flux réconcilie aussitôt les objets listés. Le jeton partagé se range dans un Secret, et sert à la fois à signer les appels et à calculer le chemin.

kubectl -n flux-system create secret generic webhook-token \
  --from-literal=token="$(openssl rand -hex 24)"

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

Une fois prêt, le Receiver publie son chemin dans son statut :

NAME         SUSPENDED  READY  MESSAGE
fleet-infra  False      True   Receiver initialized for path: /hook/b1d86d52da54db578f93e2103cacd800c65a61418c1cc5cb38529cd15f1693f0

Ce chemin est servi par le service webhook-receiver du namespace flux-system, sur le port 80, qu'il faut exposer par un Ingress pour que la forge l'atteigne. Dans la forge, l'URL du webhook est l'adresse publique suivie de ce chemin, et le secret est le même jeton. Le type github vérifie la signature des appels ; d'autres types existent pour GitLab, Bitbucket ou un appel générique.

Sur le cluster de test, un type generic appelé depuis un pod a répondu HTTP 200, et la GitRepository a été réconciliée dans la seconde, sans attendre son intervalle d'une minute.

Mesurer : les métriques Prometheus

Les contrôleurs exposent leurs métriques sur le port 8080, nommé http-prom, au chemin /metrics. Elles décrivent leur fonctionnement interne, pas l'état des objets que vous déployez :

Métrique	Ce qu'elle mesure
gotk_reconcile_duration_seconds	Durée des réconciliations, par type, nom et namespace d'objet
controller_runtime_reconcile_total	Nombre de réconciliations par contrôleur et par résultat
controller_runtime_reconcile_errors_total	Nombre de réconciliations en erreur
workqueue_longest_running_processor_seconds	Réconciliation la plus longue en cours, signe d'un blocage

Glissez pour voir

L'exemple officiel fluxcd/flux2-monitoring-example les collecte avec un PodMonitor de Prometheus Operator :

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

Où trouver l'état des objets ?

Pas dans les contrôleurs : la métrique gotk_resource_info, qui porte pour chaque objet ses labels ready et suspended, est produite par kube-state-metrics, configuré pour lire les objets Flux. La documentation de Flux la décrit ainsi, et le dépôt d'exemple fournit la configuration de kube-state-metrics qui la crée. Sans elle, la requête suivante ne renvoie rien :

gotk_resource_info{ready="False"}

Le même dépôt d'exemple fournit les tableaux de bord Grafana (cluster, control-plane, logs) sous forme de fichiers JSON, à importer avec le reste de la configuration plutôt qu'un par un.

À retenir

• On observe avec flux get (état et message), flux events (chronologie) et flux logs (détail d'un contrôleur).
• On alerte avec un Provider (le canal) et une Alert (les événements), en v1beta3 ; eventSeverity: error limite l'envoi aux échecs.
• Le message envoyé porte l'objet, la raison, la révision et le summary : nommez-y le cluster.
• Une URL de webhook est un secret : elle va dans un Secret, sous la clé address.
• Un Receiver rend la réconciliation immédiate à chaque push.
• Les contrôleurs exposent des métriques internes ; l'état des objets (gotk_resource_info) vient de kube-state-metrics.

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

×

📖 Voir la documentation →