Dashboard-as-Code
Perses offers the possibility to define dashboards as code instead of going through manipulations on the UI. But why would you want to do this? Basically Dashboard-as-Code (DaC) is something that becomes useful at scale, when you have many dashboards to maintain, to keep aligned on certain parts, etc.
DaC benefits can be summarized as follows:
- Operational efficiency, by the reusability of a common basis of dashboard components for standard monitoring use cases.
- Implementation cost reduction, by leveraging on existing components when creating new dashboards.
- Maintenance cost reduction, by making it easier to: cascade the same update on multiple dashboards, keep multiple components aligned with each other, etc..
Most of these benefits comes from not dealing with the Perses JSON format directly: instead, we provide SDKs in languages that enable factorization, code imports and more, namely:
- CUE, a powerful templating language with a strong emphasis on data validation.
- Go, an opensource programming language, that probably doesn’t need to be introduced…
Just pick your favorite to start with DaC. If you don’t have one, give a try to both!
[!NOTE] CUE is the language used for the data model of the plugins, which means you’ll always be able to include any external plugin installed in your Perses server into your code when using the CUE SDK. However, the Golang SDK may not support all the plugins: it’s basically up to each plugin development team to provide a Go package to enable the DaC use case. This statement applies also to any other language we might have a SDK for in the future.
Also, as-code means it’s GitOps-friendly, meaning that you can also benefit from:
- versions history
- peer-review of changes before rollout
- automated deployments
- and more…
Getting Started With Cue
Prerequisites
percli
, the CLI of Perses.cue
, the CLI of Cuelang.
Repository setup
Create a new folder that will become your DaC repository, then follow the steps below:
1. Initialize the CUE module
See the CUE documentation for more information about this step.
2. Retrieve the CUE sources from Perses
Ideally we should rely on a native dependency management here, but since it’s not yet available for CUE as already mentioned, we provide in the meantime a dedicated CLI command dac setup
in order to add the CUE sources from Perses as external dependencies to your repo:
You can omit the version flag if you are connected to a Perses server (it will retrieve its version). Otherwise, unless you have a specific case, better to pass the latest version available.
Develop dashboards
You are now fully ready to start developping dashboards as code!
It’s first strongly recommended to ramp up on CUE if you are not familiar with this technology. For this have a look at:
- The official website of Cuelang.
- Cuetorials, a 3rd party source of information that is a very good complement.
You should then have a look at the CUE SDK documentation to better understand how to use the framework.
You can also check an example of DaC usage here.
Getting started with Go SDK
Prerequisites
percli
, the CLI of Perses.go
, the programming language.
Repository setup
Create a new folder that will become your DaC repository, then follow the steps below:
1. Initialize the Go module
See the Go documentation for more information about this step.
2. Install the Perses SDK
If you need a specific version, you can specify it as follows:
Develop dashboards
You are now fully ready to start developing dashboards as code!
It’s first strongly recommended to ramp up on Go if you are not familiar with this technology. For this have a look at:
- The official website of Go.
You should then have a look at the Go SDK documentation to better understand how to use the framework.
You can also check an example of DaC usage here.
[!WARNING]
Do not log / print on the standard stdout! It would break the output of the
dac build
command.
Quick start example:
Build dashboards
Anytime you want to build the final dashboard definition (i.e: Perses dashboard in JSON or YAML format) corresponding to your as-code definition, you can use the dac build
command, as the following:
If the build is successful, the result can be found in the generated built
folder.
[!NOTE] the
-o
(alternatively ‘–output’) flag is optional (the default output format is YAML).
Build multiple dashboards at once
If you want to develop multiple dashboards as code, you should have 1 dashboard per file and then call the build command with the directory option:
Deploy dashboards
Once you are satisfied with the result of your DaC definition for a given dashboard, you can finally deploy it to Perses with the apply
command:
CICD setup
TODO