Escribir JSON de dashboards a mano no escala, y exportarlo desde la interfaz deja a la interfaz como la fuente real. Las herramientas de observability-as-code de Grafana abordan ambos problemas: el Foundation SDK genera dashboards a partir de código tipado, Git Sync hace que Grafana lea y escriba dashboards en un repositorio de Git, y la CLI gcx sube y descarga recursos desde la terminal. Varias de estas funciones son recientes, y algunas APIs están marcadas como alpha, así que consulta la documentación de tu versión.

Genera dashboards con el Foundation SDK

El Foundation SDK proporciona builders para dashboards, paneles y consultas en Go, TypeScript, Python, PHP y Java. Describes un dashboard en un lenguaje tipado, y llamar a build() produce el JSON del dashboard. Como es código, obtienes comprobaciones en tiempo de compilación, reutilización (una función que construye una fila estándar de servicio) y revisión de código normal.

Instálalo para tu lenguaje, por ejemplo:

# Go
go get github.com/grafana/grafana-foundation-sdk/go@latest

# TypeScript
npm install @grafana/grafana-foundation-sdk

Los paquetes de Python, PHP y Java aparecen en la documentación del SDK. Está dirigido a Grafana 10 y posteriores.

Un flujo de trabajo típico:

1. Escribe un pequeño programa que defina los dashboards y escriba el JSON de cada uno en dashboards/<nombre>.json.
2. Ejecútalo en CI.
3. Haz commit del JSON generado, o publícalo como artefacto de build.
4. Entrega el JSON con el mecanismo que ya uses: una carpeta de proveedor, un ConfigMap, un recurso GrafanaDashboard, Terraform o Git Sync.

# esquema de un job de CI
steps:
  - run: npm ci
  - run: npx tsx dashboards/generate.ts --out dashboards/generated
  - run: git diff --exit-code dashboards/generated   # falla si los archivos generados están desactualizados

La comprobación git diff --exit-code asegura que nadie edite el JSON generado a mano y que el código y la salida se mantengan sincronizados.

Git Sync

Git Sync permite a Grafana guardar dashboards como JSON en un repositorio de Git. Los cambios fluyen en ambos sentidos: una edición en la interfaz de Grafana se convierte en un commit o un pull request, y un cambio fusionado en el repositorio aparece en Grafana. Grafana consulta el repositorio cada 60 segundos por defecto, y un webhook hace que las actualizaciones lleguen casi de inmediato. Git Sync está disponible de forma general en Grafana 13 en todas las ediciones. Soporta GitHub (con autenticación de App), GitHub Enterprise, GitLab, Bitbucket y Git plano mediante un tipo de repositorio “Pure Git”.

Puedes configurarlo enteramente como código con un recurso Repository. Crea repository.yaml:

apiVersion: provisioning.grafana.app/v0alpha1
kind: Repository
metadata:
  name: my-repo
spec:
  title: My Repository
  type: github
  github:
    url: https://github.com/<org>/<repo>
    branch: main
    path: grafana/
  sync:
    enabled: true
    intervalSeconds: 60
    target: folder
  workflows:
    - write
    - branch
secure:
  token:
    create: '<git-personal-access-token>'

Notas sobre los campos:

• type es uno de github, githubEnterprise, gitlab, bitbucket o git, y cada uno tiene su propio bloque. Bitbucket y Git plano también necesitan un tokenUser.
• path es la carpeta del repositorio de la que Grafana es dueño.
• workflows controla qué hacen los guardados de la interfaz: write hace commit directamente en la rama, y branch abre un pull request.
• sync.target es folder (el predeterminado) o folderless.
• secure.token lleva la credencial, de modo que se guarda como secreto y no en la especificación. En lugar de un token puedes usar una conexión de GitHub App u OAuth app con spec.connection.name; esas necesitan un connection.yaml aparte.
• La versión de la API es v0alpha1, así que los nombres de los campos pueden cambiar entre versiones.

Aplícalo con gcx (siguiente sección), o desde la interfaz de Grafana si lo prefieres.

En lo que Git Sync destaca: dejar que quienes crean desde la interfaz y quienes priorizan Git compartan una única fuente de verdad, con revisión por pull request en cada cambio. Lee la página de limitaciones de uso antes de adoptarlo en una instancia grande, ya que provisionar grandes cantidades de dashboards tiene consideraciones de rendimiento.

La CLI gcx

gcx es la línea de comandos de Grafana para trabajar con recursos y, en Grafana Cloud, con otros productos. Funciona con Grafana Cloud y con Grafana de código abierto o Enterprise 12 y posteriores, y reemplaza a la antigua herramienta grafanactl (migrar consiste sobre todo en renombrar el comando, y grafanactl resources serve pasa a ser gcx dev serve). Instálala desde el repositorio del proyecto y configura un contexto con la URL y el token de tu Grafana, como describe su documentación.

Comandos comunes:

# sube los archivos de recursos locales a Grafana
gcx resources push --path ./resources

# lista lo que existe, o inspecciona un recurso
gcx resources get repositories
gcx resources get repository/my-repo -o yaml

# edita o elimina
gcx resources edit repository/my-repo
gcx resources delete repository/my-repo

# previsualiza dashboards en vivo mientras desarrollas
gcx dev serve

Úsala en CI para subir definiciones de recursos desde el repositorio, o en local mientras construyes dashboards con el SDK.

Cómo elegir entre los enfoques

Situación	Recurre a
Muchos dashboards similares, o bloques reutilizables	Foundation SDK, entregado por cualquier mecanismo
Los autores trabajan en la interfaz pero quieres Git como registro	Git Sync
GitOps en Kubernetes, un objeto por dashboard	Grafana Operator
Automatización de toda la plataforma, incluidos equipos y permisos	Terraform
Un Grafana, archivos JSON estáticos	Carpeta de proveedor simple

Se combinan bien: genera JSON con el SDK, haz commit en un repositorio y deja que Git Sync o una carpeta de proveedor lo entregue.

Verifica

gcx resources get repositories
curl -s -u admin:$GRAFANA_ADMIN_PASSWORD \
  "http://localhost:3000/api/search?type=dash-db" | jq '.[] | {title, folderTitle}'

Para problemas de sincronización de repositorios, comprueba el estado del repositorio en Grafana (en Administration, luego Provisioning) y el log del servidor de Grafana. Los problemas típicos son un token caducado, una rama o ruta incorrectas y un webhook que no puede llegar a Grafana.