Los data sources son lo primero de lo que depende cada dashboard y cada regla de alertas, así que son lo primero que hay que poner en archivos. Grafana lee YAML de la carpeta provisioning/datasources al arrancar, crea los data sources que encuentra y actualiza los que ya existen.

Un archivo básico

provisioning/datasources/datasources.yaml:

apiVersion: 1

datasources:
  - name: Prometheus
    uid: prometheus
    type: prometheus
    access: proxy
    orgId: 1
    url: http://prometheus:9090
    isDefault: true
    editable: false
    jsonData:
      timeInterval: 15s

Puedes poner uno o muchos data sources en un archivo, y usar varios archivos. Grafana carga todo lo que hay bajo la carpeta.

Los campos que más importan:

• name es el nombre visible.
• uid es el identificador estable al que hacen referencia los dashboards y las reglas de alertas. Si lo omites, Grafana genera uno, lo que hace frágil todo lo que lo referencia. Defínelo siempre.
• type es el ID del plugin, como prometheus, loki, tempo, postgres o elasticsearch.
• access: proxy significa que el servidor de Grafana hace las peticiones. Es la opción normal y mantiene las credenciales fuera de los navegadores.
• isDefault marca el data source con el que empiezan los paneles nuevos. Solo debería haber uno predeterminado por organización.
• editable: false bloquea los cambios en la interfaz, de modo que el archivo sigue siendo la autoridad.
• jsonData contiene ajustes no secretos, y las claves dependen del plugin.
• secureJsonData contiene secretos, que Grafana cifra en su base de datos.
• version se compara en las actualizaciones. Con varias instancias de Grafana compartiendo una base de datos, una instancia solo actualiza un data source cuando la versión del archivo es igual o mayor que la almacenada, así que súbela cuando cambies un archivo.

Credenciales sin hacer commit de ellas

Los archivos de provisioning admiten interpolación de variables de entorno en los valores (no en las claves) con $VAR o ${VAR}. Escribe $$ para un signo de dólar literal:

apiVersion: 1

datasources:
  - name: Postgres
    uid: postgres-main
    type: postgres
    url: $POSTGRES_HOST:5432
    user: $POSTGRES_USER
    editable: false
    jsonData:
      database: app
      sslmode: require
    secureJsonData:
      password: $POSTGRES_PASSWORD

Pasa POSTGRES_PASSWORD al contenedor desde tu almacén de secretos (consulta la guía de secretos). La contraseña nunca aparece en el repositorio, y Grafana la guarda cifrada tras cargarla.

Encabezados HTTP personalizados

Los nombres de los encabezados van en jsonData y sus valores en secureJsonData, numerados juntos:

datasources:
  - name: Mimir
    uid: mimir
    type: prometheus
    access: proxy
    url: https://mimir.example.com/prometheus
    jsonData:
      httpHeaderName1: X-Scope-OrgID
    secureJsonData:
      httpHeaderValue1: tenant-a

Autenticación básica y TLS

datasources:
  - name: Internal Prometheus
    uid: prom-internal
    type: prometheus
    access: proxy
    url: https://prometheus.internal:9090
    basicAuth: true
    basicAuthUser: grafana
    jsonData:
      tlsAuthWithCACert: true
    secureJsonData:
      basicAuthPassword: $PROM_PASSWORD
      tlsCACert: $PROM_CA_CERT

Correlaciona logs, métricas y trazas

Varios plugins enlazan data sources entre sí por UID, que es otra razón para definir los UID a mano. Por ejemplo, Loki puede convertir un campo de log en un enlace a trazas en Tempo:

datasources:
  - name: Loki
    uid: loki
    type: loki
    access: proxy
    url: http://loki:3100
    jsonData:
      derivedFields:
        - name: TraceID
          matcherRegex: 'trace_id=(\w+)'
          url: '$${__value.raw}'
          datasourceUid: tempo

Las claves de jsonData específicas de cada plugin varían según la versión, así que confírmalas en la documentación del data source. Una forma rápida de descubrirlas es configurar el data source una vez en una instancia de pruebas y leer el resultado desde la API (GET /api/datasources/uid/<uid>).

Eliminar y podar

deleteDatasources elimina data sources antes de procesar datasources. Úsalo cuando retires uno:

apiVersion: 1

deleteDatasources:
  - name: Old Graphite
    orgId: 1

Para hacer que la carpeta sea la verdad completa, añade prune: true (Grafana 11.1 o posterior). Los data sources provisionados que ya no estén en ningún archivo, o cuyo archivo se elimine, se borran en el siguiente arranque:

apiVersion: 1
prune: true

datasources:
  - name: Prometheus
    uid: prometheus
    type: prometheus
    url: http://prometheus:9090

Solo se podan los data sources provisionados. Los creados a mano en la interfaz se dejan intactos.

Aplica y verifica

Los data sources se leen al arrancar, así que reinicia Grafana, o llama al endpoint de recarga con autenticación básica de admin:

curl -X POST -u admin:$GRAFANA_ADMIN_PASSWORD \
  http://localhost:3000/api/admin/provisioning/datasources/reload

curl -s -u admin:$GRAFANA_ADMIN_PASSWORD \
  http://localhost:3000/api/datasources | jq '.[] | {name, uid, type, readOnly}'

Los data sources provisionados informan readOnly: true. Para confirmar la conectividad sin la interfaz, usa el endpoint de salud del data source:

curl -s -u admin:$GRAFANA_ADMIN_PASSWORD \
  http://localhost:3000/api/datasources/uid/prometheus/health

Si un data source no se cargó, revisa el log de arranque de Grafana en busca de líneas del logger de provisioning, que nombran el archivo y el error (normalmente la indentación del YAML, un campo desconocido o una variable de entorno ausente).