Datenquellen sind das Erste, wovon jedes Dashboard und jede Alert-Regel abhängt, daher sind sie das Erste, was in Dateien gehört. Grafana liest YAML aus dem Ordner provisioning/datasources beim Start, erstellt die gefundenen Datenquellen und aktualisiert die bereits vorhandenen.

Eine einfache Datei

provisioning/datasources/datasources.yaml:

apiVersion: 1

datasources:
  - name: Prometheus
    uid: prometheus
    type: prometheus
    access: proxy
    orgId: 1
    url: http://prometheus:9090
    isDefault: true
    editable: false
    jsonData:
      timeInterval: 15s

Du kannst eine oder viele Datenquellen in eine Datei schreiben und mehrere Dateien nutzen. Grafana lädt alles unter dem Ordner.

Die wichtigsten Felder:

• name ist der Anzeigename.
• uid ist die stabile Kennung, auf die Dashboards und Alert-Regeln verweisen. Lässt du sie weg, erzeugt Grafana eine, was alles, was darauf verweist, fragil macht. Setze sie immer.
• type ist die Plugin-ID, etwa prometheus, loki, tempo, postgres oder elasticsearch.
• access: proxy bedeutet, dass Grafanas Server die Anfragen stellt. Das ist die normale Wahl und hält Zugangsdaten aus Browsern heraus.
• isDefault markiert die Datenquelle, mit der neue Panels starten. Pro Organisation sollte nur eine der Standard sein.
• editable: false blockiert Änderungen in der UI, sodass die Datei maßgeblich bleibt.
• jsonData enthält nicht geheime Einstellungen, und die Schlüssel hängen vom Plugin ab.
• secureJsonData enthält Secrets, die Grafana in seiner Datenbank verschlüsselt.
• version wird bei Updates verglichen. Wenn mehrere Grafana-Instanzen eine Datenbank teilen, aktualisiert eine Instanz eine Datenquelle nur, wenn die Version der Datei gleich oder höher ist als die gespeicherte, erhöhe sie also, wenn du eine Datei änderst.

Zugangsdaten, ohne sie zu committen

Provisioning-Dateien unterstützen die Interpolation von Umgebungsvariablen in Werten (nicht in Schlüsseln) mit $VAR oder ${VAR}. Schreibe $$ für ein literales Dollarzeichen:

apiVersion: 1

datasources:
  - name: Postgres
    uid: postgres-main
    type: postgres
    url: $POSTGRES_HOST:5432
    user: $POSTGRES_USER
    editable: false
    jsonData:
      database: app
      sslmode: require
    secureJsonData:
      password: $POSTGRES_PASSWORD

Reiche POSTGRES_PASSWORD aus deinem Secret Store in den Container weiter (siehe die Anleitung zu Secrets). Das Passwort erscheint nie im Repository, und Grafana speichert es nach dem Laden verschlüsselt.

Eigene HTTP-Header

Header-Namen kommen in jsonData und ihre Werte in secureJsonData, zusammen durchnummeriert:

datasources:
  - name: Mimir
    uid: mimir
    type: prometheus
    access: proxy
    url: https://mimir.example.com/prometheus
    jsonData:
      httpHeaderName1: X-Scope-OrgID
    secureJsonData:
      httpHeaderValue1: tenant-a

Basic Auth und TLS

datasources:
  - name: Internal Prometheus
    uid: prom-internal
    type: prometheus
    access: proxy
    url: https://prometheus.internal:9090
    basicAuth: true
    basicAuthUser: grafana
    jsonData:
      tlsAuthWithCACert: true
    secureJsonData:
      basicAuthPassword: $PROM_PASSWORD
      tlsCACert: $PROM_CA_CERT

Logs, Metriken und Traces korrelieren

Mehrere Plugins verknüpfen Datenquellen über UID miteinander, was ein weiterer Grund ist, UIDs von Hand zu setzen. Zum Beispiel kann Loki ein Log-Feld in einen Link zu Traces in Tempo verwandeln:

datasources:
  - name: Loki
    uid: loki
    type: loki
    access: proxy
    url: http://loki:3100
    jsonData:
      derivedFields:
        - name: TraceID
          matcherRegex: 'trace_id=(\w+)'
          url: '$${__value.raw}'
          datasourceUid: tempo

Pluginspezifische jsonData-Schlüssel variieren je nach Version, bestätige sie also in der Dokumentation der Datenquelle. Ein schneller Weg, sie zu entdecken, ist, die Datenquelle einmal in einer Scratch-Instanz zu konfigurieren und das Ergebnis über die API zu lesen (GET /api/datasources/uid/<uid>).

Löschen und bereinigen

deleteDatasources entfernt Datenquellen, bevor datasources verarbeitet wird. Nutze es, wenn du eine stilllegst:

apiVersion: 1

deleteDatasources:
  - name: Old Graphite
    orgId: 1

Um den Ordner zur vollständigen Wahrheit zu machen, füge prune: true hinzu (Grafana 11.1 oder neuer). Provisionierte Datenquellen, die in keiner Datei mehr stehen oder deren Datei gelöscht wurde, werden dann beim nächsten Start entfernt:

apiVersion: 1
prune: true

datasources:
  - name: Prometheus
    uid: prometheus
    type: prometheus
    url: http://prometheus:9090

Nur provisionierte Datenquellen werden bereinigt. Von Hand in der UI erstellte bleiben unberührt.

Anwenden und prüfen

Datenquellen werden beim Start gelesen, starte Grafana also neu oder rufe den Reload-Endpunkt mit Admin-Basic-Auth auf:

curl -X POST -u admin:$GRAFANA_ADMIN_PASSWORD \
  http://localhost:3000/api/admin/provisioning/datasources/reload

curl -s -u admin:$GRAFANA_ADMIN_PASSWORD \
  http://localhost:3000/api/datasources | jq '.[] | {name, uid, type, readOnly}'

Provisionierte Datenquellen melden readOnly: true. Um die Konnektivität ohne UI zu bestätigen, nutze den Health-Endpunkt der Datenquelle:

curl -s -u admin:$GRAFANA_ADMIN_PASSWORD \
  http://localhost:3000/api/datasources/uid/prometheus/health

Wurde eine Datenquelle nicht geladen, prüfe das Startlog von Grafana auf Zeilen des Provisioning-Loggers, die die Datei und den Fehler nennen (meist YAML-Einrückung, ein unbekanntes Feld oder eine fehlende Umgebungsvariable).