Grafana provisioning: dashboards y datasources como código IaC
El problema de configurar Grafana a mano
En cualquier entorno de producción que se precie, la observabilidad es un pilar crítico. Grafana se ha convertido en el estándar de facto para visualizar métricas, logs y trazas. Sin embargo, la mayoría de los administradores caen en la tentación de configurar sus datasources y dashboards a través de la interfaz web. Esto parece inofensivo al principio, pero se convierte en una pesadilla cuando tienes que replicar el mismo panel en cinco clústeres distintos, o cuando un colega modifica un dashboard en producción y nadie sabe quién ni por qué.
La solución profesional se llama provisioning por código, una funcionalidad nativa de Grafana que permite declarar todos los recursos (datasources, dashboards, alertas, organizaciones, usuarios) en archivos YAML o JSON. Estos archivos se versionan en Git, se revisan con pull requests y se despliegan mediante pipelines de CI/CD. En este artículo exploraremos cómo implementarlo, con comandos reales y ejemplos prácticos, y discutiremos las ventajas y los escollos de tratar la observabilidad como infraestructura.
¿Qué es el provisioning en Grafana?
El provisioning es un mecanismo que le dice a Grafana: "no mires solo la base de datos interna para configurar; lee estos archivos al arrancar". Se define en el archivo principal de configuración grafana.ini o mediante variables de entorno. La clave está en la sección [paths] y en el directorio provisioning/ que se crea por defecto en la instalación.
La estructura típica es la siguiente:
/etc/grafana/
├── grafana.ini
└── provisioning/
├── datasources/
│ └── datasources.yaml
├── dashboards/
│ ├── dashboards.yaml
│ └── json/ # aquí se guardan los .json de los dashboards
└── alerting/
└── alert_rules.yaml
El archivo grafana.ini debe apuntar a estas rutas. Si usas la imagen oficial de Docker, puedes montar un volumen. La configuración mínima es:
[paths]
provisioning = /etc/grafana/provisioning
Provisioning de datasources: el primer paso
Sin datasources, Grafana es una carcasa vacía. El archivo datasources.yaml permite definir conexiones a Prometheus, InfluxDB, Loki, Elasticsearch, etc. Veamos un ejemplo funcional para Prometheus y PostgreSQL.
apiVersion: 1
datasources:
-
name: Prometheus type: prometheus access: proxy url: http://prometheus:9090 isDefault: true editable: false jsonData: timeInterval: ”15s” httpMethod: POST
name: PostgreSQL type: postgres url: postgres:5432 user: grafana secureJsonData: password: $POSTGRES_PASSWORD jsonData: database: observability sslmode: disable maxOpenConns: 5
Detalles clave: editable: false evita que los usuarios modifiquen el datasource desde la UI, garantizando que solo el código define la configuración. secureJsonData permite inyectar secretos sin exponerlos en texto plano en Git; Grafana los cifra en su base de datos interna. Puedes usar variables de entorno del sistema para poblar estos valores.
Dashboards como archivos JSON versionables
El siguiente nivel es el provisioning de dashboards. Se necesitan dos partes: un archivo YAML de configuración (dashboards.yaml) y los JSON de cada panel.
apiVersion: 1
providers:
name: ‘default’ orgId: 1 folder: ‘Producción’ type: file disableDeletion: true updateIntervalSeconds: 30 allowUiUpdates: false options: path: /etc/grafana/provisioning/dashboards/json
Explicación de los campos más relevantes:
- folder: organiza los dashboards en carpetas, lo cual es indispensable cuando tienes decenas de paneles.
- disableDeletion: impide que se borren desde la interfaz. La única forma de eliminarlos es quitando el archivo del repositorio.
- allowUiUpdates: si lo pones a
false, cualquier cambio hecho en la UI se sobreescribe en el próximo ciclo de actualización. Es la opción más estricta, pero garantiza que Git siempre sea la fuente de verdad. - updateIntervalSeconds: define cada cuánto escanea el directorio en busca de cambios. En producción, valores entre 30 y 60 segundos son razonables.
El contenido del dashboard es un JSON enorme que exportas desde la UI o generas con herramientas como grafonnet (librería de Jsonnet). Un truco práctico: cuando tengas un dashboard diseñado a mano, expórtalo desde Grafana (menú Share → Export) y guárdalo en el repositorio. El JSON incluye referencias a datasources por nombre, así que asegúrate de que los nombres coincidan con los definidos en datasources.yaml.
Alertas: no solo paneles bonitos
La observabilidad sin alertas es información muerta. Grafana 8+ introdujo el sistema de alertas unificado, que también es provisionable. El archivo alert_rules.yaml define reglas, condiciones y notificaciones. Ejemplo para una alerta de latencia alta:
apiVersion: 1
groups:
orgId: 1 name: ‘Latencia’ folder: ‘Producción’ interval: 1m rules:uid: latencia_alta title: ‘Latencia P99 superior a 500ms’ condition: ‘C’ data:refId: ‘A’ datasourceUid: ‘prometheus’ model: expr: ‘histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))’ instant: true relativeTimeRange: from: 300 to: 0 noDataState: OK execErrState: Error for: 5m labels: severity: critical annotations: summary: ‘Latencia P99 alta en producción’
Para que funcione, necesitas el datasourceUid correcto. Puedes asignarlo manualmente en el datasource o dejarlo que Grafana lo genere. Si usas editable: false, el UID se mantiene estable. Las alertas provisionadas por código son compatibles con los contact points (Slack, PagerDuty, Email) que también se definen en YAML.
Integración con CI/CD: el flujo GitOps
El verdadero poder del provisioning aparece cuando lo integras en un pipeline. Un flujo típico es:
- El desarrollador clona el repositorio de configuración de Grafana.
- Modifica un dashboard o añade un datasource nuevo.
- Abre un pull request. Un revisor verifica los cambios en el diff.
- Al hacer merge, un job de CI (GitHub Actions, GitLab CI, Jenkins) ejecuta una validación de sintaxis y luego despliega los archivos al servidor.
- Grafana detecta los cambios vía
updateIntervalSecondso se reinicia el servicio.
Un fragmento de pipeline en GitHub Actions para validar YAML:
name: validate-grafana
on: pull_request
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Validate YAML syntax
run: |
python -c "import yaml, sys; [yaml.safe_load(open(f)) for f in sys.argv[1:]]" \
$(find provisioning -name '*.yaml')
Para el despliegue, basta con una tarea que copie los archivos al directorio remoto y ejecute systemctl restart grafana-server o docker-compose restart grafana. Si usas Kubernetes, monta los archivos como ConfigMaps.
Ventajas y desventajas de este enfoque
Ventajas: trazabilidad total (sabes quién cambió qué y cuándo); reproducibilidad (el mismo código genera el mismo Grafana en cualquier entorno); auditoría y compliance (en entornos regulados, es imprescindible); y reversión rápida (un git revert soluciona un desastre).
Desventajas: los JSON de dashboards son enormes y difíciles de leer en diffs; la curva de aprendizaje inicial; y el riesgo de sobrescribir cambios legítimos hechos por desarrolladores en la UI si no configuras bien allowUiUpdates. Mi recomendación: para entornos de producción, establece allowUiUpdates: false y fomenta que cualquier cambio se haga vía código. Para staging o desarrollo, puedes permitir ediciones para experimentar.
Herramientas complementarias: grafonnet y jq
Trabajar con JSON a mano es tedioso. Grafonnet (basado en Jsonnet) genera dashboards a partir de código declarativo
comentarios(0)
$ dejar comentario