Rôle Ansible :rainbow: :bar_chart: Grafana

Table des matières

• Plateformes supportées
• Exigences
• Variables du rôle
  • Installation
  • Configuration
  • Lancement
  • Désinstallation
• Dépendances
• Exemple de Playbook
• Licence
• Informations sur l'auteur

Rôle Ansible qui installe et configure Grafana : une plateforme d’analyse et de surveillance.

Plateformes supportées :

* Debian
* Redhat (CentOS/Fedora)
* Ubuntu

Exigences

Nécessite l'outil unzip/gtar installé sur l'hôte cible. Voir les notes du module ansible unarchive ici pour plus de détails. Également, en raison de l'utilisation de la fonctionnalité provisioning introduite dans la version 5.0, les versions >= 5.0 de Grafana sont nécessaires pour une exécution correcte.

Variables du rôle

Les variables sont disponibles et organisées selon les différentes étapes de provisionnement du logiciel et de la machine :

• install
• config
• launch
• uninstall

Installation

grafana peut être installé en utilisant des archives compressées (.tar, .zip) ainsi que des paquets de distribution DEB et RPM, téléchargés et extraits à partir de diverses sources.

Les variables suivantes peuvent être personnalisées pour contrôler différents aspects de ce processus d'installation, allant de la version du logiciel à l'emplacement de stockage des binaires, en passant par le répertoire d'installation :

grafana_user: <nom-utilisateur-service> (défaut : grafana)

grafana_group: <nom-groupe-service> (défaut : grafana)

• utilisateur et groupe de service dédiés utilisés par grafana pour la séparation des privilèges (voir ici pour plus de détails)

install_type: <package | archive> (défaut : archive)

• package : supporté par les distributions Debian et Redhat, l'installation par paquet de Grafana récupère le paquet spécifié dans le dépôt de gestion des paquets correspondant.

  • Notez que le répertoire d'installation est déterminé par le système de gestion des paquets et par défaut se situe sous /usr/{sbin,lib, share} pour toutes les distributions.

• archive : compatible avec les formats tar et zip, les binaires d'installation archivés peuvent être obtenus à partir d'archives compressées locales et distantes, soit à partir de l'index des versions officielles, soit à partir de sources de développement/personnalisées.

install_dir: </chemin/vers/le/répertoire/d'installation> (défaut : /opt/grafana)

• chemin sur l'hôte cible où les binaires de grafana doivent être extraits.

archive_url: <chemin-ou-url-vers-l'archive> (défaut : voir defaults/main.yml)

• adresse d'une archive compressée tar ou zip contenant des binaires de grafana. Cette méthode permet techniquement d'installer n'importe quelle version disponible de grafana. Des liens vers les versions officielles peuvent être trouvés ici.

archive_checksum: <chemin-ou-url-vers-le-checksum> (défaut : voir defaults/main.yml)

• adresse d'un fichier de checksum pour vérifier l'intégrité des données de l'archive grafana spécifiée. Bien que recommandé et généralement considéré comme une bonne pratique, la spécification d'un checksum n'est pas obligatoire et peut être désactivée en fournissant une chaîne vide ('') pour sa valeur.

checksum_format: <chaîne> (défaut : voir sha256)

• algorithme de hachage utilisé pour la vérification de fichier associé au checksum de l'archive spécifiée. Référez-vous ici pour plus d'informations sur les checksums/cryptographic hachages.

package_url: <chemin-ou-url-vers-le-paquet> (défaut : voir defaults/main.yml)

• adresse d'un paquet debian (DEB) ou RPM contenant des binaires de grafana. Des liens vers les versions officielles peuvent être trouvés ici.

package_checksum: <chemin-ou-url-vers-le-checksum> (défaut : voir defaults/main.yml)

• adresse d'un fichier de checksum pour vérifier l'intégrité des données du paquet grafana spécifié. Bien que recommandé et généralement considéré comme une bonne pratique, la spécification d'un checksum n'est pas obligatoire et peut être désactivée en fournissant une chaîne vide ('') pour sa valeur.

Config

En utilisant ce rôle, la configuration d'une installation grafana est organisée selon les composants suivants :

• configuration du service grafana (grafana.ini)
• provisionnement des sources de données (provisioning/datasources - *.[json|yml])
• provisionnement des tableaux de bord (provisioning/dashboards - *.[json|yml])
• configuration des notifications (provisioning/notifiers - [json|yml])

Chaque configuration peut être exprimée dans les variables suivantes pour personnaliser le contenu et les paramètres des fichiers de configuration désignés à rendre :

