Un pod qui redémarre en boucle à 3h du matin, une base de données qui sature sa mémoire un vendredi soir, un nœud qui décroche sans que personne ne le remarque avant le lendemain : sur un cluster Kubernetes en production, ce genre d’incident finit toujours par arriver. La seule question, c’est de savoir si vous le voyez venir ou si vous le découvrez via un ticket client. Prometheus et Grafana restent la combinaison de référence pour éviter ce second scénario, et la stack a nettement évolué ces dernières semaines : Prometheus vient de passer en version 3.14.0 (17 août 2026), Grafana affiche désormais la 13.2.2 (15 septembre 2026), et l’opérateur qui orchestre le tout, Prometheus Operator, est passé en 0.94.0 le 9 septembre 2026. Ce tutoriel vous guide, étape par étape, dans le déploiement complet d’une stack de supervision Kubernetes fonctionnelle, de l’installation du cluster jusqu’aux alertes envoyées sur Slack.

Pourquoi surveiller un cluster Kubernetes avec Prometheus et Grafana

Kubernetes orchestre vos conteneurs, mais il ne vous dit pas grand-chose sur leur santé réelle. Un pod peut tourner sans erreur apparente tout en consommant 95 % de sa mémoire allouée, prêt à être tué par l’OOM killer à la moindre pointe de trafic. Sans supervision, vous découvrez ce genre de problème après coup, dans les logs, une fois l’incident terminé. Prometheus résout ce manque en interrogeant régulièrement (on parle de scraping) des endpoints métriques exposés par vos applications et par les composants internes de Kubernetes, puis en stockant ces séries temporelles dans sa propre base. Grafana, de son côté, transforme ces données brutes en tableaux de bord lisibles et déclenche des alertes visuelles quand un seuil est franchi.

Ce duo domine le paysage de l’observabilité Kubernetes pour une raison simple : Prometheus a été conçu dès le départ pour un environnement dynamique où les pods naissent et meurent en permanence, contrairement aux outils de monitoring plus anciens pensés pour des serveurs fixes, comme le rappelle la documentation officielle du projet. Le projet est aujourd’hui hébergé par la Cloud Native Computing Foundation, la même fondation qui héberge Kubernetes, ce qui explique l’intégration native entre les deux. Grafana, lui, s’est imposé comme la couche de visualisation universelle, capable d’interroger Prometheus mais aussi Loki, Tempo ou des bases de données classiques depuis un seul tableau de bord.

Concrètement, la mécanique repose sur un modèle pull plutôt que push : au lieu que chaque application pousse ses métriques vers un collecteur central, c’est Prometheus qui va lui-même interroger chaque cible à intervalle régulier, généralement toutes les 15 à 30 secondes. Ce choix architectural simplifie énormément la découverte de services dans un cluster où les adresses IP changent en permanence : Prometheus s’appuie sur l’API Kubernetes pour savoir en temps réel quels pods existent et où les joindre, sans configuration statique à maintenir à la main. C’est également ce qui rend Prometheus particulièrement adapté à l’auto-scaling : quand un déploiement passe de 3 à 30 réplicas sous l’effet d’un Horizontal Pod Autoscaler, la supervision suit automatiquement, sans intervention humaine.

Ce tutoriel part du principe que vous gérez déjà un cluster fonctionnel, qu’il s’agisse d’un environnement local, d’un cluster managé chez un fournisseur cloud, ou d’une installation K3s pour de l’edge computing. L’objectif est de vous amener, en douze étapes concrètes, d’un cluster sans aucune visibilité à une stack de supervision complète : collecte des métriques, tableaux de bord exploitables, règles d’alerte et notifications automatiques. Chaque étape inclut les commandes exactes à exécuter, la sortie attendue et les pièges les plus fréquents à cette étape précise, avant de couvrir en fin d’article les erreurs classiques, une section dépannage détaillée et des astuces réservées aux déploiements en production.

Prérequis : versions et outils nécessaires

Avant de commencer, vérifiez que votre environnement correspond aux versions suivantes. Utiliser une version plus ancienne de Helm ou de kubectl reste souvent possible, mais les commandes de ce tutoriel ont été validées avec cette configuration précise.

