Merge pull request #62902 from gwynnemonahan/OSSM-4565

OSSM-4565: [DOC] Add Kiali Configuration for user-workload monitoring

Author: jab-rh

modules/ossm-integrating-with-user-workload-monitoring.adoc

@@ -15,9 +15,60 @@ The following steps show how to integrate Service Mesh with user-workload monito
 
 * User-workload monitoring is enabled.
 * {SMProductName} Operator 2.4 is installed.
+* Kiali Operator 1.65 is installed.
 
 .Procedure
 
+. Create a token to Thanos for Kiali by running the following commands:
++
+.. Set the `SECRET` environment variable by running the following command:
++
+[source,terminal]
+----
+$ SECRET=`oc get secret -n openshift-user-workload-monitoring | 
+ grep  prometheus-user-workload-token | head -n 1 | awk '{print $1 }'`
+----
++
+.. Set the `TOKEN` environment variable by running the following command:
++
+[source,terminal]
+----
+$ TOKEN=`echo $(oc get secret $SECRET -n openshift-user-workload-monitoring -o jsonpath='{.data.token}' | base64 -d`
+----
++
+.. Create a token to Thanos for Kiali by running the following command:
++
+[source,terminal]
+----
+$ oc create secret generic thanos-querier-web-token -n istio-system --from-literal=token=$TOKEN
+----
+
+. Configure Kiali for user-workload monitoring:
++
+[source,yaml]
+----
+apiVersion: kiali.io/v1alpha1
+kind: Kiali
+metadata:
+  name: kiali-user-workload-monitoring
+  namespace: istio-system
+spec:
+  external_services:
+    istio:
+      url_service_version: 'http://istiod-basic.istio-system:15014/version'
+    prometheus:
+      auth:
+        token: secret:thanos-querier-web-token:token
+        type: bearer
+        use_kiali_token: false
+      query_scope:
+        mesh_id: "basic-istio-system"
+      thanos_proxy:
+        enabled: true
+      url: https://thanos-querier.openshift-monitoring.svc.cluster.local:9091
+  version: v1.65
+----
+
 . Configure the SMCP for external Prometheus:
 +
 [source,yaml]
@@ -34,7 +85,12 @@ spec:
     grafana:
       enabled: false # <2>
     kiali:
-      enabled: false
+      name: kiali-user-workload-monitoring
+spec:
+  meshConfig:
+    extenstionProviders:
+    - name: prometheus
+      prometheus: {}
 ----
 <1> Disable the default Prometheus instance provided by OSSM.
 <2> Disable Grafana. It is not supported with an external Prometheus instance.
@@ -47,7 +103,7 @@ apiVersion: networking.k8s.io/v1
 kind: NetworkPolicy
 metadata:
   name: user-workload-access
-  namespace: bookinfo
+  namespace: bookinfo # <1>
 spec:
   ingress:
   - from:
@@ -58,6 +114,7 @@ spec:
   policyTypes:
   - Ingress
 ----
+<1> The custom network policy must be applied to all namespaces.
 
 . Apply a `Telemetry` object to enable traffic metrics in Istio proxies:
 +
@@ -99,11 +156,18 @@ spec:
     interval: 30s
     relabelings:
     - action: replace
-      replacement: "<smcp_name>-<smcp_namespace>" # <2>
+      replacement: "basic-istio-system" # <2>
       targetLabel: mesh_id
 ----
 <1> Since {product-title} monitoring ignores the `namespaceSelector` spec in `ServiceMonitor` and `PodMonitor` objects, you must apply the `PodMonitor` object in all mesh namespaces, including the control plane namespace.
-<2> A shared Prometheus instance can include metrics from multiple meshes. However, if you are deploying Kiali, the metrics must be associated with a single mesh. To associate metrics with a single mesh, add a unique `mesh_id` to each one. Doing so narrows the query scope in Kiali to only the relevant mesh metrics.
+<2> The string `"basic-istio-system"` is a combination of the SMCP name and its namespace, but any label can be used as long as it is unique for every mesh using user workload monitoring in the cluster. The `spec.prometheus.query_scope` of the Kiali resource configured in Step 2 needs to match this value.
++
+[NOTE]
+====
+If there is only one mesh using user-workload monitoring, then both the `mesh_id` relabeling and the `spec.prometheus.query_scope` field in the Kiali resource are optional (but the `query_scope` field given here should be removed if the `mesh_id` label is removed).
+
+If there might be multiple meshes using user-workload monitoring, then both the `mesh_id` relabelings and the `spec.prometheus.query_scope` field in the Kiali resource are required so that Kiali only sees metrics from its associated mesh. If Kiali is not being deployed, applying the `mesh_id` relabeling is still recommended so that metrics from different meshes can be distinguished from one another.
+====
 
 . Apply a `PodMonitor` object to collect metrics from Istio proxies:
 +
@@ -149,10 +213,17 @@ spec:
       action: replace
       targetLabel: pod_name
     - action: replace
-      replacement: "<smcp_name>-<smcp_namespace>" # <2>
+      replacement: "basic-istio-system" # <2>
       targetLabel: mesh_id
 ----
 <1> Since {product-title} monitoring ignores the `namespaceSelector` spec in `ServiceMonitor` and `PodMonitor` objects, you must apply the `PodMonitor` object in all mesh namespaces, including the control plane namespace.
-<2> A shared Prometheus instance can include metrics from multiple meshes. However, if you are deploying Kiali, the metrics must be associated with a single mesh. To associate metrics with a single mesh, add a unique `mesh_id` to each one. Doing so narrows the query scope in Kiali to only the relevant mesh metrics.
+<2> The string `"basic-istio-system"` is a combination of the SMCP name and its namespace, but any label can be used as long as it is unique for every mesh using user workload monitoring in the cluster. The `spec.prometheus.query_scope` of the Kiali resource configured in Step 2 needs to match this value.
++
+[NOTE]
+====
+If there is only one mesh using user-workload monitoring, then both the `mesh_id` relabeling and the `spec.prometheus.query_scope` field in the Kiali resource are optional (but the `query_scope` field given here should be removed if the `mesh_id` label is removed).
+
+If there might be multiple meshes using user-workload monitoring, then both the `mesh_id` relabelings and the `spec.prometheus.query_scope` field in the Kiali resource are required so that Kiali only sees metrics from its associated mesh. If Kiali is not being deployed, applying the `mesh_id` relabeling is still recommended so that metrics from different meshes can be distinguished from one another.
+====
 
 . Open the {product-title} web console, and check that metrics are visible.