apiserver

README

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.

Documentation

Index

• Variables
• func ProvideService(cfg *setting.Cfg, features featuremgmt.FeatureToggles, ...) (*service, error)
• type DirectRestConfigProvider
• type RestConfigProvider
• type Service

Variables

var (
	Scheme = runtime.NewScheme()
	Codecs = serializer.NewCodecFactory(Scheme)
)

var WireSet = wire.NewSet(
	ProvideService,
	wire.Bind(new(RestConfigProvider), new(*service)),
	wire.Bind(new(Service), new(*service)),
	wire.Bind(new(DirectRestConfigProvider), new(*service)),
	wire.Bind(new(builder.APIRegistrar), new(*service)),
)

Functions

func ProvideService

func ProvideService(
	cfg *setting.Cfg,
	features featuremgmt.FeatureToggles,
	rr routing.RouteRegister,
	orgService org.Service,
	tracing *tracing.TracingService,
	db db.DB,
) (*service, error)

Types

type DirectRestConfigProvider

type DirectRestConfigProvider interface {
	// GetDirectRestConfig returns a k8s client configuration that will use the same
	// logged logged in user as the current request context.  This is useful when
	// creating clients that map legacy API handlers to k8s backed services
	GetDirectRestConfig(c *contextmodel.ReqContext) *clientrest.Config

	// This can be used to rewrite incoming requests to path now supported under /apis
	DirectlyServeHTTP(w http.ResponseWriter, r *http.Request)
}

type RestConfigProvider

type RestConfigProvider interface {
	GetRestConfig() *clientrest.Config
}

type Service

type Service interface {
	services.NamedService
	registry.BackgroundService
	registry.CanBeDisabled
}