Add optionals dashboards for cutomers#

Helm Chart repository#

The helm chart repository to manage optional dashboards for customers can be found here

Adding a new dashboard#

Generate the dashboard customized for Caascad#

Each new optional dashboard provided to customers must be adapted to work with our platform. To do it, please use the script scripts/generate_dashboard.py as follow:

1. Create the config file for the new dashboard#

Config files are stored in the scripts/config folder. They are used to adapt upstream dashboard to our platform.

Example: config/windows_node_exporter.yaml

We will use the upstream dashboard windows_node available at https://grafana.com/api/dashboards/2129/revisions/3/download as base for our Caascad "Windows Node Exporter dashboard"

dashboards:
  source:
    name: windows_node
    url: "https://grafana.com/api/dashboards/2129/revisions/3/download"
  title: "Caascad Windows Node Exporter"
  uid: "CaascadWindowsNodeExporter"

tags:
  - windows
  - windows_exporter
  - prometheus

replace_labels:
  - labels_source: "instance=~\"$server\""
    labels_replace: "cc_vm_source=\"$cc_vm_source\""

rename_metrics:
  - regex_source: "wmi_"
    regex_replace: "windows_"
  - regex_source: "_net_packets_outbound_discarded"
    regex_replace: "_net_packets_outbound_discarded_total"
  - regex_source: "_net_packets_outbound_errors"
    regex_replace: "_net_packets_outbound_errors_total"  
  - regex_source: "_net_packets_received_discarded"
    regex_replace: "_net_packets_received_discarded_total"
  - regex_source: "_net_packets_received_errors"
    regex_replace: "_net_packets_received_errors_total" 
  - regex_source: "[30s]"
    regex_replace: "[$interval]"

Key	Type	Yes/Optional	Description
`dashboards_source`	struct	yes	datasource for upstream dashboard
`dashboards_source.name`	string	yes	name of the dashboard
`dashboards_source.url`	string	yes	url of the upstream dashboard
`rename_metrics`	list	Optional	list of the metrics that need to be renamed
`rename_metrics[].regex_source`	string	Optional	the string that need to be modified in metric name
`rename_metrics[].regex_replace`	string	Optional	the string that need to be modified in metric name
`replace_labels`	list	yes	list of labels to replace
`replace_labels[].labels_source`	string	yes	the label that have to be replaced
`replace_labels[].labels_replace`	string	yes	the replacement label
`tags`	_list	yes	list of tags that be used as tag identifier in Grafana

2. Execute the script#

To execute the script run these commands:

nix-shell
cd scripts/generate_dashboard
python3 ./generate_dashboard.py -c config/<config_file.yaml> -o ../../helm/dashboards/<dashboard-name.json>

For example, if you need to generate the caascad_linux_node_exporter dashboard, the command will be:

python3 ./generate_dashboard.py -c config/linux_node_exporter.yaml -o ../../helm/dashboards/linux-node-exporter.json 
Pulling dashboard 'node_exporter_full.json' from: https://raw.githubusercontent.com/rfrail3/grafana-dashboards/master/prometheus/node-exporter-full.json ..........
Set custom caascad variables labels ..........
Replace labels in expression in panels ..........

3. (Optional) Provision a new provider in grafana#

Sometimes, you'll probably need to provision a new provider for your dashboards if those dashboards are related to a new feature.

Create a new branch of the caascad/terraform/envs-ng repository and edit the grafana.cue file as follow:

in the envs: [string]: configurations: [=~"^grafana"]: struct, add your provider in the _grafanadashboardProviders.client list.

Ask for a merge request and deploy the new provider

4. Reference your dashboard in the `values.yaml` file from the `grafana-dashboards` repository#

In the grafana-dashboards.yaml block, reference your dashboard.

Example: for node-exporter-full dashboard

node-exporter-full:
  file: "dashboards/node-exporter-full.json"
  grafana_directory: /tmp/dashboards/MonitoringVM
  enabled: false

Key	Type	Yes/Optional	Description
`grafana-dashboards`	struct	yes	Name of the feature
`grafana-dashboards.<dashboard_name>`	struct	yes	Name of the dashboard
`grafana-dashboards.<dashboard_name>.file`	string	yes	Location of the dashboard in the helm chart
`grafana-dashboards.<dashboard_name>.grafana_directory`	string	yes	The path of the provider dashboards defined above
`grafana-dashboards.<dashboard_name>.enabled`	boolean	false	The dashboard is desactivated by default. It's up to the customer to activate it

5. Allow the use of your new dashboard in the CI check#

The CI pipeline on customer side will check the values provided by the customers. So, you need to allow them to use your new dashboard. To do so, edit the file check.cue in the CI folder of the grafana-dashboards repository, as follow:

_names: [
        // List of the available dashboards
        "linux-node-exporter",
        "windows-node-exporter",
        "<your_new_dashboard_name>"
]

6. Update the `caascad-configurations-samples`#

Customers use those samples to know how to configure their feature. So you need to update the samples related to the grafana-dashboards

Create a branch of the repository caascad/caascad-configurations-samples.

Edit the file global/grafana-dashboards.yaml.

In the grafana_dashboards struct, add:

<dashboard-name>:
  enabled: true

7. Update the documentation for customers#

Update the table in the section List of optional dashboards of the client documentation with your new dashboard.

Update the client repository with trackbone#

To update the client repository, use Trackbone workflow.