Grafana Dashboards

Kupe ships a set of dashboards for cluster and workload health. Add your own on top, either quickly in the Grafana UI or as versioned ConfigMaps synced through GitOps.

Built-in dashboards

Kupe ships a small set of built-in dashboards that cover the most common investigation paths.

Folder	Dashboards	What they are for
Overview	Cluster Overview, Namespace Overview, Network Overview	Start here for broad health and cluster-level triage
Workloads	Deployments, Pods, Logs	Investigate rollout issues, pod behaviour, and workload log volume
Storage	Persistent Volumes	Watch stateful workloads and capacity trends
Databases	Databases, PostgreSQL	Your databases’ availability, storage and connections, and one database in depth
Registry	Registry	Your registry’s storage, images, activity, tokens and connections

The platform keeps these dashboards in sync as the default set evolves. If you want a tenant-specific version that you control, create your own dashboard rather than relying on the built-in copy to stay unchanged.

Create dashboards in the Grafana UI

Use the Grafana UI when you want to iterate quickly.

1. Open Grafana with your Kupe account.
2. Go to Dashboards and create a new dashboard.
3. Add panels against the metrics or logs datasource.
4. Save the dashboard into an existing folder or create a new one.

This is the simplest path for ad-hoc dashboards, team-specific views, and anything you expect to change frequently.

Manage dashboards with GitOps

Use ConfigMaps when you want dashboards versioned in Git and deployed through Argo CD or Helm.

Required labels

Label	Required	Purpose
kupe.cloud/grafana-dashboards	Yes, set to "true"	Marks the ConfigMap as dashboard content for Kupe
kupe.cloud/grafana-folder	No	Chooses the target Grafana folder. Defaults to General

Create the ConfigMap in your managed cluster. Kupe picks it up automatically and pushes the dashboard JSON into your Grafana org.

Example ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-app-dashboards
  namespace: backend
  labels:
    kupe.cloud/grafana-dashboards: "true"
    kupe.cloud/grafana-folder: "Workloads"
data:
  my-app-overview.json: |-
    {
      "title": "My App Overview",
      "uid": "my-app-overview",
      "version": 1,
      "schemaVersion": 39,
      "panels": []
    }

Constraints

• ConfigMap keys must end in .json
• each dashboard JSON must include a stable uid
• a single ConfigMap can contain multiple dashboards
• invalid JSON is skipped and will not appear in Grafana
• removing a dashboard key or deleting the ConfigMap removes the synced dashboard on the next update

Folder routing

The folder comes from kupe.cloud/grafana-folder, not from the filename. Create separate ConfigMaps when you want to place dashboards in different folders.

Helm example

If you manage dashboards through Helm, render them into a labelled ConfigMap:

templates/configmap-dashboard.yaml

{{- if .Values.dashboard.enabled }}
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Values.dashboard.configMapName | default "my-app-dashboards" }}
  labels:
    kupe.cloud/grafana-dashboards: "true"
    kupe.cloud/grafana-folder: {{ .Values.dashboard.folder | default "Workloads" | quote }}
data:
{{ (.Files.Glob "dashboards/*.json").AsConfig | indent 2 }}
{{- end }}

Dashboard design tips

• use variables for cluster, namespace, and workload identity
• prefer one useful dashboard per audience instead of one oversized dashboard for everything
• show both rate and error signals where possible
• keep default time ranges realistic for the type of investigation
• use datasource variables rather than hardcoded datasource UIDs when exporting dashboard JSON

Next steps

• Metrics: write and test PromQL queries
• Logs: add log panels or investigate issues in Explore