Grafana es una plataforma de código abierto para visualizar métricas, logs y trazas de muchas fuentes de datos y crear alertas sobre ellos. La mayoría de la gente la conoce por su interfaz web, pero todo lo que importa en una instalación de Grafana también puede describirse en archivos: ajustes del servidor, data sources, dashboards, reglas de alertas, contact points y políticas de notificación. Esta serie se centra en esa segunda forma de trabajar, de modo que una instancia de Grafana pueda reconstruirse desde Git en cualquier momento y nadie tenga que recordar en qué hizo clic alguien el mes pasado.

Cómo funciona

Grafana lee su configuración de capas que puedes controlar sin abrir la interfaz:

1. La configuración del servidor (grafana.ini y variables de entorno GF_*) controla los puertos, la base de datos, la autenticación, SMTP y los feature toggles.
2. Los archivos de provisioning (YAML en una carpeta provisioning/) crean data sources, proveedores de dashboards, recursos de alertas y ajustes de plugins al arrancar.
3. Los archivos JSON de dashboards en disco los carga un proveedor de dashboards y se vuelven a escanear mientras Grafana se ejecuta.
4. Las APIs y los operators (Terraform, el Grafana Operator, Git Sync, la CLI gcx) gestionan lo que los archivos por sí solos no pueden, como equipos, service accounts y permisos de carpetas.

Como todo esto es texto plano, encaja en el mismo flujo GitOps que el resto de tu infraestructura, incluidos Flux y Argo CD.

Conceptos clave

• Data source — una conexión a un backend como Prometheus, Loki o PostgreSQL. Los dashboards y las reglas de alertas consultan los data sources por nombre o UID.
• Dashboard — un documento JSON formado por paneles y variables. Grafana ahora usa internamente un esquema de dashboard más nuevo, y el JSON antiguo se migra automáticamente al cargarse.
• Folder (carpeta) — organiza dashboards y reglas de alertas, y lleva permisos.
• Provisioning — cargar recursos desde archivos al arrancar, para que existan antes de que nadie inicie sesión.
• Alerting — reglas de alertas, contact points, políticas de notificación, mute timings y plantillas, todo lo cual puede provisionarse.
• Organization (organización) — un límite de tenant dentro de un servidor Grafana; la mayoría de los archivos aceptan un orgId.

Por qué operar Grafana como código

• Reproducible. Una instancia perdida o nueva vuelve idéntica desde el repositorio.
• Revisable. Un cambio de dashboard o de alerta es un pull request con un diff, no una edición sin rastro.
• Coherente entre entornos. Dev, staging y producción comparten definiciones y solo difieren en los valores.
• Las desviaciones son visibles. Los recursos provisionados pueden bloquearse frente a ediciones en la interfaz, de modo que Git sigue siendo la fuente de verdad.

Primeros pasos

Ejecuta Grafana en un contenedor con una carpeta provisioning/ montada, añade un archivo de data source y un proveedor de dashboards, y deja el JSON de los dashboards junto a ellos. Las guías siguientes empiezan por ahí y avanzan hacia alertas, secretos, Kubernetes, Terraform y el Operator. Se escribieron con Grafana 13 como referencia; consulta la documentación de Grafana para la versión que instales, ya que algunas funciones as-code todavía están marcadas como alpha.