Le comportement du serveur Grafana est contrôlé par un fichier INI et par des variables d’environnement qui le surchargent. Connaître les règles vous permet de conserver toute la configuration dans un dépôt et de ne rien changer à la main. Ce guide couvre l’emplacement des fichiers, le fonctionnement de la priorité, la manière d’injecter des valeurs et des secrets, ainsi que les paramètres que vous modifierez le plus souvent.

Où vit la configuration

• defaults.ini est livré avec Grafana et contient toutes les valeurs par défaut (dans conf/ pour une installation par archive tarball). Ne le modifiez jamais. C’est la meilleure référence pour savoir quelles options existent.
• grafana.ini est votre fichier de configuration. Sur les paquets Linux, il se trouve à /etc/grafana/grafana.ini, et l’image Docker officielle lit le même chemin. Pour une installation tarball, utilisez conf/custom.ini. Passez --config pour pointer vers un autre fichier.
• Les variables d’environnement commençant par GF_ surchargent les deux.

Priorité, de la plus basse à la plus haute : defaults.ini, puis votre grafana.ini, puis les variables d’environnement GF_* (et les options de ligne de commande). Ne mettez dans votre fichier que les options que vous voulez changer, ce qui garde les diffs petits.

Dans un fichier INI, les lignes commençant par ; sont des commentaires ; pour activer une option, il faut donc retirer le ; initial :

;http_port = 3000   # ignoré
http_port = 3000    # actif

Redémarrez Grafana après avoir modifié le fichier ou l’environnement.

Surcharges par variables d’environnement

Le modèle est GF_<SECTION>_<CLÉ>, avec la section et la clé en majuscules et tout . ou - remplacé par _ :

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 de premier niveau, sans section

Les variables d’environnement conviennent naturellement aux conteneurs et à Kubernetes, car le même fichier peut être partagé par tous les environnements tandis que les valeurs propres à chacun (URL, mots de passe) viennent de la plateforme.

Expansion de variables dans le fichier

Les valeurs des options peuvent référencer des variables d’environnement ou des fichiers avec les fournisseurs $__env{} et $__file{}, ou le raccourci ${NAME} :

[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{} lit le fichier et supprime les espaces en début et en fin, ce qui le rend adapté aux secrets Docker et Kubernetes montés sous forme de fichiers. Grafana Enterprise dispose aussi d’un fournisseur $__vault{}. L’image Docker officielle accepte en plus un suffixe __FILE sur les noms de variables (par exemple GF_SECURITY_ADMIN_PASSWORD__FILE=/run/secrets/admin_password), traité dans le guide sur les secrets.

Une base pratique

Un court grafana.ini pour une installation modeste de type production :

[paths]
provisioning = /etc/grafana/provisioning

[server]
protocol = http
http_port = 3000
domain = grafana.example.com
root_url = https://grafana.example.com/
; ajoutez le sous-chemin à root_url et activez ceci si servi depuis /grafana
; 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

Points à connaître :

• Base de données. La valeur par défaut est SQLite, qui convient à une instance unique et aux tests. Utilisez PostgreSQL ou MySQL en production, et toujours au-delà d’un réplica Grafana.
• root_url doit correspondre à l’adresse publique, faute de quoi les liens dans les notifications d’alerte et les redirections OAuth seront erronés. Derrière un reverse proxy qui sert Grafana sous un sous-chemin, ajoutez le chemin à root_url et définissez serve_from_sub_path = true.
• admin_password n’est appliqué qu’à la première création de la base de données par Grafana. Modifier le paramètre ensuite ne change pas le mot de passe de l’utilisateur admin existant.
• secret_key chiffre les secrets stockés pour les sources de données. Si vous le changez, les secrets précédemment stockés ne peuvent plus être lus et les sources de données doivent être provisionnées à nouveau. Définissez-le explicitement et ne le faites jamais tourner à la légère.
• [paths] provisioning est l’endroit où Grafana cherche les dossiers de provisionnement. La valeur par défaut est /etc/grafana/provisioning sur les paquets.

SMTP pour les alertes par e-mail

[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

Ou la même chose avec GF_SMTP_ENABLED=true, GF_SMTP_HOST=..., et ainsi de suite. Vérifiez les noms d’options dans defaults.ini pour votre version.

Feature toggles

Les fonctionnalités expérimentales ou optionnelles s’activent dans une section dédiée :

[feature_toggles]
; listez les toggles voulus, tels que documentés pour votre version
newNavigation = true

Préférez le fichier ou l’environnement à l’interface, afin que le paramètre survive à une reconstruction. Les toggles apparaissent et disparaissent d’une version à l’autre : passez-les en revue à chaque mise à niveau.

Valider et inspecter la configuration effective

Après le démarrage de Grafana, vous pouvez comparer ce que vous avez défini avec ce qui est effectivement en vigueur :

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

Ce endpoint d’administration renvoie les paramètres fusionnés, les valeurs des clés sensibles étant masquées. C’est le moyen le plus rapide de confirmer qu’une variable d’environnement a bien pris effet. Si ce n’est pas le cas, vérifiez l’orthographe de la variable (majuscules, tirets bas) et que l’option existe dans defaults.ini.

Gardez tout dans Git

• Commitez grafana.ini et un .env.example avec des valeurs fictives.
• Gardez les vrais secrets hors du dépôt : montez-les sous forme de fichiers, injectez-les comme variables d’environnement, ou commitez-les chiffrés (voir le guide sur les secrets).
• Examinez les changements de defaults.ini lors des mises à niveau de Grafana. Les nouvelles versions ajoutent des options et en déprécient parfois d’anciennes.