Quelltext der Seite Grafana: Dashboards als Code mit Provisioning und Git Sync

{{Steckbrief
| gilt_fuer   = Grafana 13.x; dateibasiertes Provisioning (YAML) für Datenquellen, Dashboards und Alerting; Git Sync mit GitHub oder reinem Git (OSS), zusätzlich GitLab und Bitbucket per OAuth in der Enterprise-Edition; Terraform-Provider
| bereich     = Server-Software
| dauer       = Provisioning ca. 1 Stunde; Git Sync ca. 30–60 Minuten
| rechte      = Grafana-Admin; Schreibrechte im Git-Repository; Zugriff auf die Grafana-Konfiguration
| stand       = Oktober 2026
}}
'''Grafana-Dashboards als Code''' zu verwalten heißt: Datenquellen, Dashboards und Alarmregeln liegen als Dateien in einem Git-Repository, Änderungen werden nachvollziehbar, prüfbar und lassen sich auf neue oder weitere Instanzen übertragen. Grafana bietet dafür zwei Wege: das klassische '''Provisioning''' über YAML-Dateien beim Start und seit Grafana 13 das allgemein verfügbare '''Git Sync''', das Dashboards und Ordner in beide Richtungen mit einem Repository abgleicht – inklusive Pull Requests direkt aus Grafana. Diese Anleitung zeigt beide Wege und wann welcher passt.

[[Datei:Grafana-GitSync.png|thumb|center|750px|Grafana als Code: Provisioning lädt beim Start YAML-Dateien aus /etc/grafana/provisioning für Datenquellen, Dashboard-Ordner und Alerting – Einweg, ideal für Grundkonfiguration und Neuaufbau; Git Sync gleicht Ordner und Dashboards in beide Richtungen mit einem Git-Repository ab (GitHub, reines Git; GitLab und Bitbucket per OAuth in Enterprise), Änderungen direkt als Commit oder als Pull Request mit Prüfung; Abgleich per Intervall oder Webhook; Standard bis 10 Repositories, empfohlen höchstens 1.000 Ressourcen je Verbindung; Terraform für Benutzer, Teams und Rechte.]]

== Welcher Weg? ==
{| class="wikitable"
! Kriterium !! Provisioning (Dateien) !! Git Sync !! Terraform
|-
| Richtung || Datei → Grafana || Git ↔ Grafana || Code → Grafana (API)
|-
| Bearbeitung || im Editor/Repository, Grafana zeigt nur an || in Grafana oder in Git; Speichern erzeugt Commit oder Pull Request || im Code
|-
| Geeignet für || Datenquellen, Kontaktpunkte, Basis-Dashboards, automatischer Neuaufbau || Dashboards und Ordner, die Teams laufend ändern || Benutzer, Teams, Ordnerrechte, ganze Umgebungen
|-
| Verfügbar || alle Editionen || alle Editionen ab Grafana 13 (OSS: GitHub und reines Git) || alle Editionen
|}
Häufig ist die Kombination sinnvoll: Datenquellen und Alarm-Kontaktpunkte per Provisioning, Dashboards per Git Sync.

== Weg 1: Provisioning mit YAML-Dateien ==
Grafana liest beim Start alle Dateien unter <code>/etc/grafana/provisioning</code> (im Compose-Beispiel der Ordner <code>./provisioning</code>).

'''Datenquellen''' – <code>provisioning/datasources/datenquellen.yaml</code>:
<syntaxhighlight lang="yaml">
apiVersion: 1
datasources:
  - name: Prometheus
    uid: prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
  - name: Loki
    uid: loki
    type: loki
    access: proxy
    url: http://loki:3100
  - name: Fachdatenbank
    uid: fachdb
    type: grafana-postgresql-datasource
    url: db.firma.lan:5432
    user: grafana_read
    jsonData: { database: kennzahlen, sslmode: require }
    secureJsonData:
      password: $FACHDB_PASSWORD
</syntaxhighlight>
'''Dashboards''' – <code>provisioning/dashboards/dashboards.yaml</code>:
<syntaxhighlight lang="yaml">
apiVersion: 1
providers:
  - name: infrastruktur
    folder: Infrastruktur
    type: file
    allowUiUpdates: false
    options:
      path: /etc/grafana/provisioning/dashboards/infrastruktur
</syntaxhighlight>
* Dashboards als JSON-Dateien in den angegebenen Ordner legen (Export aus Grafana: ''Teilen › Exportieren''). Die Datenquelle per '''UID''' referenzieren, damit das Dashboard überall funktioniert.
* '''Geheimnisse''' nicht in die Dateien schreiben: Grafana ersetzt <code>$VARIABLE</code> durch Umgebungsvariablen.
* Bereitgestellte Dashboards sind in der Oberfläche gesperrt (<code>allowUiUpdates: false</code>) – Änderungen erfolgen nur im Repository. Das ist gewollt.
* '''Alerting''' lässt sich ebenso unter <code>provisioning/alerting/</code> mit Kontaktpunkten, Benachrichtigungsrichtlinien, Ruhezeiten und Regeln bereitstellen; Vorlage dafür ist der Export unter ''Alerting › Export''.

