app-sdk-concepts

Grafana App SDK Concepts

The grafana-app-sdk is a CLI + Go library for building schema-centric apps on the Grafana App Platform. Apps define resources via CUE schemas ("kinds"), generate Go + TypeScript code, and implement business logic via admission control and reconcilers.

Prerequisites

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

Common Workflows

Scaffold a standalone operator app

# 1. Init the project (use the Go module path)
grafana-app-sdk project init

Common failure: forgetting go install updates the binary — verify with grafana-app-sdk version before init.

Scaffold a grafana/apps-style app (inside grafana/grafana)

Only available inside the Grafana repo (or fork) — the init command detects apps/ and pkg/registry/apps/ at the repo root.

Then register the app inside Grafana (pkg/registry/apps/apps.go + register.go). Full walkthrough in references/deployment-modes.md.

End-to-end development loop

Always rerun generate after every CUE change — generated code is the API your reconciler sees.

Deployment modes (one-line table)

Full per-mode init, runtime, and wiring detail in references/deployment-modes.md.

References

• references/deployment-modes.md — per-mode init, runtime semantics, grafana/apps registration walkthrough
• references/project-structure.md — standalone project layout, what's hand-edited vs generated
• references/cli-reference.md — every grafana-app-sdk subcommand with flags
• references/specific-config.md — app.Config.SpecificConfig pattern for feature-flag-driven app config
• references/local-development.md — Tilt + k3d local dev loop
• references/local-config.md — local/config.yaml reference

Resources

• grafana-app-sdk repo
• App Platform docs