Grafana Provisioning : automatiser les dashboards et sources

1. Introduction au Provisioning Grafana #

Comprendre le concept et les avantages de la gestion de configuration 'as Code' pour Grafana.

Le principe du Provisioning #

Disponible dans : ✓ OSS ✓ Enterprise ✓ Cloud Fichiers de provisioning en auto-hébergé ; dans Grafana Cloud, préférez l’API ou Terraform

Le provisioning Grafana est une fonctionnalité qui permet de gérer la configuration de votre instance Grafana (sources de données, tableaux de bord, notificateurs, etc.) via des fichiers de configuration externes, généralement au format YAML. Au lieu de créer et de modifier ces éléments manuellement via l'interface utilisateur de Grafana, vous définissez leur état souhaité dans des fichiers qui sont ensuite lus et appliqués par Grafana au démarrage ou à intervalles réguliers.

Cela transforme la gestion de votre Grafana en une approche Infrastructure as Code (IaC), où l'état de votre plateforme est décrit dans des fichiers versionnés, auditables et reproductibles.

Pourquoi l'utiliser ? Les avantages clés #

• Automatisation et CI/CD : Intégrez la création et la mise à jour de vos configurations Grafana directement dans vos pipelines de livraison continue (CI/CD).
• Reproductibilité : Assurez-vous que tous vos environnements Grafana (développement, test, production) sont configurés de manière identique et cohérente.
• Versionnement : Suivez les modifications de vos configurations dans un système de contrôle de version (Git), permettant un audit facile et un retour arrière si nécessaire.
• Collaboration : Facilitez la collaboration entre les équipes en permettant aux développeurs et aux opérateurs de contribuer aux configurations Grafana via du code.
• Réduction des erreurs : Minimisez les erreurs manuelles et les dérives de configuration (configuration drift) en automatisant le processus.

2. Provisioning des Sources de Données (Data Sources) #

Automatisez la déclaration et la configuration de vos sources de données externes.

Utilité et structure du fichier de configuration #

Le provisioning des sources de données est essentiel pour garantir que votre instance Grafana puisse se connecter aux systèmes de monitoring (Prometheus, Elasticsearch, InfluxDB, etc.) dès son démarrage, sans intervention manuelle. Le fichier de configuration des sources de données est généralement placé dans le répertoire /etc/grafana/provisioning/datasources (ou un chemin similaire selon votre installation).

Chaque source de données est définie par un type, un nom, une URL, et des options spécifiques (authentification, version, etc.).

Exemples de configuration YAML #

Exemple de fichier pour provisionner des sources de données :

# /etc/grafana/provisioning/datasources/datasources.yaml
apiVersion: 1

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

  - name: Elasticsearch
    type: elasticsearch
    uid: elasticsearch_ds
    access: proxy
    url: https://elasticsearch:9200
    editable: false
    basicAuth: true
    basicAuthUser: grafana_user
    secureJsonData:
      basicAuthPassword: ${ES_PASSWORD}     # variable d'environnement, jamais en clair
    jsonData:
      index: "logs-*"
      timeField: "@timestamp"
      maxConcurrentShardRequests: 5

editable: false empêche les modifications par l'interface, et secureJsonData, alimenté par une variable d'environnement, garde les secrets hors du fichier.

À savoir : Le champ version d'une source de données est un numéro de révision de la configuration (un entier), pas la version d'Elasticsearch. L'ancien réglage numérique esVersion: 70 est déprécié : les versions récentes de Grafana détectent la version d'Elasticsearch, il n'est donc plus nécessaire de la déclarer.

3. Provisioning des Tableaux de Bord (Dashboards) #

Gérez vos visualisations et tableaux de bord de manière automatisée et versionnée.

Utilité et structure du fichier de configuration #

Le provisioning des tableaux de bord déploie automatiquement vos visualisations et les maintient à jour. Un fichier de providers placé dans /etc/grafana/provisioning/dashboards indique à Grafana où lire les fichiers JSON des dashboards et dans quel dossier les ranger.

Le provisioning par fichiers ne charge que des fichiers JSON locaux : il ne sait pas importer un dashboard de Grafana.com par son identifiant. Cette fonction est offerte par le chart Helm de Grafana (clé dashboards avec gnetId), qui télécharge le JSON avant le démarrage, ou par l'API d'import.

