Ce guide lance Grafana et une source de données Prometheus en local avec Docker Compose, chaque paramètre étant fourni par des fichiers et des variables d’environnement. Vous n’ouvrez jamais l’interface pour configurer quoi que ce soit. Vous avez besoin de Docker avec le plugin Compose.

Organiser le projet

grafana-as-code/
├── compose.yaml
├── .env                          # secrets et versions, non commité
├── grafana/
│   ├── grafana.ini
│   └── provisioning/
│       ├── datasources/
│       │   └── prometheus.yaml
│       ├── dashboards/
│       │   └── providers.yaml
│       ├── alerting/             # ajouté dans le guide sur l'alerting
│       └── plugins/
├── dashboards/
│   └── overview.json
└── prometheus/
    └── prometheus.yml

Conservez cela dans Git. Ajoutez .env au .gitignore et commitez plutôt un .env.example.

Le fichier compose

compose.yaml :

services:
  grafana:
    image: grafana/grafana:13.1.0   # épinglez une version que vous avez testée
    ports:
      - "3000:3000"
    environment:
      GF_SECURITY_ADMIN_USER: admin
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD}
      GF_USERS_ALLOW_SIGN_UP: "false"
    volumes:
      - ./grafana/grafana.ini:/etc/grafana/grafana.ini:ro
      - ./grafana/provisioning:/etc/grafana/provisioning:ro
      - ./dashboards:/var/lib/grafana/dashboards:ro
      - grafana-data:/var/lib/grafana
    depends_on:
      - prometheus

  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro

volumes:
  grafana-data:

Les montages importants :

• /etc/grafana/grafana.ini est le fichier de configuration du serveur à l’intérieur de l’image officielle.
• /etc/grafana/provisioning est l’endroit où Grafana cherche les dossiers datasources, dashboards, alerting et plugins.
• /var/lib/grafana/dashboards est un dossier arbitraire pour le JSON des tableaux de bord. Le chemin doit correspondre à celui que vous définissez dans le fournisseur de tableaux de bord ci-dessous.
• grafana-data est un volume nommé pour la base SQLite de Grafana et les plugins. Sans lui, l’état est perdu lorsque le conteneur est recréé.

Les montages de configuration sont en lecture seule volontairement : Grafana n’a pas besoin d’y écrire.

.env :

GRAFANA_ADMIN_PASSWORD=change-me-before-sharing

Notez que GF_SECURITY_ADMIN_PASSWORD n’est appliqué qu’à la première création de la base de données par Grafana. Le modifier plus tard dans le fichier compose n’a aucun effet sur un volume existant. Supprimez le volume pour repartir de zéro, ou réinitialisez le mot de passe avec la CLI.

Un grafana.ini minimal

[server]
http_port = 3000

[analytics]
reporting_enabled = false
check_for_updates = false

[log]
mode = console
level = info

[auth]
disable_login_form = false

Tout ce que vous omettez retombe sur les valeurs par défaut de Grafana. Le guide suivant couvre l’ensemble des règles pour grafana.ini et les surcharges GF_*.

Provisionner une source de données

grafana/provisioning/datasources/prometheus.yaml :

apiVersion: 1

datasources:
  - name: Prometheus
    uid: prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    editable: false

L’uid est ce que les tableaux de bord et les règles d’alerte doivent référencer, choisissez-en donc un stable. Les guides suivants expliquent chaque champ.

Provisionner un fournisseur de tableaux de bord et un tableau de bord

grafana/provisioning/dashboards/providers.yaml :

apiVersion: 1

providers:
  - name: default
    type: file
    updateIntervalSeconds: 30
    allowUiUpdates: false
    options:
      path: /var/lib/grafana/dashboards

dashboards/overview.json (un tableau de bord minimal ; voir le guide sur les tableaux de bord pour les détails) :

{
  "uid": "overview",
  "title": "Overview",
  "schemaVersion": 39,
  "panels": [
    {
      "id": 1,
      "type": "timeseries",
      "title": "Targets up",
      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
      "datasource": { "type": "prometheus", "uid": "prometheus" },
      "targets": [
        { "refId": "A", "expr": "up", "datasource": { "type": "prometheus", "uid": "prometheus" } }
      ]
    }
  ]
}

Et un petit prometheus/prometheus.yml pour qu’il y ait des données à afficher :

global:
  scrape_interval: 15s
scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ["localhost:9090"]

Démarrer et vérifier sans l’interface

docker compose up -d
docker compose logs grafana | grep -i provisioning
curl -s http://localhost:3000/api/health
curl -s -u admin:$GRAFANA_ADMIN_PASSWORD http://localhost:3000/api/datasources | jq '.[].name'
curl -s -u admin:$GRAFANA_ADMIN_PASSWORD "http://localhost:3000/api/search?type=dash-db" | jq '.[].title'

Le endpoint de santé doit renvoyer ok, la liste des sources de données doit contenir Prometheus, et la recherche doit renvoyer Overview. Ouvrez http://localhost:3000 si vous voulez voir le résultat, mais rien n’a été cliqué pour en arriver là.

Modifier quelque chose et le voir s’appliquer

• Modifiez dashboards/overview.json. Dans le délai updateIntervalSeconds, Grafana prend en compte le changement sans redémarrage.
• Modifiez le fichier de source de données et redémarrez : docker compose restart grafana. Les sources de données sont lues au démarrage.
• Supprimez un fichier de tableau de bord. Le tableau de bord est supprimé, sauf si le fournisseur définit disableDeletion: true.

Installer des plugins depuis la configuration

Les plugins peuvent être installés au démarrage du conteneur via une variable d’environnement, ils restent donc dans le fichier compose :

    environment:
      GF_PLUGINS_PREINSTALL: grafana-clock-panel

Les versions plus anciennes utilisent GF_INSTALL_PLUGINS à la place. Consultez la documentation de votre version, et notez que le provisionnement ne fait que configurer des plugins déjà installés.

Nettoyer

docker compose down        # conserve le volume de données
docker compose down -v     # supprime aussi la base de données de Grafana