KubeSphere Monitoring Dashboard
The project is inspired by Grafana but with significant difference in data persistence, multitenancy supports and dashboard template sharing to fit KubeSphere's context. It is not a replacement to Grafana. It requires KubeSphere backend and frontend to work.
This repo is aimed at KubeSphere developers who want to understand dashboard data model, concepts and usage and how to contribute, as the custom monitoring feature is introduced as of v3.0.
Table of contents
Get Started
Prerequisites
- Kubernetes v17.0+
- KubeSphere v3.0+
Quick Start
TODO(@FeynmanZhou)
The stack making these possible includes KubeSphere backend, console and custom resources for dashboards.
- KubeSphere Backend: proxies metrics query, ensures data isolation over namespaces.
- KubeSphere Console: renders the dashboard with data and charts.
- CustomResourceDefinition for Dashboard: defines dashboard data model.
Concept and Design
Data Model
Dashboards are backed by the custom resource definition (CRD) Dashboard
. It is compromised of three components: metadata, panels and templatings. Below is an example:
apiVersion: monitoring.kubesphere.io/v1alpha1
kind: Dashboard
metadata:
name: mysql-overview
namespace: default
spec:
title: MySQL Overview
description: MySQL dashboard for the mysql exporter
time:
from: now-1h
to: now
datasource: prometheus
panels:
- type: singlestat
title": Instance Up
targets:
- expr: mysql_up{release="$release"}
instant: "true"
- type: graph
title: mysql disk reads vs writes
targets:
- expr": irate(mysql_global_status_innodb_data_reads{release="$release"}[10m])
legendFormat": reads
- expr": irate(mysql_global_status_innodb_data_writes{release="$release"}[10m])
legendFormat": write
templatings:
- name: release
query: label_values(mysql_up,release)
type: query
sort: 0
Name |
Desc |
spec.title |
dashboard title |
spec.description |
dashboard description |
spec.time |
time range for display. see Time Range for more info |
spec.datasource |
data source to query, defaults to Prometheus |
Panels
The spec.panels
defines a collection of panels. Panels are build blocks of a dashboard. Currently supported panels are row, singlestat, graph and table. See Query and Panels for more info.
Templatings
The spec.templatings
defines a collection of variables. It is convenient to use variables in query expressions. See Variable for more info.
Note that the data model is heavily inspired by Grafana JSON model to gain compatibility. However, to adapt it to KubeSphere's context, we may bring in new fields and break changes.
Data Source
Note: we currently only support Prometheus as data source.
Multi-tenancy
Metrics data should be isolated across namespaces, which means namespace members can only view metrics in the namespace they belong to. This is implemented in the phase of querying. Any user-written expression will be mutated to make sure no query outside the scope of the namespace.
Take the datasource Prometheus for example, KubeSphere backend will add a namespace matcher, i.e. <metric_name>{namespace=<namespace_name>}
, to each query.
Dashboard Template
Dashboard is represented by a custom resource object. Select templates from contrib/gallery, and run the following command to import:
kubectl apply --namespace <NAMESPACE> -f contrib/gallery/<TEMPLATE_YAML_FILE>
You can also open source your template and contribute to Dashboard Gallery. Templates in Dashboard Gallery will be shipped with KubeSphere.
Manual
Query
Except for the panel row
, each panel accepts at least one data source query. It allows you to input query expressions and fetch metrics data.
You can use placeholders in queries. See Variables for more information.
Panels
Chart
We currently support four types of panels
Legend
Time Range
Time range specifies current dashboard time for display. The following are examples in use.
Example |
From |
To |
Last 5 minutes |
now-5m |
now |
Today |
now-1d |
now |
This week |
now-1w |
now |
Last month |
now-2M |
now-1M |
Variables
Query |
Desc |
label_values(metric, label) |
Returns a list of label values for the label in the specified metric. |
Development
APIs
For dashboard APIs, see docs/crd.md
The project is built with kubebuilder v2.3.0.
Backend
If you find some fields should be included in the CRD, edit api package and regenerate the project by make
. Kubebuilder is the tool we are using.
If you find bugs or want to add new APIs, implement new datasources to KubeSphere, read KubeSphere developer guides for monitoring.
Frontend
@TODO(justahole)
Contributing
Dashboard Gallery
If you want to share your dashboard templates, you can submit dashboard template yaml files to gallery folder with an elaborate readme. Outstanding templates will be selected to ship with KubeSphere future releases.