Exemples de configuration YAML #

Exemple de fichier de providers :

# /etc/grafana/provisioning/dashboards/dashboards.yaml
apiVersion: 1

providers:
  - name: applications
    orgId: 1
    folder: Mes applications
    type: file
    disableDeletion: true          # un dashboard supprimé du disque n'est pas supprimé de Grafana
    updateIntervalSeconds: 30      # relecture des fichiers
    allowUiUpdates: false          # modifications dans l'interface interdites (elles seraient écrasées)
    options:
      path: /var/lib/grafana/dashboards/applications
      foldersFromFilesStructure: false

  - name: infrastructure
    orgId: 1
    folder: Infrastructure
    type: file
    updateIntervalSeconds: 60
    allowUiUpdates: false
    options:
      path: /var/lib/grafana/dashboards/infrastructure

Les fichiers JSON des dashboards s'exportent depuis Grafana (Export > Export as JSON) et se déposent dans les répertoires indiqués par options.path.

Erreur Courante : La clé racine est providers:, et les réglages updateIntervalSeconds et allowUiUpdates se placent au niveau du provider, pas dans options. L'ancien réglage editable des providers est remplacé par allowUiUpdates.

4. Provisioning de l'alerting (points de contact et politiques) #

Déclarer points de contact, politiques de notification et règles d'alerte de Grafana Alerting.

Utilité et structure #

Depuis Grafana Alerting (alerting unifié), le dossier provisioning/notifiers et ses notifiers appartiennent à l'ancien alerting, retiré des versions récentes. On provisionne désormais des fichiers dans /etc/grafana/provisioning/alerting : contact points, notification policies, règles d'alerte, templates et mute timings.

Bonne Pratique : Le plus simple pour obtenir un fichier correct : configurer l'élément dans l'interface, puis utiliser Export (format YAML de provisioning) depuis la page des points de contact, des politiques ou des règles.

Exemples de configuration YAML #

Exemple : un point de contact Slack et la politique racine.

# /etc/grafana/provisioning/alerting/notifications.yaml
apiVersion: 1

contactPoints:
  - orgId: 1
    name: equipe-ops
    receivers:
      - uid: slack-ops
        type: slack
        settings:
          url: ${SLACK_WEBHOOK_URL}
          recipient: "#alertes"

policies:
  - orgId: 1
    receiver: equipe-ops
    group_by: [grafana_folder, alertname]
    group_wait: 30s
    group_interval: 5m
    repeat_interval: 4h

Comme pour les sources de données, l'URL du webhook vient d'une variable d'environnement ou d'un secret, jamais du fichier versionné.

5. Autres types de Provisioning et Bonnes Pratiques #

Élargir le champ d'application du provisioning et adopter les meilleures pratiques.

Plugins, utilisateurs et équipes #

• Plugins : on les installe (variable GF_INSTALL_PLUGINS, CLI, chart Helm) ; les applications de plugins se provisionnent dans provisioning/plugins.
• Utilisateurs et équipes : Grafana ne permet pas de les provisionner par fichiers YAML. On les gère par l'API HTTP, par le fournisseur Terraform grafana/grafana (grafana_user, grafana_team), ou mieux par la synchronisation d'un annuaire (LDAP, OAuth, SAML, SCIM).

resource "grafana_team" "ops" {
  name    = "Ops"
  members = ["alice@example.com", "bob@example.com"]
}

Bonnes pratiques pour un Provisioning efficace #

• Versionnez tout : Stockez tous vos fichiers de provisioning dans un dépôt Git.
• Utilisez des secrets : Ne mettez jamais d'informations sensibles (mots de passe, clés API) directement dans les fichiers de configuration. Utilisez des variables d'environnement, des secrets Kubernetes, ou un coffre-fort de secrets (Vault).
• Intégrez au CI/CD : Automatisez le déploiement de vos configurations Grafana à chaque changement de code ou de déploiement d'application.
• Testez vos configurations : Validez vos fichiers YAML avant de les déployer en production.
• Documentation : Documentez clairement la structure de vos fichiers de provisioning et les conventions de nommage utilisées.