datasource-provisioning

工作流

1. 询问起点：从头开始，还是使用现有数据源？

先问这个问题（仅当用户已经明确说明时才跳过）：

• 从头开始 — 用户指定要配置的数据源类型 → 继续执行第 2 步。
• 使用正在运行的实例中的现有数据源 → 跳转到转换现有数据源，然后返回第 6 步。

2. 确定完整的插件 ID

配置时需要使用规范的插件 ID（<org>-<name>-datasource），而不是用户可能提到的简称。

• 已是规范格式（包含 -datasource 或 -app）？直接使用：yesoreyeram-infinity-datasource。
• 只有简称（例如 infinity、clickhouse）？使用 filter=<keyword> 查询目录 API：

  curl -s "https://grafana.com/api/plugins?filter=infinity" \
    | jq -r '.items[] | "\(.slug)\t\(.name)"'
  # → yesoreyeram-infinity-datasource    Infinity
  

  如果匹配项不止一个 → 展示候选项并询问用户要选哪一个。

以下代码片段以 Infinity（yesoreyeram-infinity-datasource）为示例 — 在每条命令和每项输出中，将其替换为此处确定的 ID（以及第 3 步确定的版本）。

3. 确定最新版本

curl -s "https://grafana.com/api/plugins/yesoreyeram-infinity-datasource" | jq -r '.version'

切勿对版本号进行硬编码 — CDN 路径会固定到特定版本，过时的版本会返回 404。

4. 获取设置架构（主要结构化来源）

https://plugins-cdn.grafana.net/<PLUGIN_ID>/<VERSION>/public/plugins/<PLUGIN_ID>/schema/dsconfig.json

ID=yesoreyeram-infinity-datasource
VER=$(curl -s "https://grafana.com/api/plugins/$ID" | jq -r '.version')
curl -sf "https://plugins-cdn.grafana.net/$ID/$VER/public/plugins/$ID/schema/dsconfig.json"

此文件符合 dsconfig 架构规范 — 这是解读该文件的事实来源。不要凭记忆重新推断字段含义（仅 valueType 就可能是 string、number、boolean、array、object、map、any）；遇到非简单标量的字段时，请查阅该规范：

• 说明文档：https://raw.githubusercontent.com/grafana/dsconfig/refs/heads/main/dsconfig/schema.md
• 元架构（定义每个 dsconfig.json 的格式）：https://raw.githubusercontent.com/grafana/dsconfig/refs/heads/main/dsconfig/schema.json

配置时需要从每个字段中获取：key（配置键）、valueType、target（root | jsonData | secureJsonData）和 validations（对于 auth_method 等选择器，应遵循 allowedValues）。示例说明（schemaVersion: "v1"）：

{
  "pluginType": "yesoreyeram-infinity-datasource",
  "fields": [
    {
      "key": "auth_method",
      "valueType": "string",
      "target": "jsonData",
      "validations": [
        {
          "type": "allowedValues",
          "values": [
            "none",
            "basicAuth",
            "apiKey",
            "bearerToken",
            "oauth2",
            "aws",
            "azureBlob"
          ]
        }
      ]
    }
  ]
}

只选择与用户需求相关的字段（所选身份验证方式和连接），不要选择全部字段。每个字段的 description 都会说明它对应的身份验证方式。

如需现成的示例配置，请获取 v0alpha1.json：

https://plugins-cdn.grafana.net/<PLUGIN_ID>/<VERSION>/public/plugins/<PLUGIN_ID>/schema/v0alpha1.json

ID=yesoreyeram-infinity-datasource
VER=$(curl -s "https://grafana.com/api/plugins/$ID" | jq -r '.version')
curl -sf "https://plugins-cdn.grafana.net/$ID/$VER/public/plugins/$ID/schema/v0alpha1.json"

已完成的示例位于 settingsExamples.examples 中，这是一个以场景为键的对象（例如 apiKey、oauth2ClientCredentials）。每个条目都有一个 summary/description（场景说明）和一个 value，其中包含可直接写入文件的 jsonData/secureJsonData 有效负载：

# list scenarios, then pull one payload
... | jq -r '.settingsExamples.examples | keys[]'
... | jq '.settingsExamples.examples.apiKey.value'

5. 未发布架构时的回退方案

如果 schema/dsconfig.json 返回 404（较旧的插件）：

• 最后手段：使用 grafana-oss（§ 数据源配置）中的通用结构 — 告知用户字段名称仅为尽力推测，并非插件作者提供的权威信息。

6. 按照各字段的 target 映射

target	YAML	Terraform（grafana_data_source）
root	数据源的顶层键（url、basicAuth、basicAuthUser）	顶层参数（url）／json_data_encoded 内部
jsonData	位于 jsonData: 下	json_data_encoded = jsonencode({ … }) 内的键
secureJsonData	位于 secureJsonData: 下，值为 ${ENV_VAR}	通过 sensitive 变量设置 secure_json_data_encoded = jsonencode({ … }) 内的键