config_dir: </chemin/vers/le/répertoire/de/configuration> (défaut : {{ install_dir }})

• chemin sur l'hôte cible où le fichier de configuration grafana doit être rendu.

provision_configs: <['datasources', 'dashboards' et/ou 'notifiers']> (défaut : [])

• liste des composants de provisionnement Grafana à configurer. Voir ici pour plus de détails.

Configuration du service Grafana

La configuration du service Grafana se trouve dans un fichier INI, grafana.ini par défaut, qui définit un ensemble de comportements de service organisés par section représentant l'administration générale et divers aspects liés au fournisseur de contenu du service Grafana.

Ces sections et paramètres peuvent être exprimés dans le hachage grafana_config, indexé par section de configuration avec des dictionnaires comme valeurs représentant les spécifications de la section de configuration (par exemple, le chemin pour stocker le fichier de base de données sqlite3 - activé par défaut). Ce qui suit fournit un aperçu et des exemples de configuration de chaque section pour référence.

:paths

[grafana_config:] path: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres liés à l'endroit où Grafana stocke les artefacts et les données variables

 grafana_config:
   # section [paths]
   paths:
     # option de section 1 - chemin de la base de données sqlite
     data: /mnt/data/grafana
     # option de section 2 - chemin pour stocker les logs
     logs: /mnt/logs/grafana

[grafana_config:] server: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres liés à la manière dont Grafana interagit sur le réseau

 grafana_config:
   # section [server]
   server:
     http_addr: 127.0.0.1
     http_port: 3030

:database

[grafana_config:] database: <clé: valeur,...> (défaut : voir section documentation)

• spécifie des paramètres qui contrôlent comment Grafana interagit avec l'un des types de stockage de backend disponibles (c'est-à-dire mysql, postgres et sqlite)

 grafana_config:
   # section [database]
   database:
     type: mysql
     host: 127.0.0.1:3306
     name: grafana-test
     user: mysql-admin
     password: PASSWORD

:remote_cache

[grafana_config:] remote_cache: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres qui contrôlent comment Grafana interagit avec l'un des types de cache distant disponibles (c'est-à-dire redis, memcached et database)

 grafana_config:
   # section [remote_cache]
   remote_cache:
     type: redis
     connstr: addr=127.0.0.1:6379,pool_size=100,db=0,ssl=false

:security

[grafana_config:] security: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres qui gèrent l'authentification et l'autorisation des utilisateurs/organisations Grafana

  grafana_config:
    # section [security]
    security:
      admin_user: sre-user
      admin_password: PASSWORD
      login_remember_days: 7

:users

[grafana_config:] users: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres qui contrôlent les capacités des utilisateurs Grafana

  grafana_config:
    # section [users]
    users:
      allow_sign_up: true
      allow_org_create: false
      login_hint: CECI EST UN INDICE

:auth

[grafana_config:] auth: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres qui régulent les capacités d'autorisation des utilisateurs

Grafana fournit plusieurs méthodes pour authentifier les utilisateurs et les paramètres pour chaque méthode sont exprimés dans les sections [auth.<méthode>] selon le besoin, permettant une authentification allant de l'authentification utilisateur basique à OAuth via Google & Github.

  grafana_config:
    # section [auth.github] - REMARQUE : **github** représente la méthode d'authentification
    auth.github:
      enabled: true
      allow_sign_up: true
      client_id: YOUR_GITHUB_APP_CLIENT_ID
      client_secret: YOUR_GITHUB_APP_CLIENT_SECRET
      scopes: user:email,read:org
      auth_url: https://github.com/login/oauth/authorize
      token_url: https://github.com/login/oauth/access_token
      api_url: https://api.github.com/user

:dataproxy

[grafana_config:] dataproxy: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres qui activent la journalisation du proxy de données

  grafana_config:
    # section [dataproxy]
    dataproxy:
      logging: true
      timeout: 60
      send_user_header: true

:analytics

[grafana_config:] analytics: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres qui activent la collecte et le rapport des statistiques d'utilisation

  grafana_config:
    # section [analytics]
    analytics:
      reporting_enabled: true
      google_analytics_ua_id: UA_ID
      check_for_updates: true

:dashboards

[grafana_config:] dashboards: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres qui régulent la politique d'entretien des tableaux de bord de Grafana

  grafana_config:
    # section [dashboards]
    dashboards:
      versions_to_keep: 5

:smtp

[grafana_config:] smtp: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres du serveur de messagerie pour l'identité ainsi que les alertes/notifications

  grafana_config:
    # section [smtp]
    smtp:
      enabled: true
      host: 127.0.0.1:65
      user: smtp-user
      password: PASSWORD

