datasource-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 と、ファイルにそのまま転記できる jsonData／secureJsonData ペイロードを含む value があります。

# 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	${ENV_VAR} として secureJsonData: の下	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 のどちらにするか尋ねてください。 フィールドは同じですが、出力ファイルと構文が異なります。形式を決めつけないでください。「X をプロビジョニングして」という依頼はどちらを意味する場合もあります。ユーザーが形式をすでに指定している場合（「X を Terraform で」など）に限り、質問を省略してください。YAML ファイルによるプロビジョニングは、依存関係のない標準の方法です。Terraform では公式の grafana/grafana プロバイダーが必要です。

選択肢	生成するファイル
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 プロバイダーのリソースです。引数名（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

または、UI で確認するには、<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 — 一般的なデータソース／ダッシュボードのプロビジョニング構造とプロビジョニングのパス。