Dashboard-JSON von Hand zu schreiben skaliert nicht, und der Export aus der UI lässt die UI als eigentliche Quelle zurück. Grafanas Observability-as-Code-Werkzeuge adressieren beides: Das Foundation SDK erzeugt Dashboards aus typisiertem Code, Git Sync lässt Grafana Dashboards in einem Git-Repository lesen und schreiben, und die gcx-CLI pusht und pullt Ressourcen vom Terminal. Mehrere dieser Funktionen sind neu, und manche APIs sind als Alpha markiert, prüfe also die Dokumentation für deine Version.

Dashboards mit dem Foundation SDK erzeugen

Das Foundation SDK bietet Builder für Dashboards, Panels und Queries in Go, TypeScript, Python, PHP und Java. Du beschreibst ein Dashboard in einer typisierten Sprache, und der Aufruf von build() erzeugt das Dashboard-JSON. Weil es Code ist, bekommst du Prüfungen zur Compile-Zeit, Wiederverwendung (eine Funktion, die eine Standard-Service-Panel-Zeile baut) und normales Code-Review.

Installiere es für deine Sprache, zum Beispiel:

# Go
go get github.com/grafana/grafana-foundation-sdk/go@latest

# TypeScript
npm install @grafana/grafana-foundation-sdk

Python-, PHP- und Java-Pakete sind in der SDK-Dokumentation aufgeführt. Es zielt auf Grafana 10 und neuer.

Ein typischer Workflow:

1. Schreibe ein kleines Programm, das die Dashboards definiert und das JSON jedes einzelnen nach dashboards/<name>.json schreibt.
2. Führe es in CI aus.
3. Committe das erzeugte JSON oder veröffentliche es als Build-Artefakt.
4. Liefere das JSON mit dem Mechanismus aus, den du ohnehin nutzt: ein Provider-Ordner, eine ConfigMap, eine GrafanaDashboard-Ressource, Terraform oder Git Sync.

# Skizze eines CI-Jobs
steps:
  - run: npm ci
  - run: npx tsx dashboards/generate.ts --out dashboards/generated
  - run: git diff --exit-code dashboards/generated   # schlägt fehl, wenn erzeugte Dateien veraltet sind

Die Prüfung mit git diff --exit-code stellt sicher, dass niemand erzeugtes JSON von Hand bearbeitet und dass Code und Ausgabe im Gleichschritt bleiben.

Git Sync

Git Sync lässt Grafana Dashboards als JSON in einem Git-Repository speichern. Änderungen fließen in beide Richtungen: Eine Bearbeitung in der Grafana-UI wird zu einem Commit oder Pull Request, und eine gemergte Änderung im Repository erscheint in Grafana. Grafana fragt das Repository standardmäßig alle 60 Sekunden ab, und ein Webhook lässt Updates nahezu sofort eintreffen. Git Sync ist in Grafana 13 über alle Editionen hinweg allgemein verfügbar. Es unterstützt GitHub (mit App-Authentifizierung), GitHub Enterprise, GitLab, Bitbucket und reines Git über einen Repository-Typ „Pure Git“.

Du kannst es komplett als Code mit einer Repository-Ressource konfigurieren. Erstelle repository.yaml:

apiVersion: provisioning.grafana.app/v0alpha1
kind: Repository
metadata:
  name: my-repo
spec:
  title: My Repository
  type: github
  github:
    url: https://github.com/<org>/<repo>
    branch: main
    path: grafana/
  sync:
    enabled: true
    intervalSeconds: 60
    target: folder
  workflows:
    - write
    - branch
secure:
  token:
    create: '<git-personal-access-token>'

Anmerkungen zu den Feldern:

• type ist github, githubEnterprise, gitlab, bitbucket oder git, und jeder hat seinen eigenen Block. Bitbucket und reines Git brauchen zusätzlich ein tokenUser.
• path ist der Ordner im Repository, den Grafana besitzt.
• workflows steuert, was Speichern in der UI tut: write committet direkt auf den Branch, und branch öffnet einen Pull Request.
• sync.target ist folder (der Standard) oder folderless.
• secure.token trägt die Zugangsdaten, sodass sie als Secret gespeichert werden und nicht in der Spec. Statt eines Tokens kannst du eine Verbindung über eine GitHub App oder OAuth App mit spec.connection.name nutzen; dafür braucht es eine separate connection.yaml.
• Die API-Version ist v0alpha1, Feldnamen können sich also zwischen Releases ändern.

Wende es mit gcx an (nächster Abschnitt) oder, wenn du magst, über die Grafana-UI.

Wofür Git Sync am besten ist: UI-Autoren und Git-first-Entwickler eine gemeinsame Quelle der Wahrheit teilen zu lassen, mit Pull-Request-Review für jede Änderung. Lies die Seite zu den Nutzungsbeschränkungen, bevor du es für eine große Instanz einführst, da das Provisionieren sehr vieler Dashboards Performance-Überlegungen mit sich bringt.

Die gcx-CLI

gcx ist Grafanas Kommandozeile für die Arbeit mit Ressourcen und, in Grafana Cloud, anderen Produkten. Sie funktioniert mit Grafana Cloud sowie Open-Source- oder Enterprise-Grafana 12 und neuer und ersetzt das frühere Werkzeug grafanactl (die Migration besteht größtenteils darin, den Befehl umzubenennen, und grafanactl resources serve wird zu gcx dev serve). Installiere sie aus dem Repository des Projekts und konfiguriere einen Kontext mit deiner Grafana-URL und deinem Token, wie in ihrer Dokumentation beschrieben.

Gängige Befehle:

# lokale Ressourcendateien nach Grafana pushen
gcx resources push --path ./resources

# auflisten, was existiert, oder eine Ressource untersuchen
gcx resources get repositories
gcx resources get repository/my-repo -o yaml

# bearbeiten oder löschen
gcx resources edit repository/my-repo
gcx resources delete repository/my-repo

# Dashboards bei der Entwicklung live in der Vorschau ansehen
gcx dev serve

Nutze sie in CI, um Ressourcendefinitionen aus dem Repository zu pushen, oder lokal beim Bau von Dashboards mit dem SDK.

Zwischen den Ansätzen wählen

Situation	Greife zu
Viele ähnliche Dashboards oder wiederverwendbare Bausteine	Foundation SDK, mit jedem Mechanismus ausgeliefert
Autoren arbeiten in der UI, du willst aber Git als Aufzeichnung	Git Sync
Kubernetes-GitOps, ein Objekt pro Dashboard	Grafana Operator
Automatisierung der gesamten Plattform einschließlich Teams und Berechtigungen	Terraform
Ein Grafana, statische JSON-Dateien	Einfacher Provider-Ordner

Sie lassen sich gut kombinieren: JSON mit dem SDK erzeugen, in ein Repository committen und Git Sync oder einen Provider-Ordner ausliefern lassen.

Prüfen

gcx resources get repositories
curl -s -u admin:$GRAFANA_ADMIN_PASSWORD \
  "http://localhost:3000/api/search?type=dash-db" | jq '.[] | {title, folderTitle}'

Bei Problemen mit der Repository-Synchronisierung prüfe den Status des Repositorys in Grafana (unter Administration, dann Provisioning) und das Grafana-Server-Log. Typische Probleme sind ein abgelaufenes Token, ein falscher Branch oder Pfad und ein Webhook, der Grafana nicht erreichen kann.