OutilVersion utilisée dans ce tutorielRôle
Kubernetes1.30 ou supérieurCluster cible (minikube, K3s, GKE, AKS ou EKS)
Helm3.15 ou supérieurGestionnaire de paquets pour déployer la stack
kubectlVersion alignée avec votre clusterInteraction en ligne de commande avec l’API Kubernetes
kube-prometheus-stack (chart Helm)29.31.1 (18 septembre 2026)Chart communautaire packageant Prometheus, Grafana et Alertmanager
Prometheus3.14.0 (17 août 2026, stable)Collecte et stockage des métriques
Prometheus Operator0.94.0 (9 septembre 2026)Gère les CRD Prometheus, ServiceMonitor et PrometheusRule
Grafana13.2.2 (15 septembre 2026, stable)Visualisation et tableaux de bord
Alertmanager1.43.3Routage et déduplication des alertes

Un point de vigilance avant de vous lancer : au moment de la rédaction, une version 3.15.0-rc.1 de Prometheus a été publiée le 21 septembre 2026, mais il s’agit d’une release candidate. Pour un déploiement en production, restez sur la 3.14.0, qui est la dernière version stable listée sur la page officielle de téléchargement. Si vous cherchez une branche à support long, la politique de cycle de release de Prometheus confirme que la série 3.13 est maintenue en LTS jusqu’au 31 juillet 2027, ce qui peut convenir si vous préférez limiter la fréquence des montées de version.

Étape 1 : Préparer votre cluster Kubernetes

Que vous testiez sur un cluster local ou que vous déployiez sur un cluster managé, commencez par vérifier que kubectl pointe bien vers le bon contexte. Une erreur classique consiste à lancer une installation sur le mauvais cluster parce qu’un ancien kubeconfig traîne encore dans votre environnement.

kubectl config current-context
kubectl get nodes -o wide
kubectl cluster-info

Assurez-vous également que votre cluster dispose d’au moins 2 vCPU et 4 Go de RAM disponibles rien que pour la stack de monitoring : Prometheus, Grafana et Alertmanager consomment des ressources non négligeables dès qu’ils tournent en continu, surtout si vous conservez plusieurs jours de métriques en mémoire avant compaction sur disque.

Si vous testez sur un environnement local, un cluster minikube ou K3s avec au moins 4 vCPU et 8 Go de RAM au total fera l’affaire, en laissant de la marge pour vos propres applications à côté de la stack de monitoring. Sur un cluster managé, vérifiez également que votre nœud (ou pool de nœuds) dispose d’un accès à un provisioner de stockage persistant : sans lui, l’étape de déploiement de Prometheus échouera silencieusement, les volumes restant coincés en attente. C’est l’un des blocages les plus fréquents rencontrés par les équipes qui suivent ce type de tutoriel pour la première fois, et nous y revenons en détail dans la section dépannage.

Étape 2 : Installer Helm et ajouter le dépôt prometheus-community

Helm simplifie considérablement le déploiement : plutôt que d’appliquer des dizaines de manifestes YAML à la main, vous installez un chart préconfiguré et vous ajustez seulement les valeurs qui vous intéressent. Si Helm n’est pas encore installé sur votre machine, la méthode la plus fiable reste le script officiel documenté par le projet Helm.

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
helm version

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update
helm search repo prometheus-community/kube-prometheus-stack --versions | head -5

La dernière commande doit afficher la version 29.31.1 du chart en tête de liste, celle qui embarque Prometheus 3.14.0, Alertmanager 1.43.3 et les CRD compatibles avec Prometheus Operator 0.94.0. Si une version plus ancienne apparaît en premier, votre cache de dépôt Helm n’est pas à jour : relancez helm repo update.

Étape 3 : Créer un namespace dédié à l’observabilité

Isoler la stack de monitoring dans son propre namespace facilite la gestion des quotas de ressources, des permissions RBAC et du nettoyage en cas de désinstallation. Évitez de tout déployer dans le namespace default, une pratique qui complique le débogage sur des clusters partagés par plusieurs équipes.

kubectl create namespace monitoring
kubectl label namespace monitoring purpose=observability

Étape 4 : Personnaliser le fichier values.yaml pour kube-prometheus-stack

Le chart kube-prometheus-stack accepte des centaines de paramètres, mais l’immense majorité des déploiements n’en modifient qu’une poignée : la rétention des métriques, le stockage persistant, le mot de passe d’administration Grafana et la taille des ressources allouées. Créez un fichier values.yaml dédié plutôt que de tout passer en ligne de commande, ce qui rend la configuration reproductible et versionnable dans Git.

