La configuración como código solo funciona si el repositorio puede compartirse, y un repositorio que contiene contraseñas no puede. Grafana te ofrece varias formas de mantener los secretos fuera de los archivos y a la vez definir todo de forma declarativa. Esta guía muestra dónde aparecen los secretos, cómo inyectarlos y qué hacer con los secretos que Grafana guarda por sí mismo.

Dónde aparecen los secretos

• Ajustes del servidor: la contraseña de admin, la contraseña de la base de datos, las credenciales SMTP, los client secrets de OAuth y el secret_key.
• Data sources: contraseñas, tokens y claves TLS en secureJsonData.
• Contact points: URL de webhooks, claves de API y claves de enrutamiento en settings.
• Provisioning para otras herramientas: Terraform, el Operator y Git Sync necesitan cada uno un token de API o una credencial de Git.

Método 1: variables de entorno

La opción más simple. El YAML de provisioning admite $VAR y ${VAR} en los valores, y grafana.ini admite ${VAR} y $__env{VAR}:

# provisioning/datasources/postgres.yaml
datasources:
  - name: Postgres
    uid: postgres-main
    type: postgres
    url: $POSTGRES_HOST:5432
    secureJsonData:
      password: $POSTGRES_PASSWORD

# grafana.ini
[security]
admin_password = ${GF_ADMIN_PASSWORD}

Reglas que conviene recordar:

• La interpolación funciona solo en valores, no en claves.
• Usa $$ cuando necesites un signo de dólar literal (por ejemplo en una plantilla como {{ $$labels }}).
• No funciona dentro del JSON de dashboards, y no se aplica en algunos campos de alertas: anotaciones de reglas, modelos de consulta, relativeTimeRange, nombres e intervalos de mute timings y plantillas de notificación.

En Docker Compose, lee las variables de un archivo .env sin versionar o de tu almacén de secretos de CI. En Kubernetes, asigna un Secret al contenedor (ver más abajo).

Método 2: secretos como archivos

Grafana lee el contenido de un archivo en un ajuste con $__file{}, que recorta los espacios circundantes:

[database]
password = $__file{/run/secrets/grafana_db_password}

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

Esto se adapta a los secretos de Docker y a los Secrets de Kubernetes montados como archivos, y evita filtrar valores mediante docker inspect o los entornos de procesos. La imagen oficial de Docker también acepta un sufijo __FILE en los nombres de variable GF_*:

services:
  grafana:
    image: grafana/grafana:13.1.0
    environment:
      GF_SECURITY_ADMIN_PASSWORD__FILE: /run/secrets/grafana_admin_password
    secrets:
      - grafana_admin_password

secrets:
  grafana_admin_password:
    file: ./secrets/grafana_admin_password.txt

Método 3: Secrets de Kubernetes

Guarda las credenciales en un Secret y exponlas como variables de entorno:

apiVersion: v1
kind: Secret
metadata:
  name: grafana-secrets
  namespace: monitoring
type: Opaque
stringData:
  admin-password: change-me
  slack-webhook-url: https://hooks.slack.com/services/XXX/YYY/ZZZ
  postgres-password: change-me-too

env:
  - name: SLACK_WEBHOOK_URL
    valueFrom:
      secretKeyRef:
        name: grafana-secrets
        key: slack-webhook-url

El chart de Helm de Grafana puede tomar un Secret existente para el usuario admin y montar otros como variables de entorno, lo que muestra la guía de Kubernetes. No hagas commit de ese Secret como YAML plano. Cífralo, o genéralo desde un gestor de secretos:

• SOPS con Flux o Argo CD: haz commit de grafana-secrets.yaml cifrado y deja que el controlador GitOps lo descifre en el clúster. La serie de Flux de esta biblioteca tiene una guía de SOPS.
• External Secrets Operator o un driver CSI: sincroniza secretos desde Vault, AWS Secrets Manager u otro almacén, y haz commit solo de la referencia.

El secret_key y los secretos almacenados

Grafana cifra los secretos que guarda en su base de datos (como las contraseñas de data sources) con el ajuste secret_key. Dos consecuencias:

• Defínelo explícitamente y mantenlo igual entre reinicios, réplicas y reconstrucciones. El valor predeterminado es público, así que dejarlo sin definir debilita ese cifrado.
• No lo cambies a la ligera. Si cambia, los valores cifrados existentes no pueden descifrarse. Como los data sources se provisionan desde archivos, volver a provisionar con la nueva clave los restaura, pero los secretos introducidos solo en la interfaz se pierden.

Salvedad sobre la contraseña de admin

admin_password solo surte efecto cuando Grafana crea su base de datos por primera vez. Para cambiarla después, restablécela mediante la CLI dentro del contenedor o mediante la API, o recrea la base de datos:

grafana cli admin reset-admin-password 'new-password'

Mejor aún, pasa a las personas a SSO para que la cuenta de admin local sea solo un acceso de emergencia, y guarda su contraseña en tu gestor de secretos.

Tokens para las herramientas que rodean a Grafana

• Terraform y el Operator se autentican con un token de service account. Crea la service account con un rol mínimo, guarda el token en tu almacén de secretos de CI o del clúster y rótalo según un calendario.
• Git Sync necesita una credencial del proveedor de Git: un personal access token, o una conexión de GitHub App u OAuth app. Pasa el token en el bloque secure del recurso Repository, para que se guarde como secreto y no en la especificación.
• La API de provisioning de administración acepta solo autenticación básica con un usuario admin, no tokens de API, así que restringe quién puede llegar a esos endpoints.

Lista de comprobación

• Ningún secreto en texto plano en el historial de Git. Si se coló alguno, rótalo, no te limites a eliminar el commit.
• secret_key definido explícitamente y guardado en tu gestor de secretos.
• Cada entorno tiene su propia contraseña de base de datos, contraseña de admin y tokens de API.
• .env y las carpetas de secretos están en .gitignore, y el CI escanea los commits en busca de secretos.