App SDK Concepts

Local Development Guide

Standalone Operator Mode

Standard Way from Generated Files

The grafana-app-sdk generates a standard way of running a kubernetes cluster locally with grafana, datasources, and app setup using k3d and tilt.

Prerequisites

• k3d

• tilt

Create Cluster

The generated Makefile has the target make local/up to create the cluster and apply everything. This runs:

• grafana-app-sdk project local generate - generates a k3d config (./local/generated/k3d-config.json) to mount the host volume ./local/mounted-files and a YAML bundle in ./local/generated/dev-bundle.yaml.

• ./local/scripts/cluster.sh create "local/generated/k3d-config.json" to create the cluster

• tilt up in the local directory to stand up all resources.

local/Tiltfile is generated by project init and will scrape all YAML in local/generated, and then all YAML in local/additional (which overwrites anything declared in local/generated).

Push Operator Image

The operator image must be built with make build and then pushed to the local cluster with make local/push_operator

Deploy Plugin

The plugin for the app can be pushed to the local grafana deployment with make local/deploy_plugin. The plugin must have been built already (make build). By default, the grafana deployment loads the plugin from local/mounted-files/plugin/dist.

Configuration

The local setup can be configured with the file local/config.yaml (generated by project init).

See local-config.md for a full reference of all available configuration options.

Testing with kubectl

Once CRDs are applied and the operator is running, create test resources directly:

# Create a resource
kubectl apply -f - <<EOF
apiVersion: my-app.grafana.app/v1alpha1
kind: MyKind
metadata:
  name: test-resource
  namespace: default
spec:
  title: "Test"
  description: "A test resource"
EOF

# Watch the resource status update as the reconciler runs
kubectl get mykind test-resource -w

# See full status
kubectl describe mykind test-resource

# Delete it
kubectl delete mykind test-resource

Debug Logging

By default, the generated operator code uses debug-level logging when it instantiates the global default logger:

// main.go
func main() {
  // Configure the default logger to use slog
	logging.DefaultLogger = logging.NewSLogLogger(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
		Level: slog.LevelDebug,
	}))
  // ... rest of code
}

An app author may change this to read from a config file or CLI, in order to find our, either ask the user or read cmd/operator/main.go to see how the logging is configured.

Alternative Local Dev Methods

Prerequisites

A local Kubernetes cluster is required. The easiest options:

# Option A: kind (Kubernetes in Docker)
brew install kind
kind create cluster --name dev

# Option B: minikube
brew install minikube
minikube start

# Confirm kubectl is pointing at the local cluster
kubectl config current-context
kubectl get nodes

Apply CRDs

Before running the operator, apply the generated CRDs to the cluster:

# Apply all generated CRD files
kubectl apply -f definitions/

kubectl apply -f definitions/ will also attempt to apply the <app>-manifest.(json|yaml) file, which is not a valid Kubernetes resource and will produce an error. This error can be safely ignored — the CRD files will still be applied successfully.

Run this again after every grafana-app-sdk generate if schema fields changed.

Run the Operator Locally

Build and run the operator binary against the local cluster:

# Run directly with go run
go run ./cmd/operator/... --kubeconfig="$HOME/.kube/config"

# Or build first then run
make build
./bin/operator --kubeconfig="$HOME/.kube/config"

The operator uses the standard kubeconfig by default — it will connect to whatever cluster kubectl points to.

grafana/apps Mode

For grafana/apps, local development means running the full Grafana binary with your app registered.

Build and Run Grafana

From the Grafana repo root:

# Build the backend (includes your app)
make build-go

# Run Grafana with your app registered
./bin/grafana server

# Or use the dev mode that watches for changes
make run

Your app is automatically included in the binary because it's registered in pkg/registry/apps/apps.go.

Testing with Grafana UI

1. Navigate to http://localhost:3000

2. Use the Grafana API or UI to create resources of your kind

3. Watch server logs for reconciler/admission output

API Access

Your kind is accessible via the Grafana API at:

GET/POST /apis/<group>/<version>/namespaces/<namespace>/<plural>

For example:

# List resources
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/apis/my-app.grafana.app/v1alpha1/namespaces/default/mykinds

# Create a resource
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"apiVersion":"my-app.grafana.app/v1alpha1","kind":"MyKind","metadata":{"name":"test"},"spec":{"title":"Test"}}' \
  http://localhost:3000/apis/my-app.grafana.app/v1alpha1/namespaces/default/mykinds

Common Development Patterns

Watching Reconciler Behavior

Run the operator with debug logging and watch what happens when resources change:

# Terminal 1: Run operator
go run ./cmd/operator/...

# Terminal 2: Create a resource and watch it
kubectl apply -f my-resource.yaml && kubectl get mykind -w

Forcing a Re-reconcile

The operator reconciles on changes. To force a re-reconcile without editing the resource:

# Touch the resource with a no-op annotation change
kubectl annotate mykind my-resource grafana.com/force-reconcile="$(date)" --overwrite

Checking Admission Webhooks

For standalone mode, the operator runs its own webhook server. Test admission by creating/updating resources and checking for validation errors:

# Invalid resource (should be rejected)
kubectl apply -f invalid-resource.yaml
# Output should include the admission error message

# Check webhook logs in the operator output

Resetting State

To start fresh during development:

# Delete all resources of a kind
kubectl delete mykind --all -n default

# Delete and re-apply CRDs (loses all data)
kubectl delete -f definitions/
kubectl apply -f definitions/

Both commands will produce an error for the <app>-manifest.(json|yaml) file, which is not a valid Kubernetes resource. These errors can be safely ignored.