prometheus:
  prometheusSpec:
    retention: 15d
    resources:
      requests:
        cpu: 500m
        memory: 1Gi
      limits:
        memory: 2Gi
    storageSpec:
      volumeClaimTemplate:
        spec:
          accessModes: ["ReadWriteOnce"]
          resources:
            requests:
              storage: 20Gi

grafana:
  adminPassword: "changez-ce-mot-de-passe"
  persistence:
    enabled: true
    size: 5Gi
  resources:
    requests:
      cpu: 200m
      memory: 256Mi

alertmanager:
  alertmanagerSpec:
    resources:
      requests:
        cpu: 100m
        memory: 128Mi

Ne laissez jamais adminPassword en clair dans un dépôt Git public. Pour un usage réel, référencez plutôt un secret Kubernetes existant via grafana.admin.existingSecret, une approche détaillée dans notre tutoriel sur la gestion des secrets Kubernetes.

Étape 5 : Déployer Prometheus Operator, Prometheus 3.14 et Alertmanager

Une fois le fichier de valeurs prêt, l’installation elle-même tient en une seule commande Helm. Elle déploie Prometheus Operator, qui à son tour crée et gère les ressources Prometheus, Alertmanager et les CRD associées (ServiceMonitor, PodMonitor, PrometheusRule), comme le décrit le dépôt Helm charts de la communauté Prometheus.

helm install kube-prometheus-stack prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --values values.yaml \
  --version 29.31.1

kubectl get pods -n monitoring -w

L’installation crée en général une dizaine de pods : l’opérateur, un ou plusieurs pods Prometheus, un pod Grafana, un ou plusieurs pods Alertmanager, ainsi que des exporters comme node-exporter (un par nœud) et kube-state-metrics. Voici à quoi ressemble une sortie saine après deux à trois minutes :

NAME                                                     READY   STATUS    RESTARTS   AGE
kube-prometheus-stack-grafana-7d6f9c8b5-xk2pl             3/3     Running   0          2m14s
kube-prometheus-stack-kube-state-metrics-6b7f4-w9qzt       1/1     Running   0          2m14s
kube-prometheus-stack-operator-5f8d9c6f4-hj3rq             1/1     Running   0          2m14s
kube-prometheus-stack-prometheus-node-exporter-x7ttv        1/1     Running   0          2m14s
alertmanager-kube-prometheus-stack-alertmanager-0           2/2     Running   0          105s
prometheus-kube-prometheus-stack-prometheus-0               2/2     Running   0          105s

Si un pod reste en Pending plus de deux minutes, c’est presque toujours un problème de stockage persistant : votre cluster n’a pas de StorageClass par défaut capable de satisfaire la demande de 20 Gi définie dans values.yaml. Vérifiez avec kubectl get storageclass avant d’aller plus loin.

Étape 6 : Accéder à l’interface Prometheus et vérifier les cibles

Avant de toucher à Grafana, validez que Prometheus scrape correctement ses cibles. Un port-forward suffit pour un premier contrôle, sans exposer quoi que ce soit publiquement.

kubectl port-forward -n monitoring svc/kube-prometheus-stack-prometheus 9090:9090

Ouvrez ensuite http://localhost:9090/targets dans votre navigateur. Toutes les cibles doivent apparaître en vert (state UP). Si l’une d’elles reste en rouge, le problème vient presque toujours d’une règle réseau ou d’un ServiceMonitor mal configuré, deux points que nous couvrons dans la section dépannage plus bas.

Profitez-en également pour tester une requête PromQL simple dans l’onglet Graph, histoire de confirmer que les données remontent bien, pas seulement que les cibles répondent. Une requête comme up{namespace="monitoring"} doit retourner une série avec la valeur 1 pour chaque cible saine. Une valeur 0 signifie que Prometheus considère la cible comme injoignable, même si le pod correspondant tourne normalement : c’est souvent le signe d’un problème de port ou de chemin dans la définition du ServiceMonitor plutôt que d’une vraie panne applicative.

Étape 7 : Configurer Grafana 13.2 et sa source de données

Bonne nouvelle : le chart kube-prometheus-stack connecte automatiquement Grafana à Prometheus au démarrage, vous n’avez donc rien à configurer manuellement pour la datasource principale. Récupérez le mot de passe administrateur (si vous n’en avez pas défini un dans values.yaml) puis ouvrez l’interface.

