Grafana

从 YAML Provision 数据源

在文件中而不是 UI 中定义数据源、凭据和自定义头。

10 min 初级

数据源是每个仪表板和告警规则所依赖的第一样东西,所以它们是最先应当放进文件的东西。Grafana 在启动时读取 provisioning/datasources 文件夹中的 YAML,创建它找到的数据源,并更新已存在的那些。

一个基本文件

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

你可以在一个文件中放一个或多个数据源,也可以使用多个文件。Grafana 会加载该文件夹下的所有内容。

最重要的字段:

name 是显示名称。
uid 是仪表板和告警规则引用的稳定标识符。如果省略它,Grafana 会生成一个,这会让所有引用它的内容变得脆弱。请始终设置它。
type 是插件 ID,例如 prometheus、loki、tempo、postgres 或 elasticsearch。
access: proxy 表示由 Grafana 的服务器发出请求。这是正常的选择,能让凭据远离浏览器。
isDefault 标记新面板默认使用的数据源。每个组织只应有一个默认数据源。
editable: false 阻止在 UI 中更改,使文件保持权威。
jsonData 保存非机密设置,键取决于插件。
secureJsonData 保存密钥,Grafana 会在其数据库中加密它们。
version 在更新时被比较。当多个 Grafana 实例共享一个数据库时,只有当文件的版本与已存储的相同或更高时,某个实例才会更新数据源,所以更改文件时请提升它。

不提交凭据

Provisioning 文件支持在值(不包括键)中进行环境变量插值,使用 $VAR 或 ${VAR}。用 $$ 表示字面的美元符号:

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

从你的 secret 存储将 POSTGRES_PASSWORD 传入容器(参见密钥指南)。密码永远不会出现在仓库中,Grafana 加载后会将其加密存储。

自定义 HTTP 头

头的名称放在 jsonData 中,其值放在 secureJsonData 中,编号相互对应:

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

基本认证与 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

关联日志、指标和追踪

一些插件按 UID 将数据源相互链接,这是手动设置 UID 的另一个原因。例如,Loki 可以把日志字段变成指向 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

特定于插件的 jsonData 键会因版本而异,所以请在数据源的文档中确认。一个发现它们的快捷方法是在临时实例中配置一次数据源,然后通过 API 读取结果(GET /api/datasources/uid/<uid>)。

删除与 prune

deleteDatasources 会在处理 datasources 之前移除数据源。当你要淘汰某个数据源时使用它:

apiVersion: 1

deleteDatasources:
  - name: Old Graphite
    orgId: 1

要让该文件夹成为完整的事实,请添加 prune: true(Grafana 11.1 或更新版本)。这样,不再位于任何文件中,或其文件已被删除的被 provision 的数据源,会在下次启动时被移除:

apiVersion: 1
prune: true

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

只有被 provision 的数据源才会被 prune。在 UI 中手工创建的数据源不受影响。

应用与验证

数据源在启动时读取,所以请重启 Grafana,或使用管理员基本认证调用 reload 端点:

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}'

被 provision 的数据源会报告 readOnly: true。要在不使用 UI 的情况下确认连通性,请使用数据源健康端点:

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

如果某个数据源没有加载,请检查 Grafana 的启动日志中来自 provisioning logger 的行,它们会指明文件和错误(通常是 YAML 缩进、未知字段或缺失的环境变量)。

RackMint