From 1fc9fb452e024292eec588400a32bc6797388dfd Mon Sep 17 00:00:00 2001
From: daseul cho <102581914+jds9090@users.noreply.github.com>
Date: Mon, 4 May 2026 18:22:13 +0900
Subject: [PATCH] docs: clarify Grafana multi-cluster monitoring (#1144)

---
 docs/content/guides/monitoring.md | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/docs/content/guides/monitoring.md b/docs/content/guides/monitoring.md
index 9d8994a..4473dfd 100644
--- a/docs/content/guides/monitoring.md
+++ b/docs/content/guides/monitoring.md
@@ -246,9 +246,20 @@ kubeScheduler:
 
 ## Grafana
 
-**Grafana** is a widely used tool for visualizing metrics. You can create custom dashboards for Tenant Control Planes and visualize the metrics scraped by Prometheus. The Prometheus Operator Helm Chart also installs Grafana with a set of predefined dashboards for Kubernetes Control Plane components: `kube-apiserver`, `kube-scheduler`, and `kube-controller-manager`. These dashboards can serve as a starting point for creating custom dashboards for Tenant Control Planes or can be used as-is.
+**Grafana** is a widely used tool for visualizing metrics. You can create custom dashboards for Tenant Control Planes and visualize the metrics scraped by Prometheus. When using `kube-prometheus-stack`, Grafana can also be installed with a set of predefined dashboards for Kubernetes Control Plane components: `kube-apiserver`, `kube-scheduler`, and `kube-controller-manager`. These dashboards can serve as a starting point for creating custom dashboards for Tenant Control Planes or can be used as-is, provided that the scraped metrics use the labels expected by those dashboards.
 
 !!! tip "Multi-Cluster Mode"
-    In Grafana, enable the "Multi-Cluster Mode" option for improved visualization of metrics. This option is available in the Grafana settings.
+    When using the predefined `kube-prometheus-stack` dashboards to visualize multiple Tenant Control Planes, enable the multi-cluster dashboard mode in the chart values:
+
+    ```yaml
+    grafana:
+      sidecar:
+        dashboards:
+          multicluster:
+            global:
+              enabled: true
+    ```
+
+    This exposes the `cluster` variable in the dashboards. Each Tenant Control Plane `ServiceMonitor` should relabel scraped metrics with a unique `cluster` value, for example the Tenant Control Plane name, and with the standard Control Plane `job` labels expected by the dashboards: `apiserver`, `kube-scheduler`, and `kube-controller-manager`.
 
 That's it!