Les sources de données sont la première chose dont dépendent tous les tableaux de bord et toutes les règles d’alerte, c’est donc la première chose à mettre dans des fichiers. Grafana lit le YAML du dossier provisioning/datasources au démarrage, crée les sources de données qu’il trouve et met à jour celles qui existent déjà.

Un fichier de base

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

Vous pouvez placer une ou plusieurs sources de données dans un fichier, et utiliser plusieurs fichiers. Grafana charge tout ce qui se trouve sous le dossier.

Les champs les plus importants :

• name est le nom affiché.
• uid est l’identifiant stable que les tableaux de bord et les règles d’alerte référencent. Si vous l’omettez, Grafana en génère un, ce qui fragilise tout ce qui le référence. Définissez-le toujours.
• type est l’ID du plugin, tel que prometheus, loki, tempo, postgres ou elasticsearch.
• access: proxy signifie que le serveur de Grafana effectue les requêtes. C’est le choix normal, qui garde les identifiants hors des navigateurs.
• isDefault marque la source de données avec laquelle démarrent les nouveaux panneaux. Une seule devrait être la valeur par défaut par organisation.
• editable: false bloque les modifications dans l’interface, de sorte que le fichier reste l’autorité.
• jsonData contient les paramètres non secrets, dont les clés dépendent du plugin.
• secureJsonData contient les secrets, que Grafana chiffre dans sa base de données.
• version est comparé lors des mises à jour. Quand plusieurs instances Grafana partagent une base de données, une instance ne met à jour une source de données que si la version du fichier est égale ou supérieure à celle stockée ; incrémentez-la donc quand vous modifiez un fichier.

Des identifiants sans les commiter

Les fichiers de provisionnement prennent en charge l’interpolation de variables d’environnement dans les valeurs (pas dans les clés) avec $VAR ou ${VAR}. Écrivez $$ pour un signe dollar littéral :

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

Passez POSTGRES_PASSWORD au conteneur depuis votre gestionnaire de secrets (voir le guide sur les secrets). Le mot de passe n’apparaît jamais dans le dépôt, et Grafana le stocke chiffré après le chargement.

En-têtes HTTP personnalisés

Les noms d’en-têtes vont dans jsonData et leurs valeurs dans secureJsonData, numérotés ensemble :

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

Authentification basique et 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

Corréler logs, métriques et traces

Plusieurs plugins relient les sources de données entre elles par UID, ce qui est une raison de plus de définir les UID à la main. Par exemple, Loki peut transformer un champ de log en lien vers des traces dans Tempo :

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

Les clés jsonData propres à chaque plugin varient selon la version ; confirmez-les dans la documentation de la source de données. Un moyen rapide de les découvrir consiste à configurer la source de données une fois dans une instance de test et à lire le résultat via l’API (GET /api/datasources/uid/<uid>).

Supprimer et élaguer

deleteDatasources supprime des sources de données avant le traitement de datasources. Utilisez-le quand vous retirez l’une d’elles :

apiVersion: 1

deleteDatasources:
  - name: Old Graphite
    orgId: 1

Pour faire du dossier la vérité complète, ajoutez prune: true (Grafana 11.1 ou plus récent). Les sources de données provisionnées qui ne figurent plus dans aucun fichier, ou dont le fichier est supprimé, sont alors retirées au prochain démarrage :

apiVersion: 1
prune: true

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

Seules les sources de données provisionnées sont élaguées. Celles créées à la main dans l’interface sont laissées intactes.

Appliquer et vérifier

Les sources de données sont lues au démarrage ; redémarrez donc Grafana, ou appelez le endpoint de rechargement avec l’authentification basique admin :

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}'

Les sources de données provisionnées renvoient readOnly: true. Pour confirmer la connectivité sans l’interface, utilisez le endpoint de santé de la source de données :

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

Si une source de données ne s’est pas chargée, consultez le log de démarrage de Grafana : les lignes du logger de provisionnement nomment le fichier et l’erreur (généralement une indentation YAML, un champ inconnu ou une variable d’environnement manquante).