Grafana piloté à la souris fonctionne jusqu’au jour où il faut une seconde copie, un retour arrière, ou une réponse à « qui a modifié ce panneau ? ». Ce guide cartographie la façon d’exécuter Grafana à partir de fichiers, pour que vous sachiez quel mécanisme utiliser pour quelle ressource avant d’écrire la moindre ligne de YAML.

Pourquoi l’interface devient un problème

Quand les tableaux de bord, les sources de données et les alertes sont créés à la main, trois choses tournent mal avec le temps :

• Rien n’est reproductible. L’état vit dans la base de données de Grafana. Reconstruire une instance revient à refaire tous les clics.
• Les modifications sont invisibles. Il n’y a ni étape de relecture ni historique au-delà de ce que conserve le journal de versions propre à Grafana.
• Les environnements dérivent. Staging et production divergent lentement, et personne ne peut dire comment.

La solution consiste à traiter la base de données comme un cache et le dépôt comme la vérité. Tout ce dont Grafana a besoin est soit provisionné à partir de fichiers au démarrage, soit appliqué par un outil qui lit des fichiers.

Les couches

Couche	Format	Ce qu’elle contrôle	Appliquée par
Configuration du serveur	grafana.ini et variables d’env GF_*	Ports, base de données, authentification, SMTP, journalisation, feature toggles	Grafana au démarrage
Provisionnement des sources de données	YAML	Sources de données et leurs identifiants	Grafana au démarrage
Provisionnement des tableaux de bord	Fournisseur YAML + fichiers JSON	Tableaux de bord et dossiers	Grafana, réanalysé à intervalle régulier
Provisionnement de l’alerting	YAML	Règles d’alerte, points de contact, politiques, mute timings, modèles	Grafana au démarrage
Provisionnement des plugins	YAML	Paramètres des applications de plugin déjà installées	Grafana au démarrage
Terraform	HCL	Tout ce qui possède une API : dossiers, sources de données, tableaux de bord, alertes, équipes, comptes de service	terraform apply
Grafana Operator	Ressources personnalisées Kubernetes	Instances, dossiers, tableaux de bord, sources de données, règles d’alerte	Un contrôleur dans le cluster
Git Sync	Une ressource Repository	Tableaux de bord conservés dans un dépôt Git, synchronisés dans les deux sens	Grafana lui-même

Lequel utiliser ?

• Un seul Grafana dans un conteneur ou une VM, une petite équipe : configuration du serveur plus provisionnement par fichiers. Aucune pièce mobile supplémentaire.
• Kubernetes avec GitOps (Flux ou Argo CD) : le chart Helm de Grafana pour l’instance, avec les fichiers de provisionnement sous forme de ConfigMaps, ou le Grafana Operator si vous voulez chaque tableau de bord et chaque source de données comme objet Kubernetes à part entière.
• Plusieurs instances, ou Grafana Cloud : Terraform, car il peut aussi créer des stacks, des comptes de service et des équipes.
• Tableaux de bord rédigés par de nombreuses personnes : Git Sync, ou une bibliothèque de code telle que le Grafana Foundation SDK qui génère le JSON.

Ces approches se combinent bien. Une configuration courante : provisionnement par fichiers pour les sources de données et l’alerting, plus Git Sync ou Terraform pour les tableaux de bord.

Ce que les fichiers ne peuvent pas faire

Certaines ressources n’ont aucun format de fichier de provisionnement. Prévoyez-les :

• Les utilisateurs, équipes, organisations et comptes de service sont créés via l’API ou Terraform (ou via un fournisseur d’identité avec SSO et mappage des rôles).
• Les permissions des dossiers et des tableaux de bord sont gérées via l’API, Terraform ou l’Operator.
• Le mot de passe du premier administrateur n’est défini qu’au premier lancement ; le modifier ensuite nécessite un appel CLI ou API.

Les guides sur l’authentification et Terraform présentent les solutions de contournement.

Provisionné signifie verrouillé

Les ressources provisionnées sont censées appartenir aux fichiers. Les sources de données peuvent être marquées editable: false, les tableaux de bord issus d’un fournisseur peuvent refuser les enregistrements depuis l’interface, et les ressources d’alerte provisionnées ne peuvent pas du tout être modifiées dans l’interface. C’est le but : si quelqu’un pouvait les changer à la main, Git cesserait d’être la vérité. N’oubliez pas que l’interface reste utile pour explorer les données et ébaucher un panneau, et le workflow de création du guide sur les tableaux de bord montre comment ramener ces brouillons dans Git.

Un modèle mental pour une modification

1. Modifiez un fichier dans le dépôt (un JSON de tableau de bord, un YAML de source de données, une règle d’alerte).
2. Ouvrez une pull request, relisez le diff, fusionnez.
3. Le mécanisme de livraison l’applique : un redémarrage de conteneur, une réanalyse des tableaux de bord, une réconciliation Flux ou terraform apply.
4. La base de données propre à Grafana est mise à jour en conséquence. En cas de problème, annulez le commit.

Où aller ensuite

Lancez un Grafana local à partir d’un fichier compose (guide suivant), apprenez les règles de configuration, puis ajoutez les sources de données, les tableaux de bord et les alertes un par un. Pour référence, consultez la documentation Grafana.