kubectl get secret -n monitoring kube-prometheus-stack-grafana \
  -o jsonpath="{.data.admin-password}" | base64 --decode; echo

kubectl port-forward -n monitoring svc/kube-prometheus-stack-grafana 3000:80

Connectez-vous sur http://localhost:3000 avec l’utilisateur admin. Dans Grafana 13.2, l’écran d’accueil a été remanié pour mettre en avant l’exploration de données directement depuis la page principale, une des nouveautés mises en avant par Grafana Labs pour cette série de versions. Vérifiez dans Connections > Data sources que la source Prometheus affiche un statut vert après un test de connexion.

Étape 8 : Exposer Grafana en toute sécurité via un Ingress

Le port-forward est pratique pour les tests, mais inutilisable au quotidien pour une équipe. Exposez Grafana via un Ingress, avec TLS et une authentification en amont plutôt qu’un compte admin partagé.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: grafana-ingress
  namespace: monitoring
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - grafana.exemple.fr
      secretName: grafana-tls
  rules:
    - host: grafana.exemple.fr
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: kube-prometheus-stack-grafana
                port:
                  number: 80

Ne vous arrêtez pas au TLS : ajoutez une NetworkPolicy qui restreint l’accès entrant au namespace monitoring aux seules sources légitimes (ingress controller, équipe SRE). Notre tutoriel sur Cilium et le zero trust réseau détaille la mise en place de ce type de politique sur un cluster Kubernetes.

Pensez également à limiter l’accès en sortie (egress) du namespace monitoring, en particulier si Alertmanager doit contacter un webhook Slack externe : sans règle d’egress explicite, un pod compromis dans ce namespace pourrait exfiltrer des données vers n’importe quelle destination sur Internet. Une politique par défaut de type deny-all, complétée par des exceptions explicites pour chaque destination légitime (API Slack, registre de dashboards, etc.), reste la posture la plus sûre pour un namespace qui, par nature, a un accès en lecture à l’ensemble des métriques du cluster.

Étape 9 : Créer un ServiceMonitor pour surveiller votre propre application

Jusqu’ici, vous supervisez uniquement l’infrastructure Kubernetes elle-même. L’intérêt réel de Prometheus, c’est de scraper aussi vos applications métier. Si votre service expose déjà un endpoint /metrics au format Prometheus (via une bibliothèque comme prom-client en Node.js ou client_golang), un ServiceMonitor suffit à le connecter.

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: mon-api-servicemonitor
  namespace: monitoring
  labels:
    release: kube-prometheus-stack
spec:
  selector:
    matchLabels:
      app: mon-api
  namespaceSelector:
    matchNames:
      - production
  endpoints:
    - port: metrics
      path: /metrics
      interval: 30s

Le label release: kube-prometheus-stack est le piège numéro un à cette étape. Prometheus Operator ne découvre que les ServiceMonitor portant le label correspondant à la release Helm définie dans prometheus.prometheusSpec.serviceMonitorSelector. L’oublier signifie que votre ServiceMonitor existe dans le cluster, mais que Prometheus l’ignore silencieusement.

Notez aussi le champ interval: 30s : c’est la fréquence à laquelle Prometheus va interroger l’endpoint /metrics de votre application. Descendre à 5 ou 10 secondes peut sembler tentant pour obtenir des graphiques plus réactifs, mais cela multiplie d’autant le volume de séries temporelles stockées et la charge CPU sur Prometheus lui-même. Pour la majorité des métriques applicatives (temps de réponse, taux d’erreur, nombre de requêtes), 30 secondes offre un bon compromis entre réactivité et coût de stockage. Réservez des intervalles plus courts aux métriques réellement critiques, comme la latence d’un système de paiement, où chaque seconde de retard de détection compte.

Une fois le ServiceMonitor appliqué avec kubectl apply -f servicemonitor-mon-api.yaml, retournez dans l’interface Prometheus, section Status > Target health. Votre application doit apparaître dans la liste sous quelques dizaines de secondes, avec le label job correspondant au nom du ServiceMonitor. Si elle n’apparaît toujours pas après une minute, vérifiez que le port nommé metrics existe bien dans la définition du Service Kubernetes ciblé : Prometheus Operator résout le port par son nom, pas par son numéro.

Étape 10 : Importer des dashboards Kubernetes dans Grafana

