app-sdk-concepts

What this skill does

# 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:
```bash
go install github.com/grafana/grafana-app-sdk/cmd/grafana-app-sdk@latest
```

Verify installation:
```bash
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.

| Mode | Description | Context |
|------|-------------|---------|
| **Standalone operator** | Single binary, runs as a Kubernetes operator with its own webhook server | Outside Grafana repo |
| **grafana/apps** | Submodule inside `apps/<name>/`, admission auto-registered as a k8s plugin | Inside Grafana repo only |
| **Frontend-only** | No backend code; CUE kinds and generated types only | Outside Grafana repo |

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

## Project Init Workflow

### Standalone operator

```bash
# 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.

```bash
# 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

```bash
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:

```go
// 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

```bash
# 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](https://github.com/grafana/grafana-app-sdk)
- [App Platform Documentation](https://grafana.com/docs/grafana/latest/developers/plugins/app-platform/)