Quand tout est défini dans des fichiers, les pannes vivent aussi dans des fichiers : une mauvaise indentation, un UID manquant, un chemin qui n’existe pas dans le conteneur. Grafana vous dit ce qu’il a fait, mais il faut savoir où regarder. Ce guide couvre les endpoints de rechargement, quelques commandes de vérification et les erreurs que vous rencontrerez le plus souvent, afin que vous puissiez les corriger sans ouvrir l’interface.

Ce qui est appliqué et quand

Ressource	Quand elle est lue	Comment la réappliquer
grafana.ini et variables d’env GF_*	Au démarrage uniquement	Redémarrer Grafana
Sources de données	Au démarrage	Redémarrer, ou le endpoint de rechargement
Tableaux de bord	Au démarrage, puis toutes les updateIntervalSeconds	Attendre, ou le endpoint de rechargement
Ressources d’alerting	Au démarrage	Redémarrer (ou relancer le provisionnement via l’API Admin comme documenté pour votre version)
Paramètres des applications de plugin	Au démarrage	Redémarrer, ou le endpoint de rechargement

Recharger sans redémarrer

Ces endpoints d’administration relisent les fichiers de provisionnement. Ils utilisent POST et l’authentification basique avec un utilisateur admin de Grafana ; les jetons d’API ne fonctionnent pas pour l’API Admin :

BASE=http://localhost:3000
AUTH="admin:$GRAFANA_ADMIN_PASSWORD"

curl -X POST -u "$AUTH" $BASE/api/admin/provisioning/dashboards/reload
curl -X POST -u "$AUTH" $BASE/api/admin/provisioning/datasources/reload
curl -X POST -u "$AUTH" $BASE/api/admin/provisioning/plugins/reload
curl -X POST -u "$AUTH" $BASE/api/admin/provisioning/notifications/reload

Un appel réussi renvoie un message JSON indiquant que la configuration a été rechargée. N’exposez pas ces endpoints publiquement, car ils nécessitent des identifiants admin. Pour tout le reste, redémarrer est toujours sans risque.

Vérifier ce que Grafana a réellement chargé

Comparez les fichiers avec la vue de l’API :

# santé
curl -s $BASE/api/health

# paramètres effectifs du serveur (valeurs sensibles masquées)
curl -s -u "$AUTH" $BASE/api/admin/settings | jq '.paths, .server'

# sources de données, avec l'indicateur lecture seule pour celles provisionnées
curl -s -u "$AUTH" $BASE/api/datasources | jq '.[] | {name, uid, type, readOnly}'

# connectivité de la source de données
curl -s -u "$AUTH" $BASE/api/datasources/uid/prometheus/health

# tableaux de bord et dossiers
curl -s -u "$AUTH" "$BASE/api/search?type=dash-db" | jq '.[] | {title, uid, folderTitle}'
curl -s -u "$AUTH" $BASE/api/folders | jq '.[] | {title, uid}'

# alerting
curl -s -u "$AUTH" $BASE/api/v1/provisioning/alert-rules | jq '.[] | {uid, title}'
curl -s -u "$AUTH" $BASE/api/v1/provisioning/contact-points | jq '.[].name'
curl -s -u "$AUTH" $BASE/api/v1/provisioning/policies | jq .

Si quelque chose que vous avez provisionné manque dans ces listes, les logs diront pourquoi.

Lire les logs

Les messages de provisionnement proviennent de loggers dont le nom commence par provisioning. Augmentez la verbosité pendant le débogage :

# docker compose
GF_LOG_LEVEL=debug docker compose up -d grafana
docker compose logs grafana | grep -i provision

# kubernetes
kubectl logs deploy/grafana -n monitoring -c grafana | grep -i provision

Cherchez le nom du fichier dans le message. Grafana nomme le fichier qu’il n’a pas pu analyser ou la ressource qu’il a rejetée.

Vérifier les fichiers avant qu’ils n’atteignent Grafana

La plupart des erreurs peuvent être détectées en CI :

# syntaxe YAML
yamllint grafana/provisioning

# syntaxe JSON et champs obligatoires
jq empty dashboards/**/*.json
jq -e '.uid and .title' dashboards/*/*.json >/dev/null

# uid de tableaux de bord en double
jq -r '.uid' dashboards/*/*.json | sort | uniq -d

