Aller au contenu

Manage Grafana Dashboards#

Create a dashboard#

The creation of a dashboard is the first step. It is possible to duplicate an already existing dashboard or to create it from scratch.

Warning

You need to save it and export it to your laptop as often as you can.

When your dashboard is ready to be provisioned, export it (one more time) as a json file to your laptop. Then follow the section below to add your dashboard to Grafana as a provisionned dashboard. This will make it persistent over Grafana restarts.

Add Dashboard#

Step 1: Identify the dashboard label of the targeted Grafana#

Depending of the environment, the label has the following values :

  • Grafana infra and cloud/caascad: grafana-dashboard-caascad: "1"
  • Grafana cloud/client: grafana-dashboard-client: "1"
  • Grafana central and Grafana client: grafana_dashboard: "1"

Reference document for Grafana dashboard labels :

A sidecar container is deployed in the Grafana pod. It's role is to watch configmaps in all namespaces in the cluster and to filter out the ones with a label as defined in grafana.sidecar.dashboards.label.

The label information (grafana.sidecar.dashboards.label) is contained in grafana.cue.

Step 2 : Edit the JSON of your dashboard#

Edit the file where you saved your dashboards. The following fields to update are usually located at the end of the file.

  • title: ensure it is named as you want (no (Copy) or other tmp mentions).
  • uid: ensure the UID is new and unique. Example: P5DCFC7561CCDE821.
  • version: in a new dashboard, you should reset it to the value 1.

Step 3 : Helm template for dashboards#

In most cases, your dashboard comes with an application already deployed with helm. You will add the template below to that helm chart.

In case your dashboard is standalone, create a new helm chart (helm create <name of the chart>) and add the template below.

{{- if .Values.dashboards }}
{{ $files := .Files }}
{{- range $name, $dashboard := .Values.dashboards }}
{{- if eq $dashboard.enabled true }}
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ template "<name of your chart>.fullname" $ }}-dashboard-{{ $name }}
  labels:
{{ toYaml $dashboard.labels | indent 4 }}
{{- include "<name of your chart>.labels" $ | nindent 4 }}
data:
  "{{ template "<name of your chart>.fullname" $ }}-{{ $name }}.json":
  {{ toYaml ( $files.Get $dashboard.file ) | indent 4 }}
{{- end }}
{{- end }}
{{- end }}
  • Copy this template to your helm/templates/ directory.
  • Replace <name of your chart> with the name of your chart (check Chart.yaml or templates/_helpers.tpl)
  • Create a directory named helm/dashboards near the already existing helm/charts/ and helm/templates/ directories.
  • Edit the helm/values.yaml file and add a section dashboards: 
    dashboards:
  <name of your dashboard>:
    enabled: true
    file: dashboards/<file name of your dashboard>.json
    labels:
      <grafana-label>
  • Put the json file of your dashboard in the helm/dashboards/ directory and update the helm/values.yaml file above.
  • Replace grafana-label with the correct value (see above the dashboard label).

Important

Check list for the template file:

  • The template file should contain ---. It will fail if there are more than one dashboard without ---.
  • The dashboard json should be defined in a dedicated file. Consider using something like this : {{ toYaml ( $files.Get $dashboard.file ) | indent 4 }}. Don't put it inline in your template file. Inline dashboards are bad :
    • they are more difficult to edit or update (think about the YAML indentation),
    • they may contain go-template (e.g. {{ <template> }}) for Grafana that you need to escape for Helm. If you forget the escaping, the dashboard will be broken.
  • For Envs-ng/Trackbone, configmap names should be overridable. Example : name: {{ template "<name of your chart>.fullname" $ }}-dashboard-{{ $name }}
  • the key in the data: dict must be calculated and unique. Do not hardcode it. In the bad case where 2 dashboards would share the same key, one dashboard would never appear in Grafana.

Update Dashboard#

Make a copy of the dashboard and edit the copy like a new dashboard.

Warning

You need to save it and export it to your laptop as often as you can.

When your dashboard is ready to be provisioned in its new version, export it (one more time) as a json file to your laptop.

Before replacing the old dashboard file in the template, save these fields: title, uid and version (usually located at the end of the file).

Replace the old dashboard file with the new one. Edit these fields :

  • title: set the same name as the old one.
  • uid: set the same name as the old one.
  • version: reset the version to the old one, then increment it by 1.

Increment the version in your helm chart (Chart.yaml).

Now you are ready to deploy as usual with Trackbone/Envs-ng.

Delete Dashboard#

Edit the helm chart :

  • Remove the dashboard file.
  • Remove the dashboard in the values.yaml file.
  • If there are no more dashboards in the chart, remove the helm/templates/dashboards.yaml file.
  • Increment the version in your helm chart (Chart.yaml).

Now you are ready to deploy as usual with Trackbone/Envs-ng.

Tip

Sometimes Grafana may take time to notice the removal of the file. Sometimes it will not even notice it (unqualified bug). Feel free to restart Grafana with kubectl delete pod. Note that kubectl rollout restart will not fix the problem.

How to add tags to a Dashboard#

It is important to add at least one tag to each dashboard. This information needs to be added in dashboard JSON file.

"tags": [
      "app1-tag1",
      "app1-tag2"
   ],