ダッシュボードは JSON ドキュメントなので、Git に保存しやすいものです。ダッシュボードプロバイダーは、Grafana に監視するフォルダーを伝え、Grafana はそこで見つけたすべての JSON ファイルを読み込み、その後も変更を確認し続けます。このガイドでは、プロバイダーのファイル、フォルダーの対応付け、ダッシュボードの JSON そのもの、そして UI のみの編集に終わらずにダッシュボードを作成するためのワークフローを説明します。

プロバイダーのファイル

provisioning/dashboards/providers.yaml:

apiVersion: 1

providers:
  - name: default
    orgId: 1
    type: file
    disableDeletion: false
    updateIntervalSeconds: 30
    allowUiUpdates: false
    options:
      path: /var/lib/grafana/dashboards
      foldersFromFilesStructure: true

各フィールドの役割：

• name は必須で、プロバイダー間で一意である必要があります。
• options.path は、Grafana が JSON ファイルを探してスキャンするディレクトリです。コンテナ内に存在している必要があります。
• updateIntervalSeconds は、Grafana がパスを再スキャンする頻度です。すべてのダッシュボードは起動時に読み込まれ、その後の変更は、再起動なしで取り込まれます。
• allowUiUpdates：false の場合、プロビジョニングされたダッシュボードは UI から保存できず、Git が権威を持ち続けます。true の場合、UI での保存は、ソースファイルが変更されるまでデータベースに保持され、変更された時点で、ファイルがそれを上書きします。
• disableDeletion：true の場合、ファイルを削除しても、そのダッシュボードは Grafana から削除されません。Git が真実であるべきなら、false のままにします。
• folder または folderUid は、すべてのダッシュボードを 1 つの名前付きフォルダーに配置します。これらがなければ、ダッシュボードはルートに入ります。
• foldersFromFilesStructure: true は、path のサブディレクトリを Grafana のフォルダーに対応付けます。これを使うときは、folder と folderUid を空のままにしてください。入れ子のフォルダーはサポートされていないため、サブディレクトリは 1 階層が限度です。

リポジトリをフォルダーごとに整理する

foldersFromFilesStructure: true の場合、この構成は：

dashboards/
├── infrastructure/
│   ├── node-exporter.json
│   └── kubernetes.json
└── applications/
    └── webapp.json

2 つの Grafana フォルダー、infrastructure と applications を作成し、その中にダッシュボードを置きます。グループごとに異なる設定が必要な場合、たとえば「scratch」エリア用に allowUiUpdates: true を持つ 1 つのプロバイダーを使うような場合は、代わりに別々のプロバイダーを使います。

ダッシュボードの JSON の要点

プロビジョニングされるファイルには、ダッシュボードのモデル自体が含まれ、最上位に uid と title がある必要があります。HTTP API が使う {"dashboard": {...}, "overwrite": true} のエンベロープで包まないでください。これは、「Dashboard title cannot be empty」エラーの一般的な原因です。

{
  "uid": "webapp-overview",
  "title": "Webapp Overview",
  "tags": ["webapp", "provisioned"],
  "schemaVersion": 39,
  "version": 1,
  "refresh": "30s",
  "time": { "from": "now-6h", "to": "now" },
  "templating": {
    "list": [
      {
        "name": "namespace",
        "type": "query",
        "datasource": { "type": "prometheus", "uid": "prometheus" },
        "query": "label_values(kube_pod_info, namespace)"
      }
    ]
  },
  "panels": [
    {
      "id": 1,
      "type": "timeseries",
      "title": "Request rate",
      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
      "datasource": { "type": "prometheus", "uid": "prometheus" },
      "targets": [
        {
          "refId": "A",
          "expr": "sum(rate(http_requests_total{namespace=\"$namespace\"}[5m]))",
          "datasource": { "type": "prometheus", "uid": "prometheus" }
        }
      ]
    }
  ]
}

コードとして適切に動作するダッシュボードのためのガイドライン：

• 安定した uid を設定する。 Grafana は、読み込みのたびに、その UID のダッシュボードを更新します。ファイル間で UID を再利用したり、同じフォルダーで同じタイトルを 2 回使ったりしないでください。
• 数値の id を省略する。 データベースが割り当てるもので、インスタンス間で異なります。
• データソースは UID で参照する。 プロビジョニングした uid と一致させます（{"type": "prometheus", "uid": "prometheus"}）。共有用にエクスポートされたダッシュボードには、${DS_PROMETHEUS} のようなプレースホルダーが含まれていることがあり、実際の UID か、データソースのテンプレート変数に置き換える必要があります。
• 環境変数の補間は、ダッシュボードの JSON の中では機能しません。 環境ごとの違いには、ダッシュボードのテンプレート変数を使います。
• Grafana 13 は、内部でダッシュボードをより新しいスキーマで保存し、古い JSON を読み込み時に移行するため、既存のファイルは引き続き機能します。

UI で作成してから、結果を Git に戻す

パネルの JSON を手で書くのは遅いため、ほとんどのチームは UI で下書きしてエクスポートします。ファイルを真実に保つワークフローは次のとおりです。

1. プロバイダーが allowUiUpdates: true を持つテスト用のインスタンス（前のガイドの compose の構成）を実行します。
2. UI でダッシュボードを構築または調整します。
3. ダッシュボードの共有またはエクスポートのメニューから、JSON としてエクスポートします。データソースを入力に置き換えたい場合は、外部への共有用にエクスポートするオプションを選び、その後、実際の UID を設定します。
4. 数値の id を削除し、安定した uid を設定して、ファイルをリポジトリのフォルダーに commit します。
5. プルリクエストを開きます。本番の Grafana はマージ後にそれを取り込み、そこでの allowUiUpdates: false が、誰も乖離させないようにします。

API を通じて既存のダッシュボードを取得することもできます。

curl -s -u admin:$GRAFANA_ADMIN_PASSWORD \
  http://localhost:3000/api/dashboards/uid/webapp-overview \
  | jq '.dashboard | del(.id)' > dashboards/applications/webapp.json

diff が実際の変更を示すように、JSON を一貫して整形してください（たとえば jq -S .）。

コードからダッシュボードを生成する

多くのダッシュボードが同じ形を共有しているなら、コピーする代わりに JSON を生成します。Grafana Foundation SDK（Go、TypeScript、Python、PHP、Java）は、型付きのコードからダッシュボードを構築し、その出力は、プロバイダーのフォルダーに置くのと同じ JSON です。このシリーズの Foundation SDK のガイドで説明します。

CI で検証する

Grafana に届く前に、ミスを見つけます。

# 有効な JSON か？
jq empty dashboards/**/*.json
# すべてのファイルに uid と title があるか？
for f in dashboards/*/*.json; do
  jq -e '.uid and .title' "$f" >/dev/null || echo "missing uid/title: $f"
done
# uid の重複は？
jq -r '.uid' dashboards/*/*.json | sort | uniq -d

適用して確認する

変更は、updateIntervalSeconds 以内に取り込まれます。再スキャンを強制するには：

curl -X POST -u admin:$GRAFANA_ADMIN_PASSWORD \
  http://localhost:3000/api/admin/provisioning/dashboards/reload

curl -s -u admin:$GRAFANA_ADMIN_PASSWORD \
  "http://localhost:3000/api/search?type=dash-db" | jq '.[] | {title, uid, folderTitle}'

ダッシュボードが現れない場合は、プロビジョニングのロガーからの、起動時と再スキャン時のログの行を確認してください。よくある原因は、コンテナ内に存在しないパス、API のエンベロープで包まれた JSON、uid を共有する 2 つのファイルです。