Cuando todo se define en archivos, los fallos también viven en archivos: una indentación incorrecta, un UID ausente, una ruta que no existe en el contenedor. Grafana te dice lo que hizo, pero tienes que saber dónde mirar. Esta guía cubre los endpoints de recarga, unos cuantos comandos de verificación y los errores que encontrarás con más frecuencia, para que puedas arreglarlos sin abrir la interfaz.

Qué se aplica cuándo

Recurso	Cuándo se lee	Cómo volver a aplicarlo
grafana.ini y variables GF_*	Solo al arrancar	Reiniciar Grafana
Data sources	Al arrancar	Reiniciar, o el endpoint de recarga
Dashboards	Al arrancar, luego cada updateIntervalSeconds	Esperar, o el endpoint de recarga
Recursos de alertas	Al arrancar	Reiniciar (o volver a ejecutar el provisioning mediante la Admin API según documente tu versión)
Ajustes de apps de plugins	Al arrancar	Reiniciar, o el endpoint de recarga

Recarga sin reiniciar

Estos endpoints de administración vuelven a leer los archivos de provisioning. Usan POST y autenticación básica con un usuario admin de Grafana; los tokens de API no funcionan con la Admin API:

BASE=http://localhost:3000
AUTH="admin:$GRAFANA_ADMIN_PASSWORD"

curl -X POST -u "$AUTH" $BASE/api/admin/provisioning/dashboards/reload
curl -X POST -u "$AUTH" $BASE/api/admin/provisioning/datasources/reload
curl -X POST -u "$AUTH" $BASE/api/admin/provisioning/plugins/reload
curl -X POST -u "$AUTH" $BASE/api/admin/provisioning/notifications/reload

Una llamada exitosa devuelve un mensaje JSON que dice que la configuración se recargó. No expongas estos endpoints públicamente, porque necesitan credenciales de admin. Para cualquier otra cosa, reiniciar siempre es seguro.

Comprueba qué cargó realmente Grafana

Compara los archivos con la vista de la API:

# salud
curl -s $BASE/api/health

# ajustes efectivos del servidor (valores sensibles enmascarados)
curl -s -u "$AUTH" $BASE/api/admin/settings | jq '.paths, .server'

# data sources, con el flag de solo lectura para los provisionados
curl -s -u "$AUTH" $BASE/api/datasources | jq '.[] | {name, uid, type, readOnly}'

# conectividad del data source
curl -s -u "$AUTH" $BASE/api/datasources/uid/prometheus/health

# dashboards y carpetas
curl -s -u "$AUTH" "$BASE/api/search?type=dash-db" | jq '.[] | {title, uid, folderTitle}'
curl -s -u "$AUTH" $BASE/api/folders | jq '.[] | {title, uid}'

# alertas
curl -s -u "$AUTH" $BASE/api/v1/provisioning/alert-rules | jq '.[] | {uid, title}'
curl -s -u "$AUTH" $BASE/api/v1/provisioning/contact-points | jq '.[].name'
curl -s -u "$AUTH" $BASE/api/v1/provisioning/policies | jq .

Si algo que provisionaste falta en estas listas, los logs dirán por qué.

Lee los logs

Los mensajes de provisioning provienen de loggers cuyos nombres empiezan por provisioning. Aumenta la verbosidad mientras depuras:

# docker compose
GF_LOG_LEVEL=debug docker compose up -d grafana
docker compose logs grafana | grep -i provision

# kubernetes
kubectl logs deploy/grafana -n monitoring -c grafana | grep -i provision

Busca el nombre del archivo en el mensaje. Grafana nombra el archivo que no pudo analizar o el recurso que rechazó.

Comprueba los archivos antes de que lleguen a Grafana

La mayoría de los errores pueden detectarse en CI:

# sintaxis YAML
yamllint grafana/provisioning

