Wenn alles in Dateien definiert ist, leben auch die Fehler in Dateien: eine falsche Einrückung, eine fehlende UID, ein Pfad, der im Container nicht existiert. Grafana sagt dir, was es getan hat, aber du musst wissen, wo du nachsehen musst. Diese Anleitung behandelt die Reload-Endpunkte, ein paar Prüfbefehle und die Fehler, denen du am häufigsten begegnest, sodass du sie beheben kannst, ohne die UI zu öffnen.

Was wann angewendet wird

Ressource	Wann sie gelesen wird	Wie du sie erneut anwendest
grafana.ini und GF_*-Umgebungsvariablen	Nur beim Start	Grafana neu starten
Datenquellen	Beim Start	Neustart oder der Reload-Endpunkt
Dashboards	Beim Start, dann alle updateIntervalSeconds	Warten oder der Reload-Endpunkt
Alerting-Ressourcen	Beim Start	Neustart (oder Provisioning erneut über die Admin-API ausführen, wie für deine Version dokumentiert)
Einstellungen von Plugin-Apps	Beim Start	Neustart oder der Reload-Endpunkt

Ohne Neustart neu laden

Diese Admin-Endpunkte lesen Provisioning-Dateien neu ein. Sie nutzen POST und Basic Authentication mit einem Grafana-Admin-Benutzer; API-Tokens funktionieren für die Admin-API nicht:

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

Ein erfolgreicher Aufruf gibt eine JSON-Nachricht zurück, die besagt, dass die Konfiguration neu geladen wurde. Exponiere diese Endpunkte nicht öffentlich, da sie Admin-Zugangsdaten brauchen. Für alles andere ist ein Neustart immer sicher.

Prüfen, was Grafana tatsächlich geladen hat

Vergleiche die Dateien mit der Sicht der API:

# Health
curl -s $BASE/api/health

# wirksame Servereinstellungen (sensible Werte maskiert)
curl -s -u "$AUTH" $BASE/api/admin/settings | jq '.paths, .server'

# Datenquellen, mit Read-only-Flag für provisionierte
curl -s -u "$AUTH" $BASE/api/datasources | jq '.[] | {name, uid, type, readOnly}'

# Konnektivität der Datenquelle
curl -s -u "$AUTH" $BASE/api/datasources/uid/prometheus/health

# Dashboards und Ordner
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 .

Fehlt etwas, das du provisioniert hast, in diesen Listen, sagen dir die Logs, warum.

Die Logs lesen

Provisioning-Meldungen kommen von Loggern, deren Namen mit provisioning beginnen. Erhöhe beim Debuggen die Ausführlichkeit:

# 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

Achte auf den Dateinamen in der Meldung. Grafana nennt die Datei, die es nicht parsen konnte, oder die Ressource, die es abgelehnt hat.

Dateien prüfen, bevor sie Grafana erreichen

Die meisten Fehler lassen sich in CI abfangen:

# YAML-Syntax
yamllint grafana/provisioning

# JSON-Syntax und Pflichtfelder
jq empty dashboards/**/*.json
jq -e '.uid and .title' dashboards/*/*.json >/dev/null

# doppelte Dashboard-UIDs
jq -r '.uid' dashboards/*/*.json | sort | uniq -d

# beginnt jede provisionierte Datei mit apiVersion: 1
grep -L '^apiVersion: 1' grafana/provisioning/*/*.yaml

Ein günstiger Ende-zu-Ende-Test ist, in CI ein Wegwerf-Grafana aus denselben Dateien zu starten, auf /api/health zu warten und auf die obige API-Ausgabe zu prüfen.

Häufige Probleme und Lösungen

Eine Datenquelle oder ein Dashboard erscheint nicht. Der Provisioning-Ordner ist nicht dort gemountet, wo Grafana sucht. Bestätige, dass [paths] provisioning (Standard /etc/grafana/provisioning) zu deinem Mount passt und dass die Unterordner exakt datasources, dashboards, alerting und plugins heißen.

„Permission denied“ beim Lesen von Dateien. Das offizielle Image läuft als Nicht-Root-Benutzer, gemountete Dateien müssen also für ihn lesbar sein. Mache sie für alle lesbar (chmod -R a+rX) oder setze passende Besitzverhältnisse am Volume.

Dashboard schlägt mit „Dashboard title cannot be empty“ fehl. Das JSON ist im API-Umschlag verpackt ({"dashboard": {...}}). Provisionierte Dateien müssen das Dashboard-Modell selbst enthalten.

Dashboard lädt, aber Panels sagen, die Datenquelle wurde nicht gefunden. Das Panel referenziert eine UID, die nicht provisioniert ist, oder die Datei hat noch einen ${DS_...}-Platzhalter aus einem Export. Setze uid in der Datenquellen-Datei und nutze dieselbe UID im Dashboard-JSON.

Zwei Dashboards kämpfen, oder eines wird immer wieder zurückgesetzt. Sie teilen eine uid oder denselben Titel im selben Ordner. Mache jede UID über die gesamte Installation eindeutig. Wird eine UI-Bearbeitung ständig überschrieben, gewinnt die Datei, was gewollt ist, außer der Provider hat allowUiUpdates: true.

Datei entfernt, aber das Dashboard ist noch da. Der Provider hat disableDeletion: true, oder das Dashboard wurde von Hand in einen Ordner verschoben. Lösche es über die API oder schalte disableDeletion aus.

Änderung an der Datenquelle bei Multi-Instanz-Setup ignoriert. Bei mehreren Grafana-Replikas aktualisiert eine Instanz eine Datenquelle nur, wenn die version der Datei gleich oder höher ist als die gespeicherte. Erhöhe version, wenn du die Datei änderst.

Umgebungsvariable nicht ersetzt. Die Interpolation gilt für Werte, nicht für Schlüssel. Sie funktioniert nicht in Dashboard-JSON, Alert-Regel-Annotationen, Query-Modellen, Mute Timings oder Templates. Prüfe, ob die Variable im Container tatsächlich gesetzt ist (docker compose exec grafana env | grep NAME).

Konflikte beim Alerting-Import. Eine Ressource mit derselben UID oder demselben Namen existiert von einer manuellen Bearbeitung. Lösche die handgemachte oder füge sie einem delete...-Block in der Datei hinzu und starte dann neu.

Secrets funktionieren nach einem Neuaufbau nicht mehr. Der secret_key hat sich geändert, sodass gespeicherte Secrets nicht entschlüsselt werden können. Stelle den ursprünglichen Schlüssel wieder her oder provisioniere die Datenquellen neu, die Zugangsdaten brauchen.

Admin-Passwort hat sich nicht geändert. admin_password gilt nur beim ersten Anlegen der Datenbank. Nutze grafana cli admin reset-admin-password oder erstelle das Volume neu.

Eine Helm- oder Operator-Ressource synchronisiert nicht. Beim Chart prüfe die Logs des Sidecar-Containers auf Label- oder Namespace-Abweichungen. Beim Operator führe kubectl describe auf der Ressource aus und lies ihre Status-Bedingungen.

Eine verlässliche Änderungsroutine

1. Ändere die Datei in einem Branch.
2. CI führt die obigen Linter aus und startet ein Wegwerf-Grafana aus den Dateien.
3. Merge. Der Auslieferungsmechanismus startet Grafana neu oder gleicht ab.
4. Prüfe /api/health und die Prüfbefehle.
5. Verhält es sich falsch, nimm den Commit zurück. Weil die Dateien die Wahrheit sind, stellt das Zurücknehmen den vorherigen Zustand wieder her.