AutoGineer
Generated banner for App SDK Concepts
Generated logo for App SDK Concepts

App SDK Concepts

Grafana LabsOfficialPublished by Grafana Labs

  • Skill
  • Tool integration
  • Cloud and DevOps
  • Apache-2.0
  • Medium risk
Download ZIP

From the author

Use when starting any grafana-app-sdk work — scaffolding a Grafana app, initializing a Grafana App Platform app, picking a deployment mode (standalone operator / grafana/apps / frontend-only), wiring app-specific config, or onboarding to the SDK. Covers `grafana-app-sdk` CLI install, `project init` per deployment mode, project layout, the schema-centric workflow (CUE kinds → generated code → reconciler/admission logic), and `SpecificConfig` for env-driven app configuration. Use even if the user just says "make a new app", "Grafana app platform", "kinds and watchers", "operator scaffold", or asks about `apps/` inside the Grafana repo, without naming the SDK explicitly.
— the description by Grafana Labs

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The grafana-app-sdk provides a CLI and Go library for building schema-centric applications on the Grafana App Platform. It supports a workflow where developers define resources using CUE schemas, generate Go and TypeScript code, and implement business logic through reconcilers and admission controllers. The SDK supports multiple deployment modes, including standalone Kubernetes operators and in-process applications within the Grafana repository.

What it does

  • Initializes new application projects with the required directory structure and build files
  • Scaffolds Kubernetes operator components or frontend plugin structures
  • Generates Go types, clients, and TypeScript definitions from CUE schemas
  • Provides commands for local development and testing of application logic
  • Facilitates the creation of Kubernetes YAML bundles for deployment
  • Supports configuration management for environment-driven application settings

When to use it

  • When starting a new project on the Grafana App Platform
  • When you need to define custom resources using CUE schemas
  • When building a standalone Kubernetes operator for Grafana-related tasks
  • When integrating a new application directly into the Grafana repository
  • When you need to generate boilerplate code for reconcilers and admission handlers

Advantages

  • Ensures consistent project structure across different deployment modes
  • Automates the generation of boilerplate code from schema definitions
  • Simplifies the integration of business logic with Kubernetes-style resources
  • Provides a unified CLI for the entire development lifecycle
  • Supports both standalone and in-process deployment architectures

Usage examples

“How do I start a new Grafana app project?”
Use the command grafana-app-sdk project init github.com/your-org/your-app to create the project structure, including kinds, package skeletons, and build files.
“How do I add an operator to my project?”
Run grafana-app-sdk project component add operator to scaffold the necessary reconciler stubs, admission handlers, and the operator entrypoint.
“How do I update my Go types after changing a CUE schema?”
Execute the command grafana-app-sdk generate to update Go types, clients, and TypeScript definitions based on your latest CUE definitions.
“How do I run my app locally?”
Use the command grafana-app-sdk local/up to start a local Kubernetes-compatible API server for testing your application logic.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/grafana/app-sdk-concepts/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip app-sdk-concepts.zip -d .agents/skills

Documentation by Grafana Labs

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 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

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.

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

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
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

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

Deployment modes (one-line table)

ModeWhen to pickWhere it runs
Standalone operatorOutside Grafana repo, want your own binaryKubernetes operator with its own webhook server
grafana/appsInside github.com/grafana/grafana (or fork)In-process inside Grafana's API server
Frontend-onlyUI-only app, no Go logic neededNo backend — TS types only

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

References

Resources

Files

references/specific-config.md

App-specific configuration (SpecificConfig)

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

// 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 — never hardcode it in New.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

What our scanner noticed· Medium risk

  • References to credential files

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Grafana Labs
Publisher
Grafana Labs (Official)
Source
grafana/skills · skills/grafana-app-sdk/app-sdk-concepts · commit 8fb72a5
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Grafana Labs.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download app-sdk-concepts.zip