:log

[grafana_config:] log: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres de journalisation (par exemple, le niveau de journalisation et les modes ou canaux de sortie des journaux)

  grafana_config:
    # section [log]
    log:
      mode: console
      level: debug

:metrics

[grafana_config:] metrics: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres pour gérer l'émission de télémétrie de Grafana

  grafana_config:
    # section [metrics]
    metrics:
      enabled: true
      interval_seconds: 5s
    metrics.graphite:
      address: 127.0.0.1:7070

:snapshots

[grafana_config:] snapshots: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres pour gérer le comportement de publication de la fonctionnalité d'instantané de tableau de bord interactif de Grafana

  grafana_config:
    # section [snapshots]
    snapshots:
      external_enabled: true
      external_snapshot_name: ENDPOINT

:external_image_storage

[grafana_config:] external_image_storage: <clé: valeur,...> (défaut : voir section documentation)

• spécifie des paramètres pour contrôler comment les images doivent être rendues publiques pour un partage sur des services comme Slack

Grafana prend en charge plusieurs fournisseurs de stockage backend pour lesquels des configurations individuelles peuvent être exprimées dans les sections [external_image_storage.] selon le besoin, permettant un stockage à distance sur des services comme s3, gcs, azure blob et stockage local.

  grafana_config:
    # section [external_image_storage]
    external_image_storage:
      external_enabled: true
      external_snapshot_name: Publish to ENDPOINT
    external_image_storage.s3:
      endpoint: http://example.org.s3/
      bucket: grafana-snapshots
      region: us-east-1
      path: ${HOSTNAME}
      access_key: ACCESS_KEY
      secret_key: SECRET_KEY

:alerting

[grafana_config:] alerting: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres pour gérer le moteur d'alerte de Grafana et le comportement/règles

  grafana_config:
    # section [alerting]
    alerting:
      enabled: true
      execute_alerts: true
      nodata_or_nullvalues: no_data
      evaluation_timeout_seconds: 10
      notification_timeout_seconds: 60
      max_attempts: 5

:rendering

[grafana_config:] rendering: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres pour faire fonctionner un service de rendu HTTP à distance

  grafana_config:
    # section [rendering]
    rendering:
      server_url: http://localhost:8081/render
      callback_url: http://grafana.open.domain

:plugins

[grafana_config:] plugins: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres pour gérer la disponibilité et l'accessibilité des plugins Grafana

  grafana_config:
    # section [plugins]
    plugins:
      enable_alpha: true

:feature_toggles

[grafana_config:] feature_toggles: <clé: valeur,...> (défaut : voir section documentation)

• spécifie des paramètres pour activer l'utilisation de fonctionnalités alpha par l'instance Grafana, délimitées par des espaces

  grafana_config:
    # section [feature_toggles]
    features_toggles:
      enable: transformations

:tracing.jaeger

[grafana_config:] tracing.jaegar: <clé: valeur,...> (défaut : voir section documentation)

• spécifie les paramètres pour configurer le client Jaegar de Grafana pour le traçage distribué.

Remarque : les variables d'environnement standard de Jaegar, préfixées par JAEGAR_*, peuvent toujours être spécifiées et remplaceront tout paramètre fourni ici.

  grafana_config:
    # section [tracing.jaegar]
    tracing.jaegar:
      address: http://localhost:6381
      always_included_tag: key1:value1,key2:value2

Sources de données

Grafana prend en charge de nombreux backends de stockage de vos données temporelles connus sous le nom de sources de données. Chaque source de données peut être configurée dans un ensemble de fichiers de configuration json|yml sous le répertoire de provisioning de Grafana, qui peut être ajusté dans la section [paths] du grafana.ini.

Ces configurations de sources de données peuvent être exprimées dans le hachage grafana_datasources. Ce hachage contient une liste de structures de sources de données à activer et une autre pour les supprimer, indexées par datasources et deleteDatasources, respectivement. Les valeurs elles-mêmes consistent en une liste de dictionnaires représentant des spécifications individuelles de sources de données. Voir ici pour plus de détails et une liste des sources de données prises en charge.

grafana_datasources: <liste-de-dictionnaires> (défaut : [])

• spécifie les définitions de source de données Grafana à rendre. Voir ici pour un aperçu des sources de données disponibles de la communauté et leurs options respectives.

grafana_datasources: name: <chaîne> (défaut : obligatoire)

• nom du fichier de source de données de Grafana à rendre

grafana_datasources: <entrée> : datasources: <liste-de-dictionnaires> (défaut : [])