# sintaxis JSON y campos obligatorios
jq empty dashboards/**/*.json
jq -e '.uid and .title' dashboards/*/*.json >/dev/null

# UID de dashboards duplicados
jq -r '.uid' dashboards/*/*.json | sort | uniq -d

# ¿todos los archivos provisionados empiezan con apiVersion: 1?
grep -L '^apiVersion: 1' grafana/provisioning/*/*.yaml

Una prueba de extremo a extremo barata es iniciar un Grafana desechable en CI a partir de los mismos archivos, esperar a /api/health y hacer aserciones sobre la salida de la API anterior.

Problemas comunes y soluciones

Un data source o dashboard no aparece. La carpeta de provisioning no está montada donde Grafana busca. Confirma que [paths] provisioning (por defecto /etc/grafana/provisioning) coincide con tu montaje, y que los nombres de las subcarpetas son exactamente datasources, dashboards, alerting y plugins.

“Permission denied” al leer archivos. La imagen oficial se ejecuta como un usuario no root, así que los archivos montados deben ser legibles por él. Hazlos legibles por todos (chmod -R a+rX), o define una propiedad coincidente en el volumen.

El dashboard falla con “Dashboard title cannot be empty”. El JSON está envuelto en el sobre de la API ({"dashboard": {...}}). Los archivos provisionados deben contener el propio modelo del dashboard.

El dashboard carga pero los paneles dicen que no se encuentra el data source. El panel referencia un UID que no está provisionado, o el archivo todavía tiene un marcador ${DS_...} de una exportación. Define uid en el archivo del data source, y usa el mismo UID en el JSON del dashboard.

Dos dashboards se pelean, o uno sigue revirtiéndose. Comparten un uid, o el mismo título en la misma carpeta. Haz que cada UID sea único en toda la instalación. Si una edición de la interfaz sigue siendo sobrescrita, es el archivo ganando, lo cual es por diseño a menos que el proveedor tenga allowUiUpdates: true.

Eliminé un archivo pero el dashboard sigue ahí. El proveedor tiene disableDeletion: true, o el dashboard se movió a una carpeta a mano. Elimínalo mediante la API, o desactiva disableDeletion.

El cambio de un data source se ignora en una configuración multiinstancia. Con varias réplicas de Grafana, una instancia solo actualiza un data source si el version del archivo es igual o mayor que el almacenado. Aumenta version cuando cambies el archivo.

La variable de entorno no se sustituye. La interpolación se aplica a los valores, no a las claves. No funciona en el JSON de dashboards, las anotaciones de reglas de alertas, los modelos de consulta, los mute timings ni las plantillas. Comprueba que la variable esté realmente definida en el contenedor (docker compose exec grafana env | grep NOMBRE).

Conflictos de importación de alertas. Existe un recurso con el mismo UID o nombre de una edición manual. Elimina el hecho a mano, o añádelo a un bloque delete... del archivo, y luego reinicia.

Los secretos dejaron de funcionar tras una reconstrucción. El secret_key cambió, así que los secretos almacenados no pueden descifrarse. Restaura la clave original, o vuelve a provisionar los data sources que necesitan credenciales.

La contraseña de admin no cambió. admin_password se aplica solo al crear la base de datos por primera vez. Usa grafana cli admin reset-admin-password o recrea el volumen.

Un recurso de Helm o del Operator no se sincroniza. Para el chart, revisa los logs del contenedor sidecar en busca de desajustes de etiquetas o namespaces. Para el Operator, ejecuta kubectl describe sobre el recurso y lee sus condiciones de estado.

Una rutina de cambios fiable

1. Cambia el archivo en una rama.
2. El CI ejecuta los linters anteriores e inicia un Grafana desechable a partir de los archivos.
3. Haz merge. El mecanismo de entrega reinicia o reconcilia Grafana.
4. Comprueba /api/health y los comandos de verificación.
5. Si se comporta mal, revierte el commit. Como los archivos son la verdad, revertir restaura el estado anterior.