Plutôt que de construire vos tableaux de bord à partir de zéro, importez des dashboards communautaires déjà éprouvés. Dans Grafana, allez dans Dashboards > New > Import puis saisissez l’identifiant du dashboard à récupérer sur le catalogue officiel de Grafana Labs. Les identifiants les plus utilisés pour un cluster Kubernetes couvrent la vue d’ensemble du cluster, l’usage par namespace et le détail par pod.

  • Vue cluster : CPU, mémoire et stockage agrégés par nœud
  • Vue namespace : consommation de ressources ventilée par équipe ou service
  • Vue pod : redémarrages, throttling CPU, utilisation mémoire par conteneur

Une fois importés, sélectionnez la source de données Prometheus créée automatiquement à l’étape 7. Si un panneau reste vide, la cause la plus fréquente est une variable de template mal résolue : ouvrez le panneau en mode édition et vérifiez la requête PromQL générée dans l’inspecteur.

Ne vous limitez pas aux dashboards importés tels quels. La plupart des équipes finissent par les dupliquer et les adapter à leur propre vocabulaire métier : renommer “namespace” en “environnement”, ajouter un panneau de coût estimé par équipe, ou regrouper plusieurs graphiques existants dans une seule ligne pour réduire le défilement. Grafana 13.2 facilite cette personnalisation grâce à une édition de requêtes repensée, mise en avant par Grafana Labs comme l’une des améliorations principales de cette version, qui permet de modifier une requête PromQL directement depuis la vue d’exploration sans repasser par l’éditeur de panneau complet.

Étape 11 : Écrire des règles d’alerte Prometheus

Un dashboard qu’on regarde uniquement quand un client se plaint n’a que peu de valeur. Les alertes automatisées sont ce qui transforme la supervision passive en système proactif. Avec Prometheus Operator, on définit ces règles via une ressource PrometheusRule, dont la syntaxe suit celle des règles d’alerte natives de Prometheus, plutôt que dans un fichier de configuration statique.

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: alertes-cluster-critiques
  namespace: monitoring
  labels:
    release: kube-prometheus-stack
spec:
  groups:
    - name: ressources.rules
      rules:
        - alert: PodMemoireElevee
          expr: |
            container_memory_working_set_bytes{namespace="production"}
            / container_spec_memory_limit_bytes{namespace="production"} > 0.9
          for: 5m
          labels:
            severity: warning
          annotations:
            summary: "Pod {{ $labels.pod }} proche de sa limite mémoire"
            description: "Le pod {{ $labels.pod }} dépasse 90% de sa limite mémoire depuis 5 minutes."

        - alert: PodEnCrashLoop
          expr: increase(kube_pod_container_status_restarts_total[15m]) > 3
          for: 5m
          labels:
            severity: critical
          annotations:
            summary: "{{ $labels.pod }} redémarre en boucle"
            description: "Le pod {{ $labels.pod }} a redémarré plus de 3 fois en 15 minutes."

Le champ for: 5m évite les fausses alertes déclenchées par un pic isolé de quelques secondes : la condition doit rester vraie pendant toute la durée indiquée avant que l’alerte ne passe à l’état firing. Réduire ce délai à zéro pour “réagir plus vite” est une erreur classique qui noie l’équipe sous des notifications inutiles.

Étape 12 : Router les alertes avec Alertmanager vers Slack

Une alerte qui ne notifie personne n’a aucune utilité. Alertmanager 1.43.3 se charge de router chaque alerte vers le bon canal selon ses labels, avec regroupement et suppression des doublons. Configurez le routage via un secret contenant la configuration Alertmanager, référencé dans values.yaml.

alertmanager:
  config:
    global:
      resolve_timeout: 5m
    route:
      receiver: "slack-notifications"
      group_by: ["alertname", "namespace"]
      group_wait: 30s
      group_interval: 5m
      repeat_interval: 4h
      routes:
        - matchers:
            - severity="critical"
          receiver: "slack-notifications"
          repeat_interval: 1h
    receivers:
      - name: "slack-notifications"
        slack_configs:
          - api_url: "https://hooks.slack.com/services/VOTRE/WEBHOOK/URL"
            channel: "#alertes-production"
            send_resolved: true
            title: "{{ .CommonAnnotations.summary }}"

Appliquez ensuite la mise à jour avec helm upgrade plutôt que helm install, pour ne pas recréer toute la stack à partir de zéro.

helm upgrade kube-prometheus-stack prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --values values.yaml \
  --version 29.31.1

