El comportamiento del servidor de Grafana se controla con un archivo INI y con variables de entorno que lo sobrescriben. Conocer las reglas te permite mantener toda la configuración en un repositorio y no cambiar nada a mano. Esta guía cubre dónde viven los archivos, cómo funciona la precedencia, cómo inyectar valores y secretos, y los ajustes que más tocarás.

Dónde vive la configuración

• defaults.ini se distribuye con Grafana y contiene todos los valores predeterminados (en conf/ para una instalación desde tarball). Nunca lo edites. Es la mejor referencia de qué opciones existen.
• grafana.ini es tu archivo de configuración. En los paquetes de Linux es /etc/grafana/grafana.ini, y la imagen oficial de Docker lee la misma ruta. Para una instalación desde tarball, usa conf/custom.ini. Pasa --config para apuntar a otro archivo.
• Las variables de entorno que empiezan por GF_ sobrescriben a ambos.

Precedencia, de menor a mayor: defaults.ini, luego tu grafana.ini, luego las variables de entorno GF_* (y los flags de línea de comandos). Pon en tu archivo solo las opciones que quieras cambiar, lo que mantiene los diffs pequeños.

En un archivo INI, las líneas que empiezan por ; son comentarios, así que para habilitar una opción quitas el ; inicial:

;http_port = 3000   # ignorada
http_port = 3000    # activa

Reinicia Grafana después de cambiar el archivo o el entorno.

Sobrescrituras con variables de entorno

El patrón es GF_<SECCIÓN>_<CLAVE>, con la sección y la clave en mayúsculas y cualquier . o - reemplazado por _:

GF_SECURITY_ADMIN_USER=owner          # [security] admin_user
GF_SERVER_ROOT_URL=https://grafana.example.com   # [server] root_url
GF_AUTH_GOOGLE_CLIENT_SECRET=newS3cretKey        # [auth.google] client_secret
GF_FEATURE_TOGGLES_newNavigation=true            # [feature_toggles] newNavigation
GF_DEFAULT_INSTANCE_NAME=my-instance             # instance_name de nivel superior, sin sección

Las variables de entorno son la opción natural para contenedores y Kubernetes, porque el mismo archivo puede compartirse entre todos los entornos mientras los valores específicos de cada entorno (URL, contraseñas) vienen de la plataforma.

Expansión de variables dentro del archivo

Los valores de las opciones pueden hacer referencia a variables de entorno o archivos con los proveedores $__env{} y $__file{}, o con el atajo ${NOMBRE}:

[paths]
logs = $__env{LOGDIR}/grafana

[security]
admin_password = ${GF_ADMIN_PASSWORD}
secret_key = $__file{/run/secrets/grafana_secret_key}

[database]
password = $__file{/etc/secrets/gf_sql_password}

$__file{} lee el archivo y recorta los espacios iniciales y finales, lo que lo hace ideal para secretos de Docker y Kubernetes montados como archivos. Grafana Enterprise también tiene un proveedor $__vault{}. La imagen oficial de Docker además acepta un sufijo __FILE en los nombres de variable (por ejemplo GF_SECURITY_ADMIN_PASSWORD__FILE=/run/secrets/admin_password), que se cubre en la guía de secretos.

Una base práctica

Un grafana.ini corto para una configuración pequeña tipo producción:

[paths]
provisioning = /etc/grafana/provisioning

[server]
protocol = http
http_port = 3000
domain = grafana.example.com
root_url = https://grafana.example.com/
; añade la subruta a root_url y activa esto cuando se sirva desde /grafana
; serve_from_sub_path = true

[database]
type = postgres
host = postgres:5432
name = grafana
user = grafana
password = $__file{/run/secrets/grafana_db_password}

[security]
admin_user = admin
admin_password = $__file{/run/secrets/grafana_admin_password}
secret_key = $__file{/run/secrets/grafana_secret_key}
cookie_secure = true

[users]
allow_sign_up = false

[analytics]
reporting_enabled = false
check_for_updates = false

[log]
mode = console
level = info

Puntos que conviene saber:

• Base de datos. El valor predeterminado es SQLite, que sirve para una sola instancia y para pruebas. Usa PostgreSQL o MySQL para producción, y siempre que haya más de una réplica de Grafana.
• root_url debe coincidir con la dirección pública, o los enlaces de las notificaciones de alertas y las redirecciones de OAuth serán incorrectos. Detrás de un reverse proxy que sirve Grafana bajo una subruta, añade la ruta a root_url y define serve_from_sub_path = true.
• admin_password solo se aplica la primera vez que Grafana crea su base de datos. Cambiar el ajuste después no cambia la contraseña del usuario admin existente.
• secret_key cifra los secretos que Grafana guarda para los data sources. Si lo cambias, los secretos almacenados previamente no pueden leerse y los data sources deben volver a provisionarse. Defínelo explícitamente y nunca lo rotes a la ligera.
• [paths] provisioning es donde Grafana busca las carpetas de provisioning. El valor predeterminado es /etc/grafana/provisioning en los paquetes.

SMTP para alertas por correo

[smtp]
enabled = true
host = smtp.example.com:587
user = grafana@example.com
password = $__file{/run/secrets/smtp_password}
from_address = grafana@example.com
from_name = Grafana
startTLS_policy = OpportunisticStartTLS

O lo mismo con GF_SMTP_ENABLED=true, GF_SMTP_HOST=..., etc. Verifica los nombres de las opciones en defaults.ini de tu versión.

Feature toggles

Las funciones experimentales o de adhesión voluntaria se activan en su propia sección:

[feature_toggles]
; lista los toggles que quieras, según la documentación de tu versión
newNavigation = true

Prefiere el archivo o el entorno a la interfaz, para que el ajuste sobreviva a una reconstrucción. Los toggles van y vienen entre versiones, así que revísalos en cada actualización.

Valida e inspecciona la configuración efectiva

Tras arrancar Grafana, puedes comparar lo que definiste con lo que está en vigor:

curl -s -u admin:$GRAFANA_ADMIN_PASSWORD http://localhost:3000/api/admin/settings | jq '.server'

Este endpoint de administración devuelve los ajustes fusionados, y los valores de las claves sensibles aparecen enmascarados. Es la forma más rápida de confirmar que una variable de entorno realmente surtió efecto. Si no lo hizo, comprueba la ortografía de la variable (mayúsculas, guiones bajos) y que la opción exista en defaults.ini.

Mantenlo en Git

• Haz commit de grafana.ini y de un .env.example con valores de ejemplo.
• Mantén los secretos reales fuera del repositorio: móntalos como archivos, inyéctalos como variables de entorno o haz commit de ellos cifrados (consulta la guía de secretos).
• Revisa los cambios de defaults.ini cuando actualices Grafana. Las versiones nuevas añaden opciones y a veces deprecan las antiguas.