Grafana Opera Grafana como código: la visión de conjunto
Qué puede vivir en archivos, qué necesita una API y cómo encajan las piezas.
Grafana guiado por clics funciona hasta la primera vez que necesitas una segunda copia, un rollback o una respuesta a “¿quién cambió este panel?”. Esta guía traza cómo ejecutar Grafana desde archivos en lugar de la interfaz, para que sepas qué mecanismo usar para cada recurso antes de escribir nada de YAML.
Por qué la interfaz se convierte en un problema
Cuando los dashboards, data sources y alertas se crean a mano, tres cosas van mal con el tiempo:
- Nada es reproducible. El estado vive en la base de datos de Grafana. Reconstruir una instancia significa rehacer cada clic.
- Los cambios son invisibles. No hay paso de revisión ni historial más allá del registro de versiones del propio Grafana.
- Los entornos se desvían. Staging y producción divergen poco a poco, y nadie puede decir cómo.
La solución es tratar la base de datos como una caché y el repositorio como la verdad. Todo lo que Grafana necesita se provisiona desde archivos al arrancar o lo aplica una herramienta que lee archivos.
Las capas
| Capa | Formato | Qué controla | Quién lo aplica |
|---|---|---|---|
| Configuración del servidor | grafana.ini y variables GF_* | Puertos, base de datos, autenticación, SMTP, logging, feature toggles | Grafana al arrancar |
| Provisioning de data sources | YAML | Data sources y sus credenciales | Grafana al arrancar |
| Provisioning de dashboards | Proveedor YAML + archivos JSON | Dashboards y carpetas | Grafana, reescaneado según un intervalo |
| Provisioning de alertas | YAML | Reglas de alertas, contact points, políticas, mute timings, plantillas | Grafana al arrancar |
| Provisioning de plugins | YAML | Ajustes de apps de plugins ya instalados | Grafana al arrancar |
| Terraform | HCL | Todo lo que tenga una API: carpetas, data sources, dashboards, alertas, equipos, service accounts | terraform apply |
| Grafana Operator | Recursos personalizados de Kubernetes | Instancias, carpetas, dashboards, data sources, reglas de alertas | Un controlador en el clúster |
| Git Sync | Un recurso Repository | Dashboards guardados en un repositorio de Git, sincronizados en ambos sentidos | El propio Grafana |
¿Cuál deberías usar?
- Un Grafana en un contenedor o VM, un equipo pequeño: configuración del servidor más provisioning por archivos. No tiene piezas móviles adicionales.
- Kubernetes con GitOps (Flux o Argo CD): el chart de Helm de Grafana para la instancia, con archivos de provisioning como ConfigMaps, o el Grafana Operator si quieres cada dashboard y data source como su propio objeto de Kubernetes.
- Muchas instancias, o Grafana Cloud: Terraform, porque también puede crear stacks, service accounts y equipos.
- Dashboards creados por muchas personas: Git Sync, o una biblioteca de código como el Grafana Foundation SDK que genera el JSON.
Estas opciones se combinan bien. Una configuración común es provisioning por archivos para data sources y alertas, más Git Sync o Terraform para los dashboards.
Lo que los archivos no pueden hacer
Algunos recursos no tienen formato de archivo de provisioning. Planifica para ellos:
- Usuarios, equipos, organizaciones y service accounts se crean mediante la API o Terraform (o un proveedor de identidad con SSO y mapeo de roles).
- Los permisos de carpetas y dashboards se gestionan mediante la API, Terraform o el Operator.
- La contraseña inicial de admin solo se define en la primera ejecución, así que cambiarla después requiere una llamada a la CLI o la API.
Las guías de autenticación y de Terraform cubren las soluciones alternativas.
Provisionado significa bloqueado
Los recursos provisionados están pensados para pertenecer a los archivos. Los data sources pueden marcarse como editable: false, los dashboards de un proveedor pueden rechazar los guardados desde la interfaz, y los recursos de alertas provisionados no pueden editarse en absoluto en la interfaz. Ese es el punto: si alguien pudiera cambiarlos a mano, Git dejaría de ser la verdad. Recuerda que la interfaz sigue siendo útil para explorar datos y esbozar un panel, y el flujo de creación de la guía de dashboards muestra cómo devolver esos borradores a Git.
Un modelo mental para un cambio
- Edita un archivo del repositorio (el JSON de un dashboard, el YAML de un data source, una regla de alerta).
- Abre un pull request, revisa el diff, haz merge.
- El mecanismo de entrega lo aplica: un reinicio del contenedor, un reescaneo de dashboards, una reconciliación de Flux o
terraform apply. - La propia base de datos de Grafana se actualiza para coincidir. Si algo sale mal, revierte el commit.
Adónde ir después
Ejecuta un Grafana local desde un archivo compose (siguiente guía), aprende las reglas de configuración y luego añade data sources, dashboards y alertas de uno en uno. Como referencia, consulta la documentación de Grafana.
Guías populares
- Configura el servidor de Grafana con grafana.ini y variables de entorno Sabe dónde viven los archivos de configuración, cómo se ordenan las sobrescrituras y cómo mantener los ajustes en Git.
- Provisiona dashboards desde archivos JSON Carga dashboards desde disco, asigna carpetas a partir de directorios y crea dashboards sin perder cambios.
- Provisiona reglas de alertas, contact points y políticas de notificación Define todo el pipeline de alertas en YAML para que se revise y versione como código.
- Despliega Grafana en Kubernetes con Helm y valores de provisioning Ejecuta Grafana desde un chart de Helm donde los data sources, dashboards y ajustes provienen de archivos de valores.
- Recarga, verifica y soluciona problemas de provisioning desde la línea de comandos Averigua qué cargó Grafana, recarga sin reiniciar y arregla los errores de provisioning más habituales.