== Weg 2: Grafana Git Sync ==
Git Sync verbindet Grafana mit einem Repository; Ordner und Dashboards werden abgeglichen und Änderungen in Grafana als Commit oder Pull Request zurückgeschrieben.

'''Voraussetzungen:'''
* Grafana 13 (der nötige Schalter <code>provisioning</code> ist ab Version 13 standardmäßig an), Admin-Rechte.
* Repository bei '''GitHub''' oder ein '''reines Git'''-Repository (z. B. Gitea, Forgejo); GitLab, Bitbucket und GitHub Enterprise per OAuth nur in der lizenzierten Enterprise-Edition. In älteren 12.x-Versionen mussten die Anbieter in <code>[provisioning] repository_types</code> freigeschaltet werden.
* Ein Token bzw. eine GitHub App mit Lese- und Schreibrechten auf genau dieses Repository.
* Für sofortigen Abgleich per '''Webhook''' muss Grafana vom Git-Server aus erreichbar sein; sonst gleicht Grafana im festen Intervall ab.

'''Einrichtung:'''
# ''Administration › Provisioning'' öffnen, eine Repository-Verbindung anlegen und den Anbieter wählen.
# Repository, '''Branch''' (z. B. <code>main</code>) und '''Pfad''' (z. B. <code>grafana/produktion/</code>) angeben, Token hinterlegen.
# '''Sync-Ziel''' wählen: als eigener Ordner (Standard) oder ordnerlos auf oberster Ebene.
# '''Arbeitsweise''' festlegen: Änderungen direkt auf den Branch schreiben oder als '''Pull Request''' einreichen – für Produktivumgebungen ist der Pull Request mit Prüfung durch eine zweite Person der sichere Weg.
# Vorhandene Dashboards in den synchronisierten Ordner verschieben bzw. importieren (seit 13.1 möglich).

'''Grenzen und Hinweise:'''
* Standardmäßig bis zu '''10 Repository-Verbindungen''' (<code>[provisioning] max_repositories</code>); der Hersteller empfiehlt höchstens etwa '''1.000 Ressourcen je Verbindung''', größere Repositories über mehrere Pfade aufteilen.
* Git Sync erhöht die Datenbanklast; zuerst in einer Testumgebung ausprobieren.
* '''Achtung bei Updates''': Grafana 13.0.0 enthielt einen Migrationsfehler, der bei aktivierten Git-Sync-Vorschaufunktionen Dashboards verlieren konnte, und wurde zurückgezogen. Vor jedem Update ein Datenbank-Backup erstellen und direkt auf die aktuelle Patch-Version aktualisieren.
* Dashboards liegen im Repository im neuen Kubernetes-ähnlichen Format (Schema v2); ältere JSON-Exporte werden beim Laden umgewandelt.

== Terraform ==
Der Grafana-Terraform-Provider verwaltet über die API Ordner, Rechte, Teams, Dienstkonten, Datenquellen und Alarmierung. Sinnvoll, wenn mehrere Instanzen (Test, Produktion, Mandanten) gleich aufgebaut werden sollen. Grafana 13 stellt die API schrittweise auf das neue <code>/apis</code>-Modell um; die alten <code>/api</code>-Pfade funktionieren vorerst weiter.

== Hinweise ==
* '''Ein Weg pro Objekt''': Dasselbe Dashboard nicht gleichzeitig per Provisioning und Git Sync verwalten – sonst überschreiben sich die Stände.
* '''Repository schützen''': Wer in das Repository schreiben darf, ändert Grafana. Branch-Schutz, Pull-Request-Prüfungen und signierte Commits nutzen.
* Bei Infrastruktur als Code, CI/CD und der Automatisierung von Monitoring-Umgebungen unterstützt Sie die [https://www.max-it.de/development/individuelle-softwareentwicklung/ individuelle Softwareentwicklung von m.a.x. it].

== Siehe auch ==
* [[Grafana im Unternehmen]] – Überblick und alle Artikel der Reihe
* [[Grafana: Datenquellen und Dashboards erstellen]]
* [[Grafana: Alerting mit E-Mail, Microsoft Teams und Webhooks]]
* [[Grafana: Absichern, Backup und Updates]]

== Links und Quellen ==
* [https://grafana.com/docs/grafana/latest/as-code/observability-as-code/git-sync/ Grafana-Dokumentation: Git Sync]
* [https://www.max-it.de/development/individuelle-softwareentwicklung/ Individuelle Softwareentwicklung von m.a.x. it]

{{Uebermax}}
[[Kategorie:Server-Software]]