Erreurs fréquentes à éviter

La plupart des déploiements Prometheus et Grafana qui tournent mal en production trébuchent sur les mêmes points, encore et encore. En voici cinq qui reviennent le plus souvent, avec le contexte qui explique pourquoi ils passent si facilement inaperçus lors des premiers tests.

  • Oublier le label de release sur les CRD. Un ServiceMonitor ou un PrometheusRule sans le bon label release est silencieusement ignoré par l’opérateur. Aucune erreur n’apparaît dans les logs, ce qui rend le problème difficile à diagnostiquer : le manifeste s’applique sans erreur, la ressource existe bien dans kubectl get, mais Prometheus continue simplement à l’ignorer. C’est probablement l’erreur la plus fréquente chez les équipes qui découvrent Prometheus Operator, car rien dans l’interface ne signale explicitement le rejet.
  • Ne pas définir de rétention adaptée. Laisser la rétention par défaut sur un cluster à fort volume de métriques peut saturer le stockage persistant en quelques jours, surtout si vous scrapez de nombreuses applications avec des labels à forte cardinalité (identifiants utilisateurs, chemins d’URL complets). Ajustez retention et retentionSize ensemble, et surveillez la croissance réelle du volume plutôt que de vous fier à une estimation théorique.
  • Exposer Grafana sans authentification renforcée. Un compte admin avec un mot de passe faible, accessible publiquement, est une porte ouverte vers vos métriques internes, parfois sensibles (charges, noms d’API, topologie réseau, voire indirectement des informations sur vos clients via des labels métier). Ce risque est souvent sous-estimé parce que Grafana n’expose “que” des graphiques, alors qu’un attaquant peut en tirer une cartographie précise de votre infrastructure.
  • Scraper trop souvent, trop de cibles. Un intervalle de scraping de 5 secondes sur des centaines de pods multiplie inutilement la charge sur Prometheus. 30 secondes suffit dans l’immense majorité des cas applicatifs, et vous pouvez toujours descendre à 10 ou 15 secondes ponctuellement pour une cible critique, sans l’appliquer globalement.
  • Ignorer les limites de ressources sur Prometheus lui-même. Sans limits.memory défini, un pic de cardinalité (trop de séries temporelles uniques, souvent causé par des labels mal choisis comme un identifiant de session ou un timestamp inclus dans un nom de métrique) peut faire consommer toute la mémoire du nœud et provoquer un OOM kill en cascade, qui à son tour interrompt la collecte de métriques pendant l’incident même que vous cherchiez à détecter.

Dépannage : les problèmes les plus courants

Même en suivant les étapes précédentes à la lettre, il est presque impossible de déployer une stack de cette complexité sans rencontrer au moins un des problèmes suivants. La bonne nouvelle, c’est que ce sont des classiques bien documentés, pas des bugs exotiques : chaque symptôme ci-dessous a une cause identifiable et une commande de diagnostic précise pour la confirmer en quelques secondes, avant de perdre du temps à explorer de fausses pistes.

SymptômeCause probableCommande de diagnostic
Pod Prometheus bloqué en PendingAucune StorageClass par défaut ou PVC non provisionnékubectl describe pvc -n monitoring
Cible absente de /targetsServiceMonitor mal labellisé ou NetworkPolicy trop restrictivekubectl get servicemonitor -n monitoring --show-labels
Grafana affiche “No data” sur un panneauDatasource mal sélectionnée ou requête PromQL invalideInspecteur de panneau > onglet Query
Alertes jamais déclenchéesPrometheusRule sans label release, ou expression PromQL toujours faussekubectl get prometheusrule -n monitoring -o yaml
Notifications Slack absentesWebhook expiré ou route Alertmanager mal cibléekubectl logs -n monitoring alertmanager-kube-prometheus-stack-alertmanager-0
Prometheus redémarre en boucle (OOMKilled)Cardinalité excessive des métriques ou limite mémoire trop bassekubectl top pod -n monitoring
Grafana inaccessible via Ingress (502)Service backend mal nommé dans l’Ingress ou port incorrectkubectl get endpoints -n monitoring
helm upgrade échoue avec un conflit CRDCRD Prometheus Operator déjà présentes dans une version incompatiblekubectl get crd | grep monitoring.coreos.com

Si le problème persiste après ces vérifications, examinez les logs de Prometheus Operator lui-même : c’est lui qui traduit vos CRD en configuration Prometheus effective, et il logge explicitement les raisons de rejet d’un ServiceMonitor ou d’une PrometheusRule.

