app-sdk-concepts（应用 SDK concepts）

Grafana App SDK Concepts

The grafana-app-sdk is a CLI and Go library for building schema-centric applications on the Grafana App Platform. Apps define resource types using CUE schemas ("kinds"), generate Go and TypeScript code from those schemas, and implement business logic via admission control (ingress validation/mutation) and reconcilers (async processing).

Prerequisites

Install the CLI:

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

Verify installation:

grafana-app-sdk version

Deployment Modes

The available deployment modes depend on the repository context:

Inside the Grafana repo (github.com/grafana/grafana or a fork — identified by the presence of apps/ and pkg/registry/apps/ at the repo root):

• Only grafana/apps mode is available.

Outside the Grafana repo:

• Standalone operator or Frontend-only are available. grafana/apps is not applicable.

The app business logic (admission handlers, reconcilers) is identical across modes — only the runtime embedding differs.

Project Init Workflow

Standalone operator

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

# 2. Add operator scaffolding (prompt the user before running)
grafana-app-sdk project component add operator

The project component add operator command creates an App, watcher stubs for all kinds, and the main operator binary. Always confirm with the user before running it — they may prefer to write these from scratch against the app.App interface.

grafana/apps-style app

Only available when working inside the Grafana repo (or a fork). The init command detects this automatically by checking for apps/ and pkg/registry/apps/ at the repo root.

# 1. Create the app subdirectory and init inside it
mkdir -p apps/my-app
cd apps/my-app
grafana-app-sdk project init github.com/grafana/grafana/apps/my-app

# 2. Clean up — keep ONLY these directories/files:
#    kinds/   pkg/   go.mod   go.sum
# Delete everything else generated by project init.

# 3. Copy the Makefile from apps/example (run from repo root)
cp apps/example/Makefile apps/my-app/Makefile

# 4. Copy the codegen config from apps/example (run from repo root) (ALWAYS OVERWRITE)
cp apps/example/kinds/config.cue apps/my-app/kinds/config.cue

# 5. Update the go workspace to use the new app
go work use ./apps/my-app

Then wire the app into Grafana:

• Register in pkg/registry/apps/apps.go (ProvideAppInstallers WireSet)
• Add register.go under pkg/registry/apps/my-app/

See apps/example/README.md in the repo for the full registration walkthrough.

Frontend-only app

grafana-app-sdk project init github.com/example/my-app
# Skip operator and backend component scaffolding entirely
# Run generate to produce TypeScript types, then build frontend

Overall Development Workflow

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

Project Structure (standalone)

my-app/
├── cmd/
│   └── operator/           # Build target package for the operator, contains the `main` package
├── kinds/                  # CUE kind definitions (source of truth)
│   ├── manifest.cue        # App-level manifest and version declarations
│   ├── mykind.cue          # kind metadata for MyKind
│   └── mykind_v1alpha1.cue # version schema for MyKind version v1alpha1
├── pkg/
│   ├── generated/          # Generated Go code — do NOT edit manually
│   ├── watchers/           # Watcher stubs generated by `project component add operator`
│   └── app/
│       └── app.go          # Entry point; implement app.App interface here
├── definitions/            # Generated CRD and manifest files — do NOT edit manually
├── local/
│   ├── additional/          # Folder for specifying additional YAML manifests for local deployment
│   ├── generated/           # Folder where generated manifests for a local deployment live (don't commit)
│   ├── mounted-files/       # Folder that gets mounted to the k3d cluster (don't commit)
│   ├── scripts/             # Generated scripts (don't commit)
│   ├── Tiltfile             # Tiltfile for standing up local resources
│   └── config.yaml          # configuration file for local setup
├── go.mod
└── Makefile

App-Specific Configuration (SpecificConfig)

Apps can pass structured configuration through app.Config.SpecificConfig. This is how the registration layer (register.go) passes feature flags or runtime settings into the New function:

// pkg/app/config.go
type AppSpecificConfig struct {
    EnableReconciler bool
    SomeFeatureFlag  bool
}

// pkg/app/app.go — read it in New()
func New(cfg app.Config) (app.App, error) {
    appCfg, _ := cfg.SpecificConfig.(*AppSpecificConfig)
    if appCfg != nil && appCfg.EnableReconciler {
        // wire up reconciler
    }
    // ...
}

// pkg/registry/apps/<name>/register.go — populate from Grafana config
specificConfig := &app.AppSpecificConfig{
    EnableReconciler: features.IsEnabled(featuremgmt.FlagMyAppReconciler),
}
provider := simple.NewAppProvider(manifestdata.LocalManifest(), specificConfig, app.New)

Use SpecificConfig for anything that varies by environment or feature flag rather than hardcoding it in New.

Key CLI Commands Reference

# Project management
grafana-app-sdk project init <module>
grafana-app-sdk project kind add <KindName> --overwrite
grafana-app-sdk project component add operator
grafana-app-sdk project component add frontend

# Code generation
grafana-app-sdk generate

Resources

• grafana-app-sdk GitHub
• App Platform Documentation