こんにちは、IT 本部 IT 基盤部第一グループの窪田です。本記事では、AI と Grafana Foundation SDK を活用したダッシュボード作成フロー、環境差を扱うビルド設計、Git Sync による段階的な移行方法を紹介します。
Grafana のダッシュボードは Web UI から直感的に作成・編集できます。私たちのチームでは、この試作しやすさを活かしつつ、MCP を通じた既存ダッシュボードや実データの調査と、クエリ・パネル構成の作成に AI を活用したいと考えました。
AI の作業結果を継続的に活用するには、レビュー、検証、再利用できる形で残し、複数環境へ一貫して展開できる仕組みが必要です。そこで、AI の成果をコードとして管理する方法として、ダッシュボードの IaC 化を選びました。
今回は Grafana Foundation SDK（以下、Grafana SDK）の TypeScript 版を採用し、ダッシュボード定義と環境設定を管理しています。AI の生成結果は、型チェック、JSON の検証、Grafana 上での表示確認を経てリポジトリに取り込みます。
私たちのチームでは、アラートルール、コンタクトポイント、通知ポリシーを別の仕組みでコード管理しているため、本記事ではダッシュボードの設計と移行に焦点を当てます。
AI 活用を支える IaC
AI と Grafana SDK を活用する前は、Web UI でメトリクスを確認し、PromQL やパネル配置を試行錯誤しながら作る方が現実的でした。生成される JSON は数千行に及ぶことがあり、手作業でコードとして記述・レビューする負担から、過去に IaC 化を断念したことがありました。
一方で、Web UI 中心の管理では変更が画面内に閉じ、変更の意図を後から追いにくく、環境間の差分も増えやすくなります。AI を継続的に活用するためにも、その成果をレビュー・検証できるコードとして蓄積する必要がありました。
今回は、Grafana SDK による型付きの定義と AI によるコード記述の補助を組み合わせ、IaC 化に再挑戦しました。
Grafana SDK を選んだ理由
Grafana SDK を使うことで、複雑なダッシュボード JSON を直接記述せず、型付きのコードとして定義できます。共通パネルの再利用や、生成物のビルド・検証にもつなげやすいため、JSON をそのまま管理する方式ではなく Grafana SDK を採用しました。
Grafana SDK は Go と TypeScript を含む複数言語に対応しています。両者を厳密に比較したうえで選定したわけではありませんが、既存のダッシュボード JSON を参照しながら実装する機会が多いことから、JSON と同様にオブジェクトと配列を入れ子にして定義できる TypeScript を採用しました。
TypeScript の型チェックにより、存在しないプロパティや誤った値の型はビルド時に検出できます。ただし、メトリクスの有無、PromQL の意図、パネルの見やすさまでは判定できないため、生成された JSON と Grafana 上の表示を確認します。
ソースから同期までの基本的な流れは次のとおりです。
- TypeScript のダッシュボード定義を作成または変更する。
npm run buildで Git Sync 用の JSON を生成する。npm run validateと CI で生成物を検証する。- プルリクエストをレビューして main ブランチへマージし、Git Sync で反映する。
AI を使う二つの作成フロー
AI はダッシュボードの設計を置き換えるものではなく、調査とコード記述を速くする補助として使います。目的や既存の定義を人が与え、出力をレビューしてからリポジトリに取り込みます。
MCP で実データを調べながら作成する
MCP を使うと、AI エディタから Grafana のデータソース、メトリクス、既存ダッシュボードを参照しながら、コード案を作れます。たとえば、新しいパネルを追加するときに、AI が利用可能なメトリクス名とラベルを調べ、その結果に基づいて PromQL と Grafana SDK のコード案を作成します。担当者はクエリの意図と実データを確認してから採用します。これにより、メトリクスを検索してコードへ転記する反復作業を減らせます。
本番環境へ安全に接続するための構成
ローカルの AI エディタから本番環境の mcp-grafana へ接続するため、その前段に mcp-auth-proxy を配置しています。利用者は GitHub アカウントで認証・認可され、許可された利用者のリクエストだけが mcp-grafana へ転送されます。これにより、MCP サーバーを認証なしで公開せずに利用できます。
mcp-grafana から Grafana へのアクセスには、用途ごとに権限を絞ったサービスアカウントを使用します。メトリクスや既存ダッシュボードを調べる通常の操作は読み取り専用とし、AI が本番環境を直接変更しない構成にしています。
AI による調査とデプロイも分離しています。AI は実データを参照して Grafana SDK のコード案を作成しますが、Grafana への反映はビルド、検証、プルリクエストのレビュー、Git Sync を経由します。本番環境への書き込み操作を MCP に許可する場合は、対象者、操作範囲、監査ログを別途設計する必要があります。
Web UI で試作してからコード化する
レイアウトを素早く試したい場合や MCP 接続が難しい場合は、Web UI で試作したダッシュボードを JSON としてエクスポートし、AI に Grafana SDK のコードへの変換を依頼します。既存ダッシュボードの移行でも、エクスポートした JSON から Grafana SDK のコード案を生成し、共通パネルを再利用できる形に整理しました。多くは生成後のビルドと表示確認だけで移行できましたが、複雑なレイアウトでは gridPos などを手作業で調整しました。
どちらのフローでも、AI の出力はレビュー対象です。特にクエリ、テンプレート変数、パネルの配置は、実際の環境で期待どおりに動くことを確認します。
現在のリポジトリ設計
ソースコードはサービス横断で共通化し、Git Sync に渡す成果物だけをサービスと環境ごとに分けています。これにより、再利用できるダッシュボード実装を保ちつつ、環境ごとに異なる出力セットや設定を明示できます。
grafana-dashboards/
├── lib/ # Grafana SDK の共通パネルと正規化処理
├── src/ # カテゴリ別の TypeScript ダッシュボード定義
├── config/
│ ├── categories.json # カテゴリ、既存リソース UID の台帳
│ └── targets/ # サービス × 環境ごとの出力定義
├── scripts/ # ビルド、検証、設定生成
└── sync/
└── <service>/<environment>/dashboards/
# Git Sync が読む JSON の成果物
config/categories.json はカテゴリとダッシュボードの定義を集約し、config/targets/ は出力先、フォルダ UID、ダッシュボード UID、環境固有の設定を持ちます。複数のサービスと環境の組み合わせをビルド対象として管理しています。
npm run build はすべての環境向け JSON を生成します。確認対象を絞るときは --target、サービス単位で生成するときは --product オプションを使えます。
環境ごとに異なる値はビルド対象の設定から BuildContext として渡します。たとえばスタック名、リージョン、CloudWatch のデータソース UID をビルド時に適用します。ホスト名やインスタンス ID のように実行時に取得できる値は、テンプレート変数で探索させる方針です。
生成時に守る互換性と運用ルール
ビルド処理は、SDK が出力する JSON をそのまま保存するだけではありません。既存定義から残り得る環境依存の値を正規化し、Git Sync が解釈できる形式に整えます。
データソース参照は、用途ごとに定めた UID へ正規化します。EC2 向けの Prometheus、EKS 向けの Prometheus、Loki、CloudWatch では必要な参照先が異なるため、検証でも誤った UID が残っていないことを確認します。
このリポジトリでは、Git Sync が読み取る classic 形式のダッシュボード JSON に必要な panels、schemaVersion、tags を生成時に補います。旧形式の行ベースレイアウトは gridPos を持つ形式へ変換します。
IaC 管理のダッシュボードには editable: false を設定します。Grafana の Git Sync は双方向同期も可能ですが、Web UI 上の編集を許可すると再ビルド結果と競合します。変更経路を Grafana SDK のコードと設定ファイル、ビルド、プルリクエストに一本化することで、どの変更が正なのかを明確にしています。
CI で生成物まで検証する
GitHub Actions では、プルリクエストと main ブランチへの変更に対して npm ci、npm run build、npm run validate を実行します。さらに、ビルド後の sync/ がコミット済みかを確認します。
この検証により、TypeScript のコンパイルだけでは発見できない問題も早期に検出できます。具体的には、出力ファイルや UID の不足、空のパネル、gridPos の欠落、Git Sync 必須フィールドの不足、旧データソース UID の残存、UI 編集可能な設定、旧ダッシュボード UID の再利用を検出します。
JSON を Git に含めることで差分は増えますが、Grafana に配布される成果物そのものをレビューできます。ソースと成果物がずれている場合は CI が失敗するため、手元でのビルド漏れも防げます。
Git Sync の前提と段階的な移行
Git Sync は Grafana v13 以降で正式にサポートされています。v12 系では experimental 扱いのため、対象インスタンスのバージョンと、必要なデータソースの準備状況を確認してから展開します。
ダッシュボードの TypeScript 化とリポジトリ基盤の構築は完了しており、Git Sync への切り替えはこれらの前提を確認しながら環境ごとに進めています。
移行は次の流れで進めます。
- 稼働中のダッシュボード JSON をバックアップする。
- ダッシュボードを Grafana SDK のコードとして定義し、カテゴリとビルド対象に新しい UID を登録する。
- JSON を
sync/<service>/<environment>/dashboards/に生成する。 - 各 Grafana 環境を対応する Git Sync パスへ接続し、表示とクエリを検証する。
- 旧 UI 管理版と新しい Git Sync 管理版を並行運用し、アラートやブックマークを新しい UID へ切り替える。
- 切り替え完了後に旧版を廃止する。
並行運用では、既存の本番フォルダやダッシュボードを移動・上書きしません。Git Sync 管理版には別のフォルダ UID とダッシュボード UID を付けるため、不具合があれば Git Sync 管理版だけを無効化または削除し、旧 UI 管理版を参照して監視を継続できます。
なお、新 UID で並行展開する方式では、旧ダッシュボードの UID やパネル ID に紐付く手動アノテーションは自動で引き継がれないため、保持が必要な場合は別途移行方法を検討します。
おわりに
Web UI 中心の運用では、作成者の試行錯誤が画面内に閉じ、変更履歴の追跡や複数環境への再現が難しいという課題がありました。今回の構成では、ダッシュボード定義と環境設定をコードとして管理し、レビューと CI を経て環境別に展開できます。
さらに、MCP による実データの探索や、Web UI からエクスポートした JSON の Grafana SDK コード化を AI が支援することで、Web UI の試作しやすさを活かしながら、ダッシュボードの作成・改善を効率化できました。
AI と Grafana SDK、そして生成物を検証する CI を組み合わせることで、作成の手軽さだけでなく、変更の追跡性、再現性、安全性を備えたダッシュボード運用へ移行できました。
最後まで読んでいただき、ありがとうございます！
この記事をシェアしていただける方はこちらからお願いします。