Rol de Ansible :rainbow: :bar_chart: Grafana

Tabla de Contenidos

• Plataformas Soportadas
• Requisitos
• Variables del Rol
  • Instalación
  • Configuración
  • Lanzamiento
  • Desinstalación
• Dependencias
• Ejemplo de Playbook
• Licencia
• Información del Autor

Rol de Ansible que instala y configura Grafana: una plataforma de análisis y monitoreo.

Plataformas Soportadas:

* Debian
* Redhat(CentOS/Fedora)
* Ubuntu

Requisitos

Requiere que se instale la utilidad unzip/gtar en el host objetivo. Consulta las notas del módulo de ansible para más detalles. Además, debido al uso de la función provisioning introducida en la versión 5.0, se requieren versiones >= 5.0 de Grafana para una correcta ejecución.

Variables del Rol

Las variables están disponibles y organizadas según las siguientes etapas de aprovisionamiento de software y máquina:

• instalación
• configuración
• lanzamiento
• desinstalación

Instalación

grafana se puede instalar utilizando archivos comprimidos (.tar, .zip) y paquetes de distribución DEB así como RPM, descargados y extraídos de diversas fuentes.

Las siguientes variables se pueden personalizar para controlar varios aspectos de este proceso de instalación, que van desde la versión del software y la ubicación de los binarios hasta el directorio de instalación donde se almacenan:

grafana_user: <nombre-de-usuario-del-servicio> (por defecto: grafana)

grafana_group: <nombre-del-grupo-del-servicio> (por defecto: grafana)

• usuario y grupo de servicio dedicados utilizados por grafana para separación de privilegios.

install_type: <package | archive> (por defecto: archive)

• package: soportado por las distribuciones Debian y Redhat, la instalación por paquetes de Grafana descarga el paquete especificado del repositorio de gestión de paquetes correspondiente.

  • Ten en cuenta que el directorio de instalación es determinado por el sistema de gestión de paquetes y actualmente se ubica por defecto en /usr/{sbin,lib, share} para todas las distribuciones.

• archive: compatible con formatos tar y zip, los binarios de instalación archivados se pueden obtener de archivos comprimidos locales y remotos ya sea del índice de releases oficial o de fuentes de desarrollo personalizadas.

install_dir: </ruta/al/directorio/de/instalacion> (por defecto: /opt/grafana)

• ruta en el host objetivo donde se deben extraer los binarios de grafana.

archive_url: <ruta-o-url-del-archivo-comprimido> (por defecto: ver defaults/main.yml)

• dirección de un archivo comprimido tar o zip que contenga los binarios de grafana. Este método técnicamente soporta la instalación de cualquier versión disponible de grafana. Los enlaces a versiones oficiales se pueden encontrar aquí.

archive_checksum: <ruta-o-url-del-cheksum> (por defecto: ver defaults/main.yml)

• dirección de un archivo de checksum para verificar la integridad de los datos del archivo comprimido de grafana. Aunque se recomienda y generalmente se considera una buena práctica, especificar un checksum no es obligatorio y se puede desactivar proporcionando una cadena vacía ('') como valor.

checksum_format: <cadena> (por defecto: ver sha256)

• algoritmo de hash utilizado para la verificación de archivos asociada al checksum del archivo especificado.

package_url: <ruta-o-url-del-paquete> (por defecto: ver defaults/main.yml)

• dirección de un paquete debian(DEB) o RPM que contenga los binarios de grafana. Los enlaces a versiones oficiales se pueden encontrar aquí.

package_checksum: <ruta-o-url-del-checksum> (por defecto: ver defaults/main.yml)

• dirección de un archivo de checksum para verificar la integridad de los datos del paquete de grafana. Aunque se recomienda y generalmente se considera una buena práctica, especificar un checksum no es obligatorio y se puede desactivar proporcionando una cadena vacía ('') como valor.

Configuración

Con este rol, la configuración de una instalación de grafana se organiza según los siguientes componentes:

• configuración del servicio grafana (grafana.ini)
• aprovisionamiento de fuentes de datos (provisioning/datasources - *.[json|yml])
• aprovisionamiento de paneles de control (provisioning/dashboards - *.[json|yml])
• configuración de notificaciones (provisioning/notifiers - [json|yml])

Cada configuración se puede expresar dentro de las siguientes variables para personalizar el contenido y la configuración de los archivos de configuración designados a ser generados:

config_dir: </ruta/al/directorio/de/configuracion> (por defecto: {{ install_dir }})

• ruta en el host objetivo donde se debe generar el archivo de configuración de grafana.

provision_configs: <['datasources', 'dashboards' y/o 'notifiers']> (por defecto: [])

• lista de componentes de aprovisionamiento de Grafana a configurar.

Configuración del Servicio Grafana

La configuración del servicio Grafana se encuentra en un archivo INI, grafana.ini por defecto, que define un conjunto de comportamientos del servicio organizados por sección que representan la administración general y varios aspectos del proveedor de contenido del servicio Grafana.

Estas secciones y configuraciones se pueden expresar dentro del hash, grafana_config, usando la sección de configuración como clave y diccionarios como valores que representan las especificaciones de la sección de configuración.

:paths

[grafana_config:] path: <clave: valor,...> (por defecto: ver documentación)

• especifica parámetros relacionados con dónde Grafana almacena artefactos y datos variables.

 grafana_config:
   # sección [paths]
   paths:
     # opción de sección 1 - path de la base de datos sqlite
     data: /mnt/data/grafana
     # opción de sección 2 - path para almacenar logs
     logs: /mnt/logs/grafana

[grafana_config:] server: <clave: valor,...> (por defecto: ver documentación)

• especifica parámetros relacionados con cómo Grafana se interfaz a través de la red.

 grafana_config:
   # sección [server]
   server:
     http_addr: 127.0.0.1
     http_port: 3030

:database

[grafana_config:] database: <clave: valor,...> (por defecto: ver documentación)

• especifica parámetros que controlan cómo Grafana se interfaz con uno de los tipos de almacenamiento disponible (i.e. mysql, postgres y sqlite).

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

:remote_cache

[grafana_config:] remote_cache: <clave: valor,...> (por defecto: ver documentación)

• especifica parámetros que controlan cómo Grafana se interfaz con uno de los tipos de almacenamiento en caché remoto disponibles (i.e. redis, memcached y database).

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

:security

[grafana_config:] security: <clave: valor,...> (por defecto: ver documentación)

• especifica parámetros que gestionan la autenticación y autorización de usuarios/organizaciones de Grafana.

  grafana_config:
    # sección [security]
    security:
      admin_user: sre-user
      admin_password: PASSWORD
      login_remember_days: 7

:users

[grafana_config:] users: <clave: valor,...> (por defecto: ver documentación)

• especifica parámetros que controlan las capacidades del usuario en Grafana.

  grafana_config:
    # sección [users]
    users:
      allow_sign_up: true
      allow_org_create: false
      login_hint: ESTE ES UN HINT

:auth

[grafana_config:] auth: <clave: valor,...> (por defecto: ver documentación)

• especifica parámetros que regulan las capacidades de autorización de los usuarios.

Grafana proporciona múltiples métodos para autenticar usuarios y la configuración para cada método se expresa dentro de las secciones [auth.<método>] según sea apropiado, permitiendo autenticación que va desde la autenticación básica de usuario hasta OAuth de Google y Github.

  grafana_config:
    # sección [auth.github] - NOTA: **github** representa el método de auth
    auth.github:
      enabled: true
      allow_sign_up: true
      client_id: TU_CLIENT_ID_DE_APP_DE_GITHUB
      client_secret: TU_CLIENT_SECRET_DE_APP_DE_GITHUB
      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: <clave: valor,...> (por defecto: ver documentación)

• especifica parámetros que habilitan el registro de proxies de datos.

  grafana_config:
    # sección [dataproxy]
    dataproxy:
      logging: true
      timeout: 60
      send_user_header: true

:analytics

[grafana_config:] analytics: <clave: valor,...> (por defecto: ver documentación)

• especifica parámetros que activan la recopilación y reporte de estadísticas de uso.

  grafana_config:
    # sección [analytics]
    analytics:
      reporting_enabled: true
      google_analytics_ua_id: UA_ID
      check_for_updates: true

:dashboards

[grafana_config:] dashboards: <clave: valor,...> (por defecto: ver documentación)

• especifica parámetros que regulan la política de mantenimiento del panel de control de Grafana.

  grafana_config:
    # sección [dashboards]
    dashboards:
      versions_to_keep: 5

:smtp