标量值使用各字段的 valueType（YAML 中的 string 加引号，boolean 使用 true／false，number 不加引号）。切勿将真实密钥直接写入配置。嵌套对象（oauth2、aws）和数组（allowedHosts、scopes）直接映射。

始终设置 access（root 目标），并将其默认设为 proxy——查询通过 Grafana 服务路由（安全默认值）；只有用户明确要求时，才使用 direct（浏览器 → 数据源）。在 Terraform 中，该参数名为 access_mode。

7. 先询问格式，再生成文件

现在询问：YAML 还是 Terraform？ 字段相同，但输出文件和语法不同。不要擅自假设：“provision X” 可能指其中任一种；只有用户已指定格式（例如“用 terraform 配置 X”）时，才跳过提问。YAML 文件配置是原生且零依赖的方式；Terraform 需要官方的 grafana/grafana provider。

选项	生成
YAML 配置文件	provisioning/datasources/<name>.yaml
Terraform	<name>.tf（grafana_data_source 资源）

<name> 只是文件的基本名称——仅用于标识，因为两个加载器都会读取目录中的所有文件，不受文件名影响。默认使用插件名称。

YAML → provisioning/datasources/<name>.yaml：

apiVersion: 1
datasources:
  - name: Infinity # must be unique across the instance — collides even with a different datasource type
    type: yesoreyeram-infinity-datasource # = pluginType from the schema
    access: proxy # always set; default proxy (route queries through the Grafana server)
    uid: infinity-ds # also unique and immutable so dashboards can reference it
    jsonData:
      auth_method: apiKey # value from validations.allowedValues
      apiKeyKey: X-API-Key
      apiKeyType: header
      allowedHosts:
        - https://api.example.com
    secureJsonData:
      apiKeyValue: ${API_KEY} # env var ref, never a literal secret
    editable: false

Terraform → <name>.tf：

variable "api_key" {
  type      = string
  sensitive = true
}

resource "grafana_data_source" "infinity" {
  type        = "yesoreyeram-infinity-datasource"
  name        = "Infinity"
  uid         = "infinity-ds"
  access_mode = "proxy" # always set; default proxy (route queries through the Grafana server)

  json_data_encoded = jsonencode({
    auth_method  = "apiKey"
    apiKeyKey    = "X-API-Key"
    apiKeyType   = "header"
    allowedHosts = ["https://api.example.com"]
  })

  secure_json_data_encoded = jsonencode({
    apiKeyValue = var.api_key
  })
}

grafana_data_source 来自 grafana/grafana provider——这是参数名称（access_mode、json_data_encoded、secure_json_data_encoded）的权威参考。此文件仅包含资源；用户需自行提供 required_providers + provider "grafana" 块及凭据。

8. 将文件返回给用户

将完整文件放在单个代码块中，供用户复制并粘贴到其环境中——并说明文件应放置的位置：

• YAML → provisioning/datasources/<name>.yaml（在 Grafana 启动时或重新加载配置时应用）。
• Terraform → 用户的 Terraform 配置，并通过 terraform apply 应用。

可选：告知用户应用后如何确认配置生效：

curl -s https://grafana.example.com/api/datasources/uid/<uid>/health \
  -H "Authorization: Bearer <token>"
# { "status": "OK" }    → working
# { "status": "ERROR" } → URL unreachable or auth misconfigured

也可以在界面中验证：访问 <https://grafana.example.com>/connections/datasources/edit/<uid> 并点击 Test。

转换现有数据源

若要将运行中的实例中已配置的数据源编码为配置，请通过 Grafana MCP 服务（grafana/mcp-grafana）读取其配置。

前提条件： Grafana MCP 服务已连接，并启用了 Datasources 工具集（其中保存了实例凭据）。如果该服务不可用，请勿支持此路径——绝不要要求用户在聊天中粘贴 Grafana 令牌。请改用从头开始的工作流。

1. 使用 MCP 工具查找数据源——通过 list_datasources 浏览，然后通过 get_datasource（按 uid 或 name）获取完整配置。
2. 结果中直接包含所有非机密字段：type、uid、url、access、basicAuth、basicAuthUser 和完整的 jsonData 对象。请原样复制。
3. 绝不会返回机密信息。 secureJsonFields 映射会列出哪些机密键已设置（例如 {"apiKeyValue": true}），但不包含其值。对于其中值为 true 的每个键，请在 secureJsonData 中填入 ${ENV_VAR} 占位符。
4. 对照架构（步骤 4）核实机密键名和 target 的位置，然后按常规从步骤 6（映射）和步骤 7（输出）继续操作。

相关内容

• grafana-oss — 通用数据源 / 仪表板配置结构和配置路径。