app-sdk-concepts

Grafana App SDK の概念

grafana-app-sdk は、Grafana App Platform 上でスキーマ中心のアプリを構築するための CLI と Go ライブラリです。アプリでは CUE スキーマ（「kind」）を使ってリソースを定義し、Go と TypeScript のコードを生成して、アドミッションコントロールとリコンサイラーを通じてビジネスロジックを実装します。

前提条件

go install github.com/grafana/grafana-app-sdk/cmd/grafana-app-sdk@latest
grafana-app-sdk version   # verify

一般的なワークフロー

スタンドアロンのオペレーターアプリをスキャフォールドする

# 1. Init the project (use the Go module path)
grafana-app-sdk project init github.com/example/my-app

# 2. Add operator scaffolding — ASK THE USER FIRST.
#    They may prefer to write app.App by hand.
grafana-app-sdk project component add operator

# 3. Verify scaffolded layout
ls pkg/app pkg/watchers cmd/operator
# Expected: app.go, watchers/<kind>.go, main.go

よくある失敗：go install でバイナリが更新されることを忘れることです。init の前に grafana-app-sdk version で確認してください。

grafana/apps 形式のアプリをスキャフォールドする（grafana/grafana 内）

Grafana リポジトリ（またはフォーク）内でのみ利用できます。init コマンドは、リポジトリのルートにある apps/ と pkg/registry/apps/ を検出します。

mkdir -p apps/my-app && cd apps/my-app
grafana-app-sdk project init github.com/grafana/grafana/apps/my-app

# Keep ONLY: kinds/ pkg/ go.mod go.sum — delete everything else.
cp apps/example/Makefile       apps/my-app/Makefile
cp apps/example/kinds/config.cue apps/my-app/kinds/config.cue   # overwrite
go work use ./apps/my-app

次に、Grafana 内でアプリを登録します（pkg/registry/apps/apps.go + register.go）。詳しい手順は references/deployment-modes.md を参照してください。

開発のエンドツーエンドループ

1. project init               → module, Makefile, kinds/
2. project kind add MyKind    → CUE kind scaffold
3. Edit kinds/*.cue           → schemas, validation, versions
4. grafana-app-sdk generate   → Go types, clients, TS types, AppManifest, CRDs
5. Implement logic            → fill in reconciler / admission stubs
6. (optional) project component add frontend

CUE を変更するたびに、必ず generate を再実行してください。生成されたコードが、リコンサイラーに見える API です。

デプロイモード（1 行の表）

モード	選択する状況	実行場所
スタンドアロンオペレーター	Grafana リポジトリの外で、独自のバイナリを使いたい場合	独自の Webhook サーバーを持つ Kubernetes オペレーター
grafana/apps	github.com/grafana/grafana（またはフォーク）内	Grafana の API サーバー内で実行
フロントエンドのみ	UI のみのアプリで、Go のロジックが不要な場合	バックエンドなし。TS 型のみ

各モードの init、ランタイム、配線の詳細は references/deployment-modes.md を参照してください。

参考資料

• references/deployment-modes.md — モードごとの init、ランタイムのセマンティクス、grafana/apps の登録手順
• references/project-structure.md — スタンドアロンプロジェクトの構成、手作業で編集する部分と生成される部分
• references/cli-reference.md — grafana-app-sdk の全サブコマンドとフラグ
• references/specific-config.md — 機能フラグによるアプリ設定のための app.Config.SpecificConfig パターン
• references/local-development.md — Tilt と k3d を使ったローカル開発ループ
• references/local-config.md — local/config.yaml のリファレンス

リソース

• grafana-app-sdk リポジトリ
• App Platform のドキュメント