• liste des définitions de sources de données (basée sur la liste prise en charge mentionnée ci-dessus) à rendre dans le fichier de configuration

grafana_datasources: <entrée> : deleteDatasources: <liste-de-dictionnaires> (défaut : [])

• liste des définitions de sources de données précédemment importées à supprimer (basée sur la liste prise en charge mentionnée ci-dessus) à rendre dans le fichier de configuration

 grafana_datasources:
 - name: example_datasource
   datasources:
     - name: elasticsearch-logs
       type: elasticsearch
       access: proxy
       database: "[logs-]YYYY.MM.DD"
       url: http://localhost:9200
       jsonData:
         interval: Daily
         timeField: "@timestamp"
         esVersion: 70
         logMessageField: message
         logLevelField: fields.level
     - name: prometheus_example
       type: prometheus
       access: proxy
       url: http://localhost:9090
   deleteDatasources:
     - name: graphite-legacy
       type: graphite
       access: proxy
       url: http://localhost:8080
       jsonData:
         graphiteVersion: "1.1"

Depuis la version 5.0, Grafana a permis d'ajouter un ou plusieurs fichiers de configuration yaml|json dans le répertoire provisioning/dashboards. Cela permettant à Grafana de charger les tableaux de bord à partir du système de fichiers local, ce répertoire peut contenir une liste de fournisseurs de tableaux de bord qui indique les caractéristiques et différentes formes de métadonnées concernant le répertoire/fichier à partir duquel charger.

Ces configurations de fournisseurs de tableaux de bord peuvent être exprimées dans le hachage grafana_dashboards, qui est composé d'une liste des structures de fournisseurs de tableaux de bord mentionnées précédemment. Voir ici pour plus de détails et une liste de tableaux de bord créés par la communauté disponibles pour téléchargement et importation.

grafana_dashboards: <liste-de-dictionnaires> (défaut : [])

• spécifie les définitions de fournisseur de tableaux de bord Grafana à rendre. Voir ici pour un aperçu des options prises en charge.

grafana_dashboards: <entrée> : name: <chaîne> (défaut : obligatoire)

• nom du fichier de fournisseur de tableaux de bord de Grafana à rendre

grafana_dashboards: <entrée> : apiVersion: <chaîne> (défaut : [])

• nom de la version du fichier de fournisseur de tableaux de bord Grafana (utile pour la synchronisation entre les instances)

grafana_dashboards: <entrée> : providers: <liste-de-dictionnaires> (défaut : [])

• liste des définitions de fournisseurs de tableaux de bord à rendre dans le fichier de configuration

[grafana_dashboards: <entrée> : urls: <entrée>:] name <chaîne> (défaut : obligatoire)

• nom du fichier JSON pour stocker la configuration/contenu du tableau de bord

[grafana_dashboards: <entrée> : urls: <entrée>:] src <chaîne> (défaut : [])

• URL ou adresse web pour localiser et télécharger le fichier/content JSON

[grafana_dashboards: <entrée> : urls: <entrée>:] id (défaut : [])

• identifiant unique pour référencer le tableau de bord à télécharger depuis le hub communautaire officiel de Grafana

[grafana_dashboards: <entrée> : urls: <entrée>:] dest (défaut : {{ provisioning_dir }}/dashboards)

• emplacement sur le système de fichiers de l'hôte pour stocker la définition JSON du tableau de bord

Remarque : l'un de _.src ou _.id pour l'identification et la localisation du tableau de bord est obligatoire.

  grafana_dashboards:
    - name: test-example
      apiVersion: 2
      urls:
        - name: node_exporter_prometheus
          src: https://grafana.com/api/dashboards/11173/revisions/1/download
        - name: geth_server
          id: '6976'
      providers:
        - name: 'default-example'
          folder: 'default'
          folderUid: 1
          type: file
          disableDeletion: true
          updateIntervalSeconds: 30
          options:
            path: /var/lib/grafana/conf/provisioning/dashboards

Notifications

Les canaux de notification d'alerte peuvent être provisionnés en ajoutant un ou plusieurs fichiers de configuration yaml|json dans le répertoire provisioning/notifiers.

Chaque fichier de configuration peut être exprimé dans le hachage grafana_notifiers contenant les champs de niveau supérieur suivants :

• notifiers, une liste des notifications d'alerte qui seront ajoutées ou mises à jour lors du démarrage. Si le canal de notification existe déjà, Grafana le mettra à jour pour correspondre au fichier de configuration.
• delete_notifiers, une liste des notifications d'alerte à supprimer avant d'insérer/mettre à jour celles de la liste de notifiers.

