This repository is currently experimental, which means that interfaces and behavior may change as it evolves.

The grafana-app-sdk is an SDK used for developing apps/extensions for grafana. It encompasses the following:

• Code generation and project boilerplate generation from a CLI
• Storage and version management of unique schemas (kinds)
• An reconciler/event-based model for handling changes to data
• Both simple building blocks and opinionated solutions for building operators and plugins
• An interface layer over your storage system, allowing any compatible API-server-like system to be plugged in

If you want to try out using the SDK, there is a tutorial to build a simple issue tracker which starts you from zero and brings you through to deploying a simple app built using the SDK.

The simplest way to install the CLI is with go install. To get the latest version, use:

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

(ensure that your GOPATH/bin (typically $HOME/go/bin) is in your PATH)

If you prefer to download a binary and add it to your PATH, you can install a binary from the releases page:

1. Visit the latest release page
2. Find the appropriate artifact for your OS and architecture
3. Download the artifact and untar it into your PATH

Once you have a version of the CLI installed, you can test it with:

grafana-app-sdk version

Which will print the version of the CLI which you have installed.

An agnotic view of an app using the SDK looks like:

The SDK handles interaction with the storage system, and surfacing simple interfaces for performing normal operations on resources in storage, as well as creating controller/operator loops that react to changes in the resources in the storage system.

A typical grafana app deployment might look more like:

For more details on application design, see App Design.

Full CLI usage is covered in CLI docs page, but for a brief overview of the commands:

Read more about the library usage in the docs directory.

Package exposing interfaces for resources and client, and the various kind of Store objects, which allow you to use key/value store-like objects for handling your data.

See Resource Objects and Resource Stores for more information on how to work with resource Objects and use Store objects.

Package containing operator code, for building out event-based and/or reconciler-based operators.

See Operators & Event-Based Design for more details on building operators.

Implementation of a storage layer using a kubernetes-compatible API server.

Wrapper for the grafana backend plugin go SDK which adds layers on top for dealing with lazy-loading, encoding kube configs in secure JSON data, and HTTP-like routing.

See Writing Back-End Plugins for more details on using the plugin package.

The grafana-app-sdk code generation uses kindsys for it's CUE kind definitions, and thema for the generated code's unmarshaling.

If you use the generated code, you must take a project dependency on thema, as it is used as a depndency in the generated code (kindsys is only used in the generation process, and is not needed in your project).

Please see the /docs directory for full documentation, or take a look at the Design Patterns, Kubernetes Concepts, or the tutorial.

The examples directory contains runnable example projects that use different SDK components.

Each package also contains a README.md detailing package usage and simple examples.

See our contributing guide for instructions on how to contribute to the development of the SDK.