[grafana_config:] smtp: <clave: valor,...> (por defecto: ver documentación)

• especifica configuraciones del servidor de correo para identidad además de alertas/notificaciones.

  grafana_config:
    # sección [smtp]
    smtp:
      enabled: true
      host: 127.0.0.1:65
      user: smtp-user
      password: PASSWORD

:log

[grafana_config:] log: <clave: valor,...> (por defecto: ver documentación)

• especifica configuraciones de registro (p.ej. nivel de registro y modos o canales de salida).

  grafana_config:
    # sección [log]
    log:
      mode: console
      level: debug

:metrics

[grafana_config:] metrics: <clave: valor,...> (por defecto: ver documentación)

• especifica configuraciones para gestionar la emisión de telemetría de Grafana.

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

:snapshots

[grafana_config:] snapshots: <clave: valor,...> (por defecto: ver documentación)

• especifica configuraciones para gestionar el comportamiento de publicación de la funcionalidad de captura de instantáneas interactivas del panel de control de Grafana.

  grafana_config:
    # sección [snapshots]
    snapshots:
      external_enabled: true
      external_snapshot_name: ENDPOINT

:external_image_storage

[grafana_config:] external_image_storage: <clave: valor,...> (por defecto: ver documentación)

• especifica configuraciones para controlar cómo las imágenes deben ser accesibles públicamente para compartir en servicios como slack.

Grafana soporta varios proveedores de almacenamiento backend para los cuales se pueden expresar configuraciones individuales dentro de las secciones [external_image_storage.] según sea apropiado, habilitando almacenamiento remoto en servicios como s3, gcs, azure blob y almacenamiento local.

  grafana_config:
    # sección [external_image_storage]
    external_image_storage:
      external_enabled: true
      external_snapshot_name: Publicar en 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: <clave: valor,...> (por defecto: ver documentación)

• especifica configuraciones para gestionar el motor de alertas y el comportamiento/reglas.

  grafana_config:
    # sección [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: <clave: valor,...> (por defecto: ver documentación)

• especifica configuraciones para operar un servicio de renderizado HTTP remoto.

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

:plugins

[grafana_config:] plugins: <clave: valor,...> (por defecto: ver documentación)

• especifica configuraciones para gestionar la disponibilidad y accesibilidad de plugins de grafana.

  grafana_config:
    # sección [plugins]
    plugins:
      enable_alpha: true

:feature_toggles

[grafana_config:] feature_toggles: <clave: valor,...> (por defecto: ver documentación)

• especifica configuraciones para activar el uso de características alfa en la instancia de grafana, delimitadas por espacios.

  grafana_config:
    # sección [feature_toggles]
    features_toggles:
      enable: transformations

:tracing.jaeger

[grafana_config:] tracing.jaegar: <clave: valor,...> (por defecto: ver documentación)

• especifica configuraciones para configurar el cliente Jaeger de Grafana para el rastreo distribuido.

Nota: Las variables de entorno estándar de Jaeger, prefijadas por JAEGAR_*, aún se pueden especificar y anularán cualquier configuración proporcionada aquí.

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

Fuentes de Datos

Grafana soporta muchos tipos diferentes de almacenamiento para tus datos en series temporales conocidos como fuentes de datos. Cada fuente de datos se puede configurar en un conjunto de archivos de configuración json|yml en el directorio provisioning de Grafana, que se puede ajustar dentro de la sección [paths] de grafana.ini.

Estas configuraciones de fuentes de datos pueden expresarse dentro del hash, grafana_datasources. Este hash contiene una lista de estructuras de fuentes de datos para activar y otra para eliminar, con claves datasources y deleteDatasources, respectivamente. Los valores en sí consisten en una lista de diccionarios que representan especificaciones individuales de fuentes de datos. Consulta aquí para más detalles y una lista de fuentes de datos compatibles.

grafana_datasources: <lista-de-diccionarios> (por defecto: [])

• especifica definiciones de fuentes de datos de grafana para renderizar.

grafana_datasources:
- name: ejemplo_fuente_de_datos
  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_ejemplo
      type: prometheus
      access: proxy
      url: http://localhost:9090
  deleteDatasources:
    - name: graphite-legacy
      type: graphite
      access: proxy
      url: http://localhost:8080
      jsonData:
        graphiteVersion: "1.1"

