datasources-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 と、ファイルにそのまま転記できる 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 スキル（§ データソースのプロビジョニング）にある汎用構造を参照できます。また、フィールド名はあくまで最善努力によるもので、プラグイン作成者が保証するものではないとユーザーに伝えられます。

注意：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	${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 — 汎用的なデータソース／ダッシュボードのプロビジョニング構造とプロビジョニングパス。