Das Verhalten des Grafana-Servers wird durch eine INI-Datei und durch Umgebungsvariablen gesteuert, die sie überschreiben. Wenn du die Regeln kennst, kannst du die gesamte Konfiguration in einem Repository halten und nichts von Hand ändern. Diese Anleitung behandelt, wo die Dateien liegen, wie die Rangfolge funktioniert, wie du Werte und Secrets einspeist und welche Einstellungen du am häufigsten anfasst.

Wo die Konfiguration liegt

• defaults.ini wird mit Grafana ausgeliefert und enthält jeden Standardwert (bei einer Tarball-Installation in conf/). Bearbeite sie nie. Sie ist die beste Referenz dafür, welche Optionen es gibt.
• grafana.ini ist deine Konfigurationsdatei. Bei Linux-Paketen ist es /etc/grafana/grafana.ini, und das offizielle Docker-Image liest denselben Pfad. Bei einer Tarball-Installation nutze conf/custom.ini. Mit --config verweist du auf eine andere Datei.
• Umgebungsvariablen mit dem Präfix GF_ überschreiben beides.

Rangfolge, von niedrig nach hoch: defaults.ini, dann deine grafana.ini, dann GF_*-Umgebungsvariablen (und Kommandozeilen-Flags). Trage in deine Datei nur die Optionen ein, die du ändern willst, das hält Diffs klein.

In einer INI-Datei sind Zeilen, die mit ; beginnen, Kommentare. Um eine Option zu aktivieren, entfernst du also das führende ;:

;http_port = 3000   # wird ignoriert
http_port = 3000    # aktiv

Starte Grafana nach Änderungen an der Datei oder der Umgebung neu.

Überschreiben per Umgebungsvariable

Das Muster ist GF_<SECTION>_<KEY>, wobei Section und Key in Großbuchstaben stehen und jedes . oder - durch _ ersetzt wird:

GF_SECURITY_ADMIN_USER=owner          # [security] admin_user
GF_SERVER_ROOT_URL=https://grafana.example.com   # [server] root_url
GF_AUTH_GOOGLE_CLIENT_SECRET=newS3cretKey        # [auth.google] client_secret
GF_FEATURE_TOGGLES_newNavigation=true            # [feature_toggles] newNavigation
GF_DEFAULT_INSTANCE_NAME=my-instance             # instance_name auf oberster Ebene, ohne Section

Umgebungsvariablen passen natürlich zu Containern und Kubernetes, weil dieselbe Datei von jeder Umgebung geteilt werden kann, während die umgebungsspezifischen Werte (URLs, Passwörter) von der Plattform kommen.

Variablen-Expansion innerhalb der Datei

Optionswerte können Umgebungsvariablen oder Dateien mit den Providern $__env{} und $__file{} oder der Kurzform ${NAME} referenzieren:

[paths]
logs = $__env{LOGDIR}/grafana

[security]
admin_password = ${GF_ADMIN_PASSWORD}
secret_key = $__file{/run/secrets/grafana_secret_key}

[database]
password = $__file{/etc/secrets/gf_sql_password}

$__file{} liest die Datei und entfernt führende und nachfolgende Leerzeichen, was gut zu als Dateien gemounteten Docker- und Kubernetes-Secrets passt. Grafana Enterprise hat zusätzlich einen $__vault{}-Provider. Das offizielle Docker-Image akzeptiert außerdem ein Suffix __FILE an Variablennamen (zum Beispiel GF_SECURITY_ADMIN_PASSWORD__FILE=/run/secrets/admin_password), das in der Anleitung zu Secrets behandelt wird.

Eine praktische Basis

Eine kurze grafana.ini für ein kleines, produktionsähnliches Setup:

[paths]
provisioning = /etc/grafana/provisioning

[server]
protocol = http
http_port = 3000
domain = grafana.example.com
root_url = https://grafana.example.com/
; füge den Unterpfad zu root_url hinzu und aktiviere dies, wenn unter /grafana ausgeliefert wird
; serve_from_sub_path = true