Desde la versión 5.0, Grafana ha permitido agregar uno o más archivos de configuración yaml|json en el directorio provisioning/dashboards, habilitando a Grafana a cargar paneles de control desde el sistema de archivos local. Este directorio puede contener una lista de proveedores de paneles de control que indican características y diversos tipos de metadatos relacionados con el directorio/archivo desde el cual cargar.

Estas configuraciones de proveedores de paneles de control pueden expresarse dentro del hash, grafana_dashboards, que se compone de una lista de las mencionadas estructuras de proveedores de paneles de control. Consulta aquí para más detalles y una lista de paneles de control creados por la comunidad disponibles para descargar e importar.

grafana_dashboards: <lista-de-diccionarios> (por defecto: [])

• especifica definiciones de proveedores de paneles de control de grafana para renderizar.

grafana_dashboards:
  - name: ejemplo-prueba
    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

Notificadores

Los canales de notificación de alertas se pueden aprovisionar agregando uno o más archivos de configuración yaml|json en el directorio provisioning/notifiers.

Cada archivo de configuración se puede expresar dentro del hash grafana_notifiers, que contiene los siguientes campos de nivel superior:

• notifiers, una lista de notificaciones de alerta que se agregarán o actualizarán durante el inicio. Si el canal de notificación ya existe, Grafana lo actualizará para que coincida con el archivo de configuración.
• delete_notifiers, una lista de notificaciones de alerta que se eliminarán antes de insertar/actualizar las de la lista de notificaciones.

El aprovisionamiento busca notificaciones de alerta por uid y actualizará cualquier notificación existente con el uid proporcionado.

grafana_notifiers: <lista-de-diccionarios> (por defecto: [])

• especifica definiciones de notificaciones de grafana para renderizar.

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

Plugins

Grafana soporta plugins de origen de datos, panel y aplicación. Este rol proporciona una variable de lista, grafana_plugins, que admite la especificación de una lista de hashes que detallan el nombre y la versión del plugin a descargar. Para más información sobre la instalación de plugins, consulta la documentación oficial de plugins y consulta aquí para obtener una referencia sobre los plugins disponibles.

[grafana_plugins: <entrada>:] name: (por defecto: requerido)

• nombre del plugin de Grafana a descargar.

[grafana_plugins: <entrada>:] version: (por defecto: latest)

• versión del plugin de Grafana a descargar.

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

Lanzamiento

Este rol soporta el lanzamiento del servidor web de grafana, realizado mediante la herramienta de gestión de servicios systemd, que gestiona el servicio como un proceso en segundo plano o daemon, sujeto a la configuración y potencial de ejecución proporcionada por su marco de gestión subyacente.

Las siguientes variables se pueden personalizar para gestionar la definición de unidad de servicio systemd y el perfil/política de ejecución del servicio:

extra_run_args: <opciones-grafana-cli> (por defecto: [])

• lista de argumentos de línea de comandos de grafana que se pasan al binario en tiempo de ejecución para personalizar el lanzamiento.

Apoyando la expresión completa del cli de grafana, esta variable habilita la personalización del lanzamiento según las especificaciones del usuario.

custom_unit_properties: <hash-de-configuraciones-de-servicio-systemd> (por defecto: [])

• hash de configuraciones utilizadas para personalizar la configuración y el entorno de ejecución de la unidad [Service] del servicio Grafana de systemd.

Desinstalación

El soporte para desinstalar y eliminar artefactos necesarios para el aprovisionamiento permite a los usuarios/operadores devolver un host objetivo a su estado configurado antes de la aplicación de este rol. Esto puede ser útil para reciclar nodos y quizás proporcionar transiciones más suaves/controladas entre las actualizaciones de herramientas.

Las siguientes variables se pueden personalizar para gestionar este proceso de desinstalación:

perform_uninstall: <true | false> (por defecto: false)

• indica si se debe desinstalar y eliminar todos los artefactos y residuos de esta instalación de grafana en un host objetivo (consultar: handlers/main.yml para más detalles).

Dependencias

• 0x0i.systemd

Ejemplo de Playbook

ejemplo por defecto:

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

instalar versión específica de 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

ajustar los directorios de instalación, configuración y datos de Grafana:

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

lanzar Grafana en modo de depuración para propósitos de solución de problemas y solo output a consola/stdout{err}:

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

Licencia

MIT

Información del Autor

Este rol fue creado en 2019 por O1.IO.