Un dernier réflexe utile en cas de doute général sur l’état de la stack : demandez directement à Prometheus Operator de vous lister les objets qu’il a effectivement pris en compte, plutôt que de supposer qu’un manifeste appliqué est un manifeste actif.

kubectl logs -n monitoring deployment/kube-prometheus-stack-operator --tail=50

Astuces avancées pour un usage en production

Une fois la stack de base stable, plusieurs ajustements font la différence entre un monitoring “qui marche” et un monitoring qui tient réellement la charge en production.

Fédération et remote write. Sur un environnement multi-cluster, évitez de multiplier les instances Grafana isolées. Configurez plutôt remoteWrite pour envoyer les métriques de chaque cluster vers un backend centralisé de type Mimir ou Thanos, ce qui permet des dashboards cross-cluster sans dupliquer l’infrastructure de visualisation.

Surveiller la cardinalité vous-même. Une requête PromQL simple révèle rapidement quelles métriques génèrent le plus de séries temporelles, souvent la vraie cause d’un Prometheus qui grossit trop vite.

topk(10, count by (__name__)({__name__=~".+"}))

Automatiser le cycle de mise à jour. Ne montez jamais Prometheus, Grafana et le chart en même temps lors d’une mise à niveau majeure. Testez d’abord sur un cluster de staging, avec helm diff upgrade (plugin Helm) pour visualiser précisément ce qui va changer avant d’appliquer quoi que ce soit en production. Si votre organisation utilise déjà GitOps, notre tutoriel ArgoCD montre comment automatiser ce type de déploiement de façon déclarative.

Attention à la 13.3. Grafana Labs a planifié la sortie de la série 13.3 pour le 20 octobre 2026. Tant que cette version n’est pas passée en stable, évitez de baser vos scripts d’automatisation sur des fonctionnalités annoncées mais pas encore publiées.

Séparer les dashboards par audience. Un dashboard unique qui essaie de satisfaire à la fois les développeurs, les équipes SRE et les managers finit toujours par être illisible pour tout le monde. Construisez plutôt une vue haut niveau (disponibilité, taux d’erreur, latence) pour un affichage permanent en salle d’équipe, et des dashboards détaillés par service pour le débogage technique. Grafana permet de dupliquer et de filtrer un dashboard existant par variable de template (namespace, application, environnement), ce qui évite de maintenir plusieurs versions manuellement.

Documenter vos runbooks dans les annotations d’alerte. Une alerte qui se contente d’un titre générique comme “CPU élevé” oblige la personne d’astreinte à deviner quoi faire. Ajoutez un lien vers votre documentation interne directement dans le champ annotations.runbook_url de chaque PrometheusRule : le temps gagné lors d’un incident nocturne justifie largement les quelques minutes passées à rédiger ces liens en amont.

Le projet complet : arborescence et fichiers finaux

Pour repartir sur une base propre, voici l’arborescence complète d’un projet de monitoring Kubernetes tel que ce tutoriel l’a construit, à versionner dans Git aux côtés du reste de votre infrastructure as code.

monitoring-stack/
├── values.yaml                          # Configuration Helm de kube-prometheus-stack
├── manifests/
│   ├── grafana-ingress.yaml             # Exposition sécurisée de Grafana
│   ├── servicemonitor-mon-api.yaml      # Scraping de l'application métier
│   └── prometheusrule-alertes.yaml      # Règles d'alerte CPU/mémoire/crash loop
└── README.md                            # Procédure d'installation et de mise à jour

Une fois ces fichiers en place, le déploiement complet se résume à trois commandes, reproductibles sur n’importe quel cluster répondant aux prérequis de ce tutoriel.

Versionnez ce dossier dans le même dépôt Git que vos autres manifestes d’infrastructure, avec un changelog clair pour chaque modification de values.yaml. Sur la durée, c’est ce qui distingue une stack de monitoring qui reste fiable pendant des années d’une stack qui se dégrade progressivement : chaque ajustement de seuil d’alerte, chaque nouvelle règle, chaque changement de rétention doit être traçable et réversible. Si une alerte se met soudainement à se déclencher trop souvent après une mise à jour, vous devez pouvoir identifier en quelques minutes quel commit a modifié le seuil correspondant, plutôt que de rouvrir l’interface Grafana pour deviner ce qui a changé.

