grafana/pkg/services/apiserver/README.md

Grafana Kubernetes compatible API Server

Basic Setup

[feature_toggles]
kubernetesPlaylists = true

Start Grafana:

make run

Enable dual write to etcd

Start etcd:

make devenv sources=etcd

Set storage type and etcd server address in custom.ini:

[grafana-apiserver]
storage_type = etcd
etcd_servers = 127.0.0.1:2379

Enable dual write to JSON files:

Set storage type:

[grafana-apiserver]
storage_type = file

Objects will be written to disk under the {data.path}/grafana-apiserver/ directory.

For example:

data/grafana-apiserver
├── grafana.kubeconfig
└── playlist.grafana.app
    └── playlists
        └── default
            └── hi.json

Enable aggregation

See aggregator/README.md for more information.

kubectl access

For kubectl to work, grafana needs to run over https. To simplify development, you can use:

app_mode = development

[feature_toggles]
grafanaAPIServerEnsureKubectlAccess = true 
kubernetesPlaylists = true

This will create a development kubeconfig and start a parallel ssl listener. It can be registered by navigating to the root grafana folder, then running:

export KUBECONFIG=$PWD/data/grafana-apiserver/grafana.kubeconfig
kubectl api-resources

Grafana API Access

The Kubernetes compatible API can be accessed using existing Grafana AuthN at: http://localhost:3000/apis.

The equivalent openapi docs can be seen in http://localhost:3000/swagger, select the relevant API from the dropdown in the upper right.

General Structure

The folder structure aims to follow the patterns established in standard (https://github.com/kubernetes/kubernetes)[kubernetes] projects when possible.

• pkg/apimachinery - this is based on the structure of apimachinery. it contains types and utils that are used by both API clients and servers
• pkg/apiserver - this is based on the structure of apiserver. it contains apiserver library code used for both standalone app apiservers and the one embedded in grafana. it depends on pkg/apimachinery
• pkg/services/apiserver - this is where the embedded grafana API server background service is currently configured. it depends on pkg/apiserver and pkg/apimachinery. the closest analog in the Kubernetes monorepo is the kube-apiserver cmd.
• pkg/apis - where API resource types are defined. this is based on the structure of the sample-apiserver
• hack/update-codegen.sh - this script is used to run k8s codegen, which generates the code that is used by the API server to handle the types defined in pkg/apis. it is based on the update-codegen.sh from sample-apiserver
• pkg/registry/apis - where all of the types in pkg/apis are registered with the API server by implementing the builder interface. this pattern is unique to grafana, and is needed to support using wire dependencies in legacy storage implementations. this is separated from pkg/apis to avoid issues with k8s codegen.
• pkg/cmd/grafana/apiserver - this is where the apiserver is configured for the grafana apiserver CLI command, which can be used to launch standalone API servers. this will eventually be merged with the config in pkg/services/apiserver to reduce duplication.