[database]
type = postgres
host = postgres:5432
name = grafana
user = grafana
password = $__file{/run/secrets/grafana_db_password}

[security]
admin_user = admin
admin_password = $__file{/run/secrets/grafana_admin_password}
secret_key = $__file{/run/secrets/grafana_secret_key}
cookie_secure = true

[users]
allow_sign_up = false

[analytics]
reporting_enabled = false
check_for_updates = false

[log]
mode = console
level = info

Wissenswerte Punkte:

• Datenbank. Der Standard ist SQLite, in Ordnung für eine einzelne Instanz und zum Testen. Nutze PostgreSQL oder MySQL für die Produktion, und immer bei mehr als einem Grafana-Replikat.
• root_url muss zur öffentlichen Adresse passen, sonst sind Links in Alert-Benachrichtigungen und OAuth-Redirects falsch. Hinter einem Reverse Proxy, der Grafana unter einem Unterpfad ausliefert, füge den Pfad zu root_url hinzu und setze serve_from_sub_path = true.
• admin_password wird nur angewendet, wenn Grafana erstmals seine Datenbank anlegt. Eine spätere Änderung der Einstellung ändert nicht das Passwort des bestehenden Admin-Benutzers.
• secret_key verschlüsselt die für Datenquellen gespeicherten Secrets. Ändert man ihn, können zuvor gespeicherte Secrets nicht mehr gelesen werden, und die Datenquellen müssen erneut provisioniert werden. Setze ihn explizit und rotiere ihn nie leichtfertig.
• [paths] provisioning ist der Ort, an dem Grafana nach Provisioning-Ordnern sucht. Der Standard ist bei Paketen /etc/grafana/provisioning.

SMTP für E-Mail-Alerts

[smtp]
enabled = true
host = smtp.example.com:587
user = grafana@example.com
password = $__file{/run/secrets/smtp_password}
from_address = grafana@example.com
from_name = Grafana
startTLS_policy = OpportunisticStartTLS

Oder dasselbe mit GF_SMTP_ENABLED=true, GF_SMTP_HOST=... und so weiter. Verifiziere die Optionsnamen gegen defaults.ini deiner Version.

Feature-Toggles

Experimentelle oder Opt-in-Funktionen werden in einem eigenen Abschnitt eingeschaltet:

[feature_toggles]
; liste die gewünschten Toggles auf, wie für deine Version dokumentiert
newNavigation = true

Bevorzuge die Datei oder die Umgebung gegenüber der UI, damit die Einstellung einen Neuaufbau übersteht. Toggles kommen und gehen zwischen Releases, prüfe sie also bei jedem Upgrade.

Die wirksame Konfiguration validieren und einsehen

Nach dem Start von Grafana kannst du vergleichen, was du gesetzt hast, mit dem, was wirksam ist:

curl -s -u admin:$GRAFANA_ADMIN_PASSWORD http://localhost:3000/api/admin/settings | jq '.server'

Dieser Admin-Endpunkt liefert die zusammengeführten Einstellungen, und Werte sensibler Schlüssel sind maskiert. Es ist der schnellste Weg zu bestätigen, dass eine Umgebungsvariable tatsächlich gewirkt hat. Falls nicht, prüfe die Schreibweise der Variable (Großbuchstaben, Unterstriche) und ob die Option in defaults.ini existiert.

In Git halten

• Committe grafana.ini und eine .env.example mit Platzhalterwerten.
• Halte echte Secrets aus dem Repository heraus: Mounte sie als Dateien, injiziere sie als Umgebungsvariablen oder committe sie verschlüsselt (siehe die Anleitung zu Secrets).
• Prüfe Änderungen an defaults.ini, wenn du Grafana upgradest. Neue Releases fügen Optionen hinzu und markieren manchmal alte als veraltet.