kubectl create namespace monitoring
helm install kube-prometheus-stack prometheus-community/kube-prometheus-stack \
  --namespace monitoring --values monitoring-stack/values.yaml --version 29.31.1
kubectl apply -f monitoring-stack/manifests/

Si vous démarrez tout juste avec Kubernetes et que vous n’avez pas encore de cluster prêt à recevoir cette stack, commencez par notre tutoriel de création de cluster avec Minikube, ou déployez directement sur un cluster managé avec notre guide GKE si vous visez la production sur Google Cloud. Et si Helm est encore nouveau pour vous, notre tutoriel dédié à Helm couvre les bases avant de revenir ici.

Questions fréquentes

Faut-il utiliser Prometheus 3.14 ou attendre la 3.15 ?

Restez sur la 3.14.0 pour un déploiement en production. La 3.15.0-rc.1, publiée le 21 septembre 2026, est une version candidate destinée aux tests, pas à un usage critique. Si vous préférez une branche à support prolongé, la série 3.13 LTS est maintenue jusqu’au 31 juillet 2027. Dans tous les cas, épinglez toujours une version précise du chart Helm (via --version) plutôt que de laisser Helm installer la dernière version disponible au moment du déploiement : cela évite qu’une mise à jour majeure de Prometheus ou de Grafana ne s’installe sans prévenir lors d’un simple helm upgrade exécuté plusieurs mois plus tard.

Combien de ressources faut-il prévoir pour Prometheus sur un petit cluster ?

Pour un cluster de développement avec une dizaine de pods applicatifs, 500m CPU et 1 à 2 Gi de mémoire suffisent généralement, avec une rétention de 15 jours. Sur un cluster de production avec plusieurs centaines de pods, prévoyez plutôt 2 vCPU et 4 à 8 Gi de mémoire, à ajuster selon la cardinalité réelle observée. La meilleure méthode reste empirique : déployez avec des valeurs prudentes, surveillez la consommation réelle de Prometheus lui-même pendant une à deux semaines via kubectl top pod -n monitoring, puis ajustez les requests et limits en conséquence plutôt que de deviner à l’avance.

Grafana Cloud est-il une alternative viable à l’auto-hébergement ?

Oui, notamment depuis l’annonce par Grafana Labs, le 14 septembre 2026, de la disponibilité générale de la gestion des secrets dans Grafana Cloud avec une intégration AWS Secrets Manager. Cette option a du sens si vous préférez déléguer la maintenance de l’infrastructure de monitoring, au prix d’une dépendance à un service tiers.

Pourquoi mon ServiceMonitor n’apparaît-il pas dans Prometheus ?

C’est presque toujours un problème de label. Prometheus Operator ne surveille que les ServiceMonitor correspondant au sélecteur défini dans prometheusSpec.serviceMonitorSelector, généralement basé sur le label release. Vérifiez aussi que le namespaceSelector inclut bien le namespace où tourne votre application.

Comment éviter que Prometheus ne sature le stockage du cluster ?

Définissez à la fois retention (durée) et retentionSize (volume maximal) dans la configuration Prometheus, et surveillez la cardinalité de vos métriques avec des requêtes comme topk(10, count by (__name__)({__name__=~".+"})). Pour une rétention longue durée, préférez un remote write vers Mimir ou Thanos plutôt que d’augmenter indéfiniment le stockage local.

Peut-on utiliser cette stack sur un cluster K3s ou faut-il un cluster complet ?

K3s fonctionne parfaitement avec kube-prometheus-stack, à condition d’ajuster les ressources à la baisse pour les environnements légers. Consultez notre tutoriel K3s si vous partez d’un cluster léger pour de l’edge computing ou du développement local.

Comment sécuriser l’accès à Grafana sans exposer un mot de passe partagé ?

Configurez une authentification via OAuth (GitHub, Google Workspace ou un fournisseur OIDC interne) dans la section grafana.ini du chart, et désactivez la création de comptes en libre-service. Combinez cela avec un Ingress en TLS et une NetworkPolicy restrictive pour limiter la surface d’attaque. Pensez également à créer des rôles Grafana distincts (Viewer, Editor, Admin) plutôt que de distribuer des accès administrateur à toute l’équipe : la majorité des utilisateurs n’a besoin que de consulter les dashboards, pas de modifier la configuration des sources de données ou les permissions d’organisation.