README
¶
grafana-app-sdk
[!WARNING]
This repository is currently experimental, which means that interfaces and behavior may change as it evolves. Minor version increments may result in breaking changes, see Migrations for details.
The grafana-app-sdk is an SDK used for developing apps for grafana app platform. It consists of a CLI for generating code and projects, and a set of libraries used to make building apps easier.
Quickstart
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.
Documentation
Please see the docs directory for documentation on concepts and design patterns. For go API documentation, see godocs on pkg.go.dev.
Installation of the CLI
go install
The simplest way to install the CLI is with go install.
[!NOTE]
There is currently a known issue with running go install for many versions. You can install locally withgit clone git@github.com:grafana/grafana-app-sdk.git && cd grafana-app-sdk/cmd/grafana-app-sdk && go installBut be advised this will install the latest
maincommit. To install a specific version, usegit checkout <version>before runninggo 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)
Binary
If you prefer to download a binary and add it to your PATH, you can install a binary from the releases page:
- Visit the latest release page
- Find the appropriate artifact for your OS and architecture
- 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.
App Design
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 application design documentation.
CLI Usage
Full CLI usage is covered in CLI docs page, but for a brief overview of the commands:
| Command | Description |
|---|---|
version |
Prints the version (use -v for a verbose print) |
generate |
Generates code from your CUE kinds (defaults to CUE in schemas, use -c/--cuepath to speficy a different CUE path) |
project init <module name> |
Creates a project template, including directory structure, go module, CUE module, and Makefile |
project kind add <kind name> |
Add a boilerplate kind in CUE with descriptive comments for all fields |
project component add <component> |
Add boilerplate code for a component to your project. <component> options are frontend, backend, and operator |
project local init |
Initialize the ./local directory for a local development environment (done automatically by project init) |
project local generate |
Generate a YAML bundle for local deployment, based on your CUE kinds and ./local/config.yaml |
Examples
The examples directory contains small examples of different grafana-app-sdk functionality. For a complete example app, you can follow the tutorial project to build a functioning simple app with no prior knowledge necessary.
Further Reading
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.
Contributing
See our contributing guide for instructions on how to contribute to the development of the SDK.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
examples
|
|
|
internal
|
|
|
Package k8s contains an implementation of the resource.Client, resource.SchemalessClient, and resource.ClientGenerator interfaces which uses a standard kubernetes API server as its storage system API server.
|
Package k8s contains an implementation of the resource.Client, resource.SchemalessClient, and resource.ClientGenerator interfaces which uses a standard kubernetes API server as its storage system API server. |
|
plugin
module
|
|