Grafana : provisionner datasources et dashboards as-code (GitOps)

Le provisioning déclare les datasources et dashboards de Grafana en fichiers YAML/JSON, chargés automatiquement au démarrage. Fini le clic-à-clic non reproductible : la configuration devient versionnée, rejouable et déployable à l'identique sur plusieurs environnements. C'est la base d'une gestion GitOps de Grafana.

Ce guide de référence complète le guide Grafana. Il s'adresse aux profils intermédiaires et avancés. Vous allez provisionner une datasource, provisionner un dashboard via un fournisseur de fichiers, comprendre les ressources en lecture seule, et connaître les options editable et disableDeletion.

Ce que vous allez apprendre

Comprendre pourquoi provisionner plutôt que cliquer.
Provisionner une datasource Prometheus en YAML.
Provisionner un dashboard via un provider de fichiers + JSON.
Vérifier qu'une ressource est bien gérée par le code (readOnly).
Verrouiller avec editable: false et disableDeletion.

Pourquoi provisionner

Configurer Grafana à la souris ne se reproduit pas. À la recréation du conteneur, tout est perdu ; rien n'est versionné ; et déployer la même configuration sur staging et production relève du copier-coller manuel. Trois questions restent sans réponse : que se passe-t-il si quelqu'un supprime un dashboard par accident, comment tracer un changement, comment garantir la cohérence entre environnements.

Le provisioning répond à tout cela. Des fichiers déposés dans /etc/grafana/provisioning/ (sous-dossiers datasources/, dashboards/, alerting/) sont lus au démarrage. La configuration vit alors dans Git, revue et historisée comme du code.

Provisionner une datasource

Une datasource se déclare dans provisioning/datasources/. Ce fichier crée la datasource Prometheus au démarrage, avec un uid stable pour la référencer depuis les dashboards :

apiVersion: 1

datasources:
  - name: Prometheus
    uid: prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    editable: false

L'option editable: false empêche toute modification depuis l'interface : la datasource devient lecture seule, ce qui force les changements à passer par le code. On vérifie le résultat par l'API, qui renvoie la datasource avec "readOnly": true :

curl -s "http://admin:MDP@localhost:3000/api/datasources"

Datasource Prometheus provisionnée dans Grafana : bandeau indiquant qu'elle est gérée par la configuration et non modifiable dans l'interface

Provisionner un dashboard

Provisionner un dashboard demande deux éléments : un fournisseur (provider) qui indique à Grafana où chercher les fichiers JSON, et le JSON du dashboard lui-même.

Le provider se place dans provisioning/dashboards/provider.yaml :

apiVersion: 1

providers:
  - name: default
    orgId: 1
    folder: Provisioned
    type: file
    disableDeletion: true
    updateIntervalSeconds: 30
    options:
      path: /var/lib/grafana/dashboards

Chaque fichier .json du dossier path devient un dashboard, rangé dans le dossier Provisioned. Un dashboard minimal contient un uid, un title, un schemaVersion et des panels :

{
  "uid": "prom-self",
  "title": "Prometheus - Self-monitoring",
  "schemaVersion": 39,
  "panels": [
    {
      "type": "stat",
      "title": "Targets UP",
      "datasource": {"type": "prometheus", "uid": "prometheus"},
      "targets": [{"expr": "count(up == 1)"}]
    }
  ]
}

Au démarrage, Grafana lit le fichier et affiche le dashboard. On le confirme par l'API de recherche, qui le renvoie avec son URL :

curl -s "http://admin:MDP@localhost:3000/api/search?query=Self"

Liste des dashboards Grafana montrant le dossier Provisioned et le dashboard Prometheus - Self-monitoring

Ressources en lecture seule, un choix assumé

Un dashboard provisionné ne peut pas être modifié durablement via l'interface : toute édition est perdue au prochain rechargement. C'est intentionnel et force le bon workflow.

disableDeletion: true empêche la suppression depuis l'UI.
updateIntervalSeconds définit la fréquence de rechargement des fichiers (ici 30 s), utile pour voir un changement de JSON pris en compte sans redémarrer.

Pour modifier un dashboard provisionné, on suit la boucle GitOps : éditer le JSON, le committer, le redéployer ; Grafana recharge automatiquement. Pour partir d'une base existante, on exporte un dashboard construit à la main (menu Share → Export → Save to file) puis on le range dans le dépôt.

FAQ : questions fréquentes

Qu'est-ce que le provisioning Grafana ?

Le provisioning déclare les datasources et dashboards de Grafana en fichiers YAML et JSON, placés dans /etc/grafana/provisioning/ et chargés automatiquement au démarrage. La configuration devient versionnée, reproductible et déployable à l'identique sur plusieurs environnements.

Comment provisionner un dashboard Grafana ?

Il faut deux éléments : un provider dans provisioning/dashboards/ qui indique le dossier des fichiers JSON, et le JSON du dashboard lui-même. Chaque fichier .json du dossier devient un dashboard, chargé au démarrage et rechargé selon updateIntervalSeconds.

Pourquoi un dashboard provisionné est-il en lecture seule ?

C'est intentionnel : les modifications faites dans l'interface seraient écrasées au prochain rechargement des fichiers. Cela force le workflow GitOps, où l'on modifie le JSON, on le committe et on le redéploie. L'option disableDeletion empêche aussi la suppression via l'UI.

Comment vérifier qu'une ressource Grafana est provisionnée ?

Via l'API : GET /api/datasources renvoie la datasource avec le champ readOnly à true si elle vient du provisioning. Dans l'interface, un bandeau signale que la ressource est gérée par le code et n'est pas modifiable.

À retenir

Le provisioning rend Grafana reproductible : datasources et dashboards en fichiers, chargés au démarrage.
Une datasource se déclare en YAML dans provisioning/datasources/, avec un uid stable.
Un dashboard demande un provider de fichiers plus le JSON du dashboard.
editable: false et disableDeletion verrouillent les ressources : elles passent en lecture seule.
Modifier = éditer le JSON et redéployer : c'est la boucle GitOps, tracée et rejouable.

Prochaines étapes

Grafana : guide de référence Installation, concepts, alerting et provisioning.

Créer des panels et visualisations Construire les panels avant de les exporter en JSON.

Variables de dashboard Rendre le dashboard provisionné dynamique.