Create visualization dashboards on your AO project

This section describes the process to create and manage dashboards in your system monitoring instance. Use dashboards to perform monitoring operations in your project, such as network monitoring and server monitoring.

After the Observability platform collects the metrics produced by workloads deployed in your Google Distributed Cloud (GDC) air-gapped project, the configuration saves the associated metric labels and aggregates files from all data sources. Then, you can create customized dashboards to query and visualize metrics from the user interface (UI) of the project's system monitoring instance.

A dashboard is a dynamic visual arrangement of one or more customizable panels that interact with metrics configured in data sources for data observability. By making queries, you can use each of these panels to visualize and expose specific metrics from your Distributed Cloud components for system monitoring.

The Observability platform exposes an API that lets you configure customizations for the visual arrangement of your metrics. For example, establish acceptance thresholds, display proper signals, label graphs, and choose a consistent time resolution.

Work through the following steps to create a dashboard:

Complete the prerequisites from the Before you begin section.
Open the endpoint of the system monitoring instance of your project.
Create a ConfigMap object for your dashboard.
Create a Dashboard custom resource.

Before you begin

Before creating dashboards, you must obtain access to the system monitoring instance. For more information, see Get access to dashboards.

After obtaining the corresponding role, work through the following steps:

Collect metrics from your Distributed Cloud project.
Set the path of the kubeconfig file as an environment variable:
```
export KUBECONFIG=KUBECONFIG_FILE
```
Replace KUBECONFIG_FILE with the path of the kubeconfig file on the admin cluster where you want to create the dashboard.

System monitoring instance endpoint

The following URL is the endpoint of the monitoring instance of your project:

https://GDC_URL/PROJECT_NAMESPACE/grafana

Replace the following:

GDC_URL: the URL of your organization in GDC
PROJECT_NAMESPACE: the namespace of your project

Create a `ConfigMap` object for your dashboard

Follow these steps to create a ConfigMap object containing the JSON model of the dashboard:

Go to the endpoint of the system monitoring instance of your project.
From the navigation menu, click the Add button.
From the drop-down menu that is displayed, click Dashboard. The instance creates an empty dashboard.
On the empty dashboard, add all the panels that you want. You can customize your details and edit your panels to supply your queries or make other updates.

Note: When customizing your dashboard, ensure to implement the best practices for your use case to facilitate the visualization and interpretation of observability data from your components. For example, establish acceptance thresholds, display useful signals, properly label graphs, and choose a consistent time resolution.
From the menu bar, click the Dashboard settings button to open the Settings page.
From the navigation menu, click the JSON Model option.
Copy the JSON model of the dashboard and paste it in a plain-text file to keep it available to you.
Replace the top-level id and uid fields with the null value in the JSON model.
Create a ConfigMap object from the command line interface (CLI). In the data section of your ConfigMap object, paste the JSON model that you previously copied inside a .json file:
```
cat <<EOF | kubectl --kubeconfig ${KUBECONFIG} apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  namespace: PROJECT_NAMESPACE
  name: DASHBOARD_CONFIGMAP_NAME
data:
  JSON_FILE_NAME.json: |
    {
    <JSON model of the dashboard>
    }
EOF
```
Replace the following:
- PROJECT_NAMESPACE: the namespace of your project
- DASHBOARD_CONFIGMAP_NAME: the name you want to give to your ConfigMap object
- JSON_FILE_NAME: the name you want to give to the file where you paste the JSON model of the dashboard
For an example of what this object must look like, see the ConfigMap example for a dashboard.
Deploy the ConfigMap object of your dashboard into the admin cluster.

`ConfigMap` example for a dashboard

The following YAML file shows an example of the ConfigMap object of a dashboard in the platform-obs namespace:

  apiVersion: v1
  kind: ConfigMap
  metadata:
    namespace: platform-obs
    name: my-project-dashboard-configmap
  data:
    my-project-dashboard.json: |
      {
      "annotations": {
        "list": [
          {
            "builtIn": 1,
            "datasource": "--",
            "enable": true,
            "hide": true,
            "iconColor": "rgba(0, 211, 255, 1)",
            "name": "Annotations & Alerts",
            "type": "dashboard"
          }
        ]
      },
      "editable": true,
      "graphTooltip": 0,
      "id": null,
      "links": [],
      "panels": [],
      "schemaVersion": 27,
      "style": "dark",
      "tags": [],
      "templating": {
        "list": []
      },
      "time": {
        "from": "now-6h",
        "to": "now"
      },
      "timepicker": {},
      "timezone": "",
      "title": "Sample dashboard",
      "uid": null,
      "version": 0
      }

Create a `Dashboard` custom resource

Follow these steps to create a Dashboard custom resource and enable the Observability dashboard on your project:

Create a Dashboard custom resource from the CLI and configure the file with the name you gave to the ConfigMap object of your dashboard:
```
cat <<EOF | kubectl --kubeconfig ${KUBECONFIG} apply -f -
apiVersion: observability.gdc.goog/v1
kind: Dashboard
metadata:
  namespace: PROJECT_NAMESPACE
  name: CUSTOM_RESOURCE_NAME
spec:
  configMapRef:
    name: DASHBOARD_CONFIGMAP_NAME
    namespace: PROJECT_NAMESPACE
    key: JSON_FILE_NAME.json
  foldername: Default
EOF
```
Replace the following:
- PROJECT_NAMESPACE: the namespace of your project
- CUSTOM_RESOURCE_NAME: the name you want to give to your Dashboard custom resource
- DASHBOARD_CONFIGMAP_NAME: the name you gave to the ConfigMap object for your dashboard
- JSON_FILE_NAME: the name you gave to the file that contains the JSON model of the dashboard in the ConfigMap object
Deploy the Dashboard custom resource into the project namespace. This action configures the Observability service to import the predefined dashboard to the system monitoring instance of your project.

Dashboards are isolated from other projects, as are metrics and logs. Consequently, if you want to use the same dashboard in multiple projects, deploy a Dashboard custom resource in each one. Also, the system logging and monitoring data that the dashboard accesses must be available in all those projects.

The process that handles the dashboards detects changes to both the Dashboard custom resource and the ConfigMap object. If you modify one or the other, the program reflects the change in the system monitoring instance. To update or delete a dashboard, you must apply the changes in the custom resource and deploy it again. You can't save any updates performed directly in the UI of the system monitoring instance.

To create a dashboard in a folder or change the folders, modify the foldername value in the spec section of the Dashboard custom resource. Otherwise, leave it as Default. The process automatically creates folders if they don't exist.