ダッシュボードの JSON を手で書くのはスケールせず、UI からエクスポートすると、UI が実質的な情報源のままになります。Grafana の observability-as-code ツールは、その両方に対処します。Foundation SDK は型付きのコードからダッシュボードを生成し、Git Sync は Grafana が Git リポジトリ内のダッシュボードを読み書きするようにし、gcx CLI はターミナルからリソースを push して pull します。これらの機能のいくつかは新しく、一部の API は alpha とマークされているため、お使いのバージョンのドキュメントを確認してください。

Foundation SDK でダッシュボードを生成する

Foundation SDK は、Go、TypeScript、Python、PHP、Java で、ダッシュボード、パネル、クエリのビルダーを提供します。型付き言語でダッシュボードを記述し、build() を呼び出すと、ダッシュボードの JSON が生成されます。それはコードなので、コンパイル時のチェック、再利用（標準的なサービスの行を構築する関数）、通常のコードレビューが得られます。

お使いの言語向けにインストールします。たとえば：

# Go
go get github.com/grafana/grafana-foundation-sdk/go@latest

# TypeScript
npm install @grafana/grafana-foundation-sdk

Python、PHP、Java のパッケージは、SDK のドキュメントに記載されています。Grafana 10 以降を対象としています。

一般的なワークフロー：

1. ダッシュボードを定義し、それぞれの JSON を dashboards/<name>.json に書き込む小さなプログラムを書きます。
2. CI で実行します。
3. 生成された JSON を commit するか、ビルドのアーティファクトとして公開します。
4. すでに使っているメカニズムで JSON を配信します。プロバイダーのフォルダー、ConfigMap、GrafanaDashboard リソース、Terraform、または Git Sync です。

# CI ジョブの概略
steps:
  - run: npm ci
  - run: npx tsx dashboards/generate.ts --out dashboards/generated
  - run: git diff --exit-code dashboards/generated   # 生成されたファイルが古ければ失敗する

git diff --exit-code のチェックにより、誰も生成された JSON を手作業で編集せず、コードと出力が同期した状態に保たれます。

Git Sync

Git Sync により、Grafana はダッシュボードを JSON として Git リポジトリに保存できます。変更は双方向に流れます。Grafana の UI での編集は commit またはプルリクエストになり、リポジトリでのマージされた変更は Grafana に現れます。Grafana はデフォルトで 60 秒ごとにリポジトリをポーリングし、webhook を使えば更新がほぼ即座に届きます。Git Sync は、Grafana 13 のすべてのエディションで一般提供されています。GitHub（App 認証）、GitHub Enterprise、GitLab、Bitbucket、そして「Pure Git」のリポジトリタイプによるプレーンな Git をサポートしています。

Repository リソースを使って、完全にコードとして設定できます。repository.yaml を作成します。

apiVersion: provisioning.grafana.app/v0alpha1
kind: Repository
metadata:
  name: my-repo
spec:
  title: My Repository
  type: github
  github:
    url: https://github.com/<org>/<repo>
    branch: main
    path: grafana/
  sync:
    enabled: true
    intervalSeconds: 60
    target: folder
  workflows:
    - write
    - branch
secure:
  token:
    create: '<git-personal-access-token>'

フィールドに関する注意：

• type は、github、githubEnterprise、gitlab、bitbucket、git のいずれかで、それぞれ独自のブロックがあります。Bitbucket とプレーンな Git には、tokenUser も必要です。
• path は、Grafana が所有するリポジトリ内のフォルダーです。
• workflows は、UI での保存の動作を制御します。write はブランチに直接 commit し、branch はプルリクエストを開きます。
• sync.target は、folder（デフォルト）または folderless です。
• secure.token は認証情報を運ぶため、spec ではなくシークレットとして保存されます。トークンの代わりに、spec.connection.name で GitHub App や OAuth app の接続を使うこともできます。それらには別の connection.yaml が必要です。
• API バージョンは v0alpha1 なので、フィールド名は、リリース間で変更される可能性があります。

gcx（次のセクション）、または好みに応じて Grafana の UI から適用します。

Git Sync が最も得意とするのは、UI で作業する作成者と Git を優先するエンジニアが、すべての変更でプルリクエストのレビューを伴う、1 つの信頼できる情報源を共有できるようにすることです。大規模なインスタンスに導入する前に、使用上の制限のページをお読みください。大量のダッシュボードをプロビジョニングすることには、パフォーマンス上の考慮事項があるためです。

gcx CLI

gcx は、リソース、そして Grafana Cloud では他の製品も扱うための、Grafana のコマンドラインです。Grafana Cloud と、オープンソースまたは Enterprise の Grafana 12 以降で動作し、以前の grafanactl ツールに代わるものです（移行は主にコマンドの名前の変更で、grafanactl resources serve は gcx dev serve になります）。プロジェクトのリポジトリからインストールし、ドキュメントに記載されているとおりに、Grafana の URL とトークンでコンテキストを設定します。

一般的なコマンド：

# ローカルのリソースファイルを Grafana に push する
gcx resources push --path ./resources

# 存在するものを一覧表示するか、1 つのリソースを調べる
gcx resources get repositories
gcx resources get repository/my-repo -o yaml

# 編集または削除する
gcx resources edit repository/my-repo
gcx resources delete repository/my-repo

# 開発中にダッシュボードをライブでプレビューする
gcx dev serve

CI で、リポジトリからリソース定義を push するために使うか、SDK でダッシュボードを構築しながらローカルで使います。

アプローチの選択

状況	使うもの
多数の似たダッシュボード、または再利用可能な構成要素	Foundation SDK。任意のメカニズムで配信
作成者は UI で作業するが、Git を記録として持ちたい	Git Sync
Kubernetes の GitOps、ダッシュボードごとに 1 つのオブジェクト	Grafana Operator
チームと権限を含む、プラットフォーム全体の自動化	Terraform
1 つの Grafana、静的な JSON ファイル	シンプルなプロバイダーのフォルダー

これらはうまく組み合わせられます。SDK で JSON を生成し、リポジトリに commit し、Git Sync やプロバイダーのフォルダーに配信させます。

確認する

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

リポジトリの同期の問題については、Grafana でのリポジトリのステータス（Administration の Provisioning の下）と、Grafana のサーバーログを確認してください。典型的な問題は、期限切れのトークン、間違ったブランチやパス、Grafana に到達できない webhook です。