Le provisionnement recherche les notifications d'alerte par uid, et mettra à jour toute notification existante avec le uid fourni.

grafana_notifiers: <liste-de-dictionnaires> (défaut : [])

• spécifie les définitions de notificateurs Grafana à rendre. Voir ici pour un aperçu des options prises en charge.

grafana_notifiers: <entrée> : name: <chaîne> (défaut : obligatoire)

• nom du fichier notificateur d'alerte Grafana à rendre

grafana_notifiers: <entrée> : notifiers: <chaîne> (défaut : [])

• liste des notificateurs d'alerte Grafana à activer pour une instance de Grafana

grafana_notifiers: <entrée> : delete_notifiers: <liste-de-dictionnaires> (défaut : [])

• liste des notificateurs d'alerte Grafana à supprimer d'une instance de Grafana

  grafana_notifiers:
    - name: slack-example
      notifiers:
        - name: example-org-slack
          url: http://slack.example.org
          recipient: team-channel
        - name: example-org-pagerduty
          integrationKey: PAGER_DUTY_KEY
      delete_notifiers:
        - name: example-org-email
          addresses: [email protected],[email protected]

Plugins

Grafana prend en charge les plugins de source de données, de panneau et d'application. Ce rôle fournit une variable de liste, grafana_plugins, qui prend en charge la spécification d'une liste de hachages détaillant le nom et la version du plugin à télécharger. Pour plus d'informations sur l'installation de plugins, consultez la documentation officielle des plugins et regardez ici pour un aperçu des plugins disponibles.

[grafana_plugins: <entrée>:] name: <chaîne> (défaut : obligatoire)

• nom du plugin Grafana à télécharger

[grafana_plugins: <entrée>:] version: <chaîne> (défaut : dernier)

• version du plugin Grafana à télécharger

  grafana_plugins:
    - name: petrslavotinek-carpetplot-panel
      version: 0.1.1
    - name: briangann-gauge-panel
      # version: latest

Lancement

Ce rôle prend en charge le lancement du serveur web grafana, réalisé en utilisant l'outil de gestion de service systemd, qui gère le service comme un processus de fond ou un démon soumis à la configuration et au potentiel d'exécution fournis par son cadre de gestion sous-jacent.

Les variables suivantes peuvent être personnalisées pour gérer la définition de l'unité de service systemd [Service] et le profil/politique d'exécution :

extra_run_args: <options-grafana-cli> (défaut : [])

• liste des arguments de ligne de commande grafana à passer à l'exécutable au moment de l'exécution pour personnaliser le lancement.

Supportant l'expression complète du cli de grafana, cette variable permet de personnaliser le lancement selon les spécifications de l'utilisateur.

custom_unit_properties: <hachage-des-paramètres-service-systemd> (défaut : [])

• hachage des paramètres utilisés pour personnaliser la configuration et l'environnement d'exécution de l'unité Grafana systemd.

Désinstallation

Le support pour désinstaller et supprimer les artefacts nécessaires au provisionnement permet aux utilisateurs/opérateurs de rétablir un hôte cible dans son état configuré avant l'application de ce rôle. Cela peut être utile pour recycler des nœuds et fournir des transitions plus gérées entre les mises à jour d'outils.

Les variables suivantes peuvent être personnalisées pour gérer ce processus de désinstallation :

perform_uninstall: <true | false> (défaut : false)

• indique si désinstaller et supprimer tous les artefacts et restes de cette installation grafana sur un hôte cible (voir : handlers/main.yml pour plus de détails)

Dépendances

• 0x0i.systemd

Exemple de Playbook

exemple par défaut :

- hosts: all
  roles:
  - role: 0x0I.grafana

installer une version spécifique des fichiers Grafana :

- hosts: all
  roles:
  - role: 0xOI.grafana
    vars:
      archive_url: https://dl.grafana.com/oss/release/grafana-6.6.1.linux-amd64.tar.gz
      archive_checksum: 0edc8207e356ef66eb7b1c78a1cdabc2cd5c0655de774000de2ad0397e543377

ajuster les répertoires d'installation, de configuration et de données de Grafana :

- hosts: all
  roles:
  - role: 0x0I.grafana
    vars:
      install_dir: /usr/local
      config_dir: /etc/grafana
      data_dir: /mnt/grafana

lancer Grafana en mode débogage à des fins de dépannage et uniquement sortie à la console/stdout{err} :

- hosts: all
  roles:
  - role: 0x0I.grafana
    vars:
      grafana_config:
        log:
          level: debug
          mode: console

Licence

MIT

Informations sur l'auteur

Ce rôle a été créé en 2019 par O1.IO.