# chaque fichier provisionné commence par apiVersion: 1
grep -L '^apiVersion: 1' grafana/provisioning/*/*.yaml

Un test de bout en bout économique consiste à démarrer en CI un Grafana jetable à partir des mêmes fichiers, à attendre /api/health et à faire des assertions sur la sortie de l’API ci-dessus.

Problèmes courants et corrections

Une source de données ou un tableau de bord n’apparaît pas. Le dossier de provisionnement n’est pas monté là où Grafana le cherche. Confirmez que [paths] provisioning (par défaut /etc/grafana/provisioning) correspond à votre montage, et que les noms de sous-dossiers sont exactement datasources, dashboards, alerting et plugins.

« Permission denied » à la lecture des fichiers. L’image officielle s’exécute avec un utilisateur non root ; les fichiers montés doivent donc lui être lisibles. Rendez-les lisibles par tous (chmod -R a+rX), ou définissez une propriété correspondante sur le volume.

Un tableau de bord échoue avec « Dashboard title cannot be empty ». Le JSON est enveloppé dans l’enveloppe de l’API ({"dashboard": {...}}). Les fichiers provisionnés doivent contenir le modèle du tableau de bord lui-même.

Le tableau de bord se charge mais les panneaux indiquent « data source not found ». Le panneau référence un UID qui n’est pas provisionné, ou le fichier contient encore un espace réservé ${DS_...} issu d’un export. Définissez uid dans le fichier de la source de données, et utilisez le même UID dans le JSON du tableau de bord.

Deux tableaux de bord se disputent, ou l’un revient sans cesse en arrière. Ils partagent un uid, ou le même titre dans le même dossier. Rendez chaque UID unique dans toute l’installation. Si une modification faite dans l’interface est sans cesse écrasée, c’est le fichier qui gagne, ce qui est voulu sauf si le fournisseur a allowUiUpdates: true.

Un fichier a été supprimé mais le tableau de bord est toujours là. Le fournisseur a disableDeletion: true, ou le tableau de bord a été déplacé dans un dossier à la main. Supprimez-le via l’API, ou désactivez disableDeletion.

Un changement de source de données est ignoré sur une installation multi-instances. Avec plusieurs réplicas Grafana, une instance ne met à jour une source de données que si la version du fichier est égale ou supérieure à celle stockée. Augmentez version quand vous modifiez le fichier.

Variable d’environnement non substituée. L’interpolation s’applique aux valeurs, pas aux clés. Elle ne fonctionne pas dans le JSON des tableaux de bord, les annotations de règles d’alerte, les modèles de requête, les mute timings ou les modèles. Vérifiez que la variable est bien définie dans le conteneur (docker compose exec grafana env | grep NAME).

Conflits d’import en alerting. Une ressource avec le même UID ou le même nom existe suite à une modification manuelle. Supprimez celle faite à la main, ou ajoutez-la à un bloc delete... dans le fichier, puis redémarrez.

Les secrets ont cessé de fonctionner après une reconstruction. La secret_key a changé, de sorte que les secrets stockés ne peuvent plus être déchiffrés. Restaurez la clé d’origine, ou provisionnez à nouveau les sources de données qui ont besoin d’identifiants.

Le mot de passe admin n’a pas changé. admin_password ne s’applique qu’à la première création de la base de données. Utilisez grafana cli admin reset-admin-password ou recréez le volume.

Une ressource Helm ou Operator ne se synchronise pas. Pour le chart, consultez les logs du conteneur sidecar à la recherche de désaccords de label ou de namespace. Pour l’Operator, exécutez kubectl describe sur la ressource et lisez ses conditions de statut.

Une routine de changement fiable

1. Modifiez le fichier dans une branche.
2. La CI exécute les linters ci-dessus et démarre un Grafana jetable à partir des fichiers.
3. Fusionnez. Le mécanisme de livraison redémarre ou réconcilie Grafana.
4. Vérifiez /api/health et les commandes de vérification.
5. En cas de dysfonctionnement, annulez le commit. Comme les fichiers sont la vérité, l’annulation restaure l’état précédent.