datasources-provisioning

工作流

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

首先询问此问题（仅当用户已经明确说明时才跳过）：

• 从头开始 — 用户说出要配置的插件类型 → 继续执行步骤 2。
• 从现有数据源开始，且该数据源位于正在运行的实例中 → 跳转到转换现有数据源，然后返回步骤 6。

2. 确定完整的插件 ID

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

• 已经是规范 ID（包含 -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 技能中的通用结构（§ 数据源配置）也可以告知用户，字段名称仅为尽力而为的参考，并非插件作者提供的权威信息。

注意：grafana-oss 技能可在 grafana-core 插件中使用，也可从 https://github.com/grafana/skills 仓库作为独立技能使用

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 — 通用数据源／仪表板配置结构和配置路径。