Manage Grafana dashboards and alerts as custom resources

Starting in 6.3.0, the Grafana Operator manages the platform Grafana instance at /grafana. Instead of editing dashboards and alerts in the Grafana UI and relying on a persistent volume to keep them, you define them as Kubernetes custom resources (CRs), commit those manifests to source control, and let the operator reconcile them into Grafana. This mirrors how Domino ships its own dashboards, keeps your customizations under version control, and makes them easy to reproduce across deployments.

This workflow applies to self-managed deployments where you can apply Kubernetes manifests in the Domino cluster. On Domino Cloud you do not have cluster access, so this page is not applicable. Continue to work with your Domino contact for changes on Cloud.

Prerequisites

Domino 6.3.0 or later, with the platform Grafana instance managed by the Grafana Operator.
kubectl access to the Domino cluster, and permission to create resources in the domino-platform namespace (or the namespace where Grafana is deployed in your environment).
The Grafana Operator custom resource definitions installed in the cluster. Domino installs these automatically as part of the platform Grafana instance.

Custom resource types

The Grafana Operator provides several custom resource kinds under the grafana.integreatly.org/v1beta1 API group. The ones you use to add or override content are:

Kind	Purpose
`GrafanaDashboard`	A single Grafana dashboard, expressed as its JSON definition.
`GrafanaAlertRule`	A single Grafana alert rule.
`GrafanaDataSource`	A data source such as Prometheus. Domino provisions the platform data source for you.
`GrafanaContactPoint`, `GrafanaNotificationPolicy`	Alerting contact points and notification policies.

Domino ships its standard dashboards and alerts as these same CRs, so any dashboard or alert you can view in the Grafana UI is defined as a manifest somewhere in the platform.

How CRs attach to the Grafana instance

A single Kubernetes cluster can host more than one Grafana instance. The operator uses label selectors to decide which CRs belong to which instance. Every dashboard, alert, and data source CR must both:

Carry the label the target Grafana instance selects on.
Set spec.instanceSelector.matchLabels to the same label.

The platform Grafana instance selects on the dashboards: grafana-platform label for dashboards and datasources: grafana-platform for data sources. If the labels on your CR do not match exactly, the operator does not attach it to the instance and the dashboard or alert does not appear in the Grafana UI.

Add a custom dashboard

Build the dashboard in the Grafana UI as usual and export it as JSON (Dashboard settings > JSON Model).
Save the JSON to a file in your infrastructure repository, next to your other Kubernetes manifests.

Create a GrafanaDashboard manifest that references the JSON and carries the platform selector label. For example:

apiVersion: grafana.integreatly.org/v1beta1
kind: GrafanaDashboard
metadata:
  name: my-team-workload-overview
  namespace: domino-platform
  labels:
    dashboards: grafana-platform
spec:
  allowCrossNamespaceImport: false
  folder: Custom
  instanceSelector:
    matchLabels:
      dashboards: grafana-platform
  json: |
    {
      "title": "My Team Workload Overview",
      "panels": [ ... ],
      "schemaVersion": 39,
      "version": 1
    }

Apply the manifest:

kubectl apply -f my-team-workload-overview.yaml

Open Grafana at https://<your-domino-domain>/grafana and confirm the dashboard appears in the folder you set. If it does not, see Troubleshoot label and selector mismatches below.

Add a custom alert rule

Add a GrafanaAlertRule manifest in the same repository with the same label contract. Apply it with kubectl apply and confirm the rule appears under Alerting in the Grafana UI.

Override a Domino-shipped dashboard or alert

The operator reconciles the CR whose name matches an existing dashboard or alert, so to override a standard Domino dashboard you create a CR of your own with the same title in the same folder and different content. You do not edit the Domino-managed CR directly; changes to that CR are overwritten on the next upgrade. Keeping your override in your own repository preserves it across Domino upgrades.

Troubleshoot label and selector mismatches

If a dashboard or alert CR does not appear in Grafana after you apply it, the most common cause is a label or selector that does not match the platform instance. Confirm the labels the platform instance selects on:

kubectl -n domino-platform get grafana -o yaml | grep -A2 labels:

Confirm your CR carries the same labels and selector:

kubectl -n domino-platform get grafanadashboard <name> -o yaml \
  | yq '{"metadata.labels": .metadata.labels, "spec.instanceSelector": .spec.instanceSelector}'

If the values do not match exactly, fix the CR and re-apply it. Cross-namespace imports require spec.allowCrossNamespaceImport: true on the CR.

Store CRs in source control

Treat your Grafana CRs the same way you treat any other Kubernetes manifest: keep them in a Git repository, review changes through pull requests, and apply them through your existing GitOps or CI/CD pipeline. Dashboards or alerts that only live in the Grafana UI on the platform persistent volume are not preserved through backups today, so anything you want to keep must exist as a CR in source control. See Access Grafana for guidance on migrating existing UI-only content off the legacy instance before it is removed in a later release.

Architecture & deployment

Domino installation

Identity & access

Infrastructure & compute

Platform configuration

Data administration

Operations, monitoring & cost

Security & compliance

Troubleshooting

Manage Grafana dashboards and alerts as custom resources

Prerequisites

Custom resource types

How CRs attach to the Grafana instance

Add a custom dashboard

Add a custom alert rule

Override a Domino-shipped dashboard or alert

Troubleshoot label and selector mismatches

Store CRs in source control

Next steps

​Prerequisites

​Custom resource types

​How CRs attach to the Grafana instance

​Add a custom dashboard

​Add a custom alert rule

​Override a Domino-shipped dashboard or alert

​Troubleshoot label and selector mismatches

​Store CRs in source control

​Next steps

Prerequisites

Custom resource types

How CRs attach to the Grafana instance

Add a custom dashboard

Add a custom alert rule

Override a Domino-shipped dashboard or alert

Troubleshoot label and selector mismatches

Store CRs in source control

Next steps