Update docs with multi-cluster info (#657)

Makefile

@@ -71,4 +71,4 @@ URL_IGNORE:=$(URL_IGNORE)$(NEW_URLS)
 ## validate-site: Builds the site and validates the pages. This is used for CI
 .PHONY: validate-site
 validate-site: build-hugo
-	${DORP} run -t -i --rm -v "$(shell pwd)":/site:z -w /site ${KIALI_HUGO_IMAGE} /bin/bash -c "npm prune && npm config set fetch-retry-mintimeout 20000 && npm config set fetch-retry-maxtimeout 120000 && hugo && htmlproofer --typhoeus '{\"connecttimeout\": 30, \"timeout\": 30}' --hydra='{\"max_concurrency\": 6}' --allow-hash-href --allow-missing-href --ignore-empty-alt --ignore-missing-alt --no-check-external-hash --no-check-internal-hash --no-enforce-https --ignore_status_codes "302" --ignore-urls \"${URL_IGNORE}\" ./public"
+	${DORP} run -t -i --rm -v "$(shell pwd)":/site:z -w /site ${KIALI_HUGO_IMAGE} /bin/bash -c "npm prune && npm config set fetch-retry-mintimeout 20000 && npm config set fetch-retry-maxtimeout 120000 && hugo && htmlproofer --typhoeus '{\"connecttimeout\": 30, \"timeout\": 30}' --hydra='{\"max_concurrency\": 6}' --allow-hash-href --allow-missing-href --ignore-empty-alt --ignore-missing-alt --no-check-external-hash --no-check-internal-hash --no-enforce-https --ignore_status_codes "302" --ignore-urls \"${URL_IGNORE}\" ./public"

content/en/docs/Configuration/istio.md

@@ -5,7 +5,7 @@ description: >
   installation configuration profiles](https://istio.io/latest/docs/setup/additional-setup/config-profiles/).
   If you are [customizing your Istio installation](https://istio.io/latest/docs/setup/additional-setup/customize-installation/)
   some Kiali settings may need to be adjusted.
-  
+
   Also, some Istio management features can be enabled or disabled selectively.
 ---
 
@@ -59,23 +59,6 @@ spec:
       istiod_pod_monitoring_port: 15014
 ```
 
-## Multi-cluster support
-
-Kiali has [experimental support for Istio multi-cluster installations]({{< relref "../Features/multi-cluster" >}})
-using the [_multi-primary on different networks_ pattern](https://istio.io/latest/docs/setup/install/multicluster/multi-primary_multi-network/).
-This support is enabled by default, but requires the Kiali ServiceAccount to
-have read access to secrets in the Istio namespace. If you don't have a
-multi-cluster setup or don't want Kiali to have read access to secrets in the
-Istio namespace, you can disable clustering support:
-
-
-```yaml
-spec:
-  kiali_feature_flags:
-    clustering:
-      enabled: false
-```
-
 ## Root namespace
 
 Istio's _root namespace_ is the namespace where you can create some resources
@@ -164,6 +147,6 @@ spec:
 
 There following are links to sections of Kiali blogs posts that briefly
 explains these features:
-* [Sidecar auto-injection control description](https://medium.com/kialiproject/kiali-releases-1-21-to-1-24-overview-2a864f7d0fce#0f2c)
-* [Istio's canary upgrade assistance description](https://medium.com/kialiproject/kiali-releases-1-34-to-1-39-overview-587f33fac41a#8104) 
 
+- [Sidecar auto-injection control description](https://medium.com/kialiproject/kiali-releases-1-21-to-1-24-overview-2a864f7d0fce#0f2c)
+- [Istio's canary upgrade assistance description](https://medium.com/kialiproject/kiali-releases-1-34-to-1-39-overview-587f33fac41a#8104)

content/en/docs/Configuration/multi-cluster.md

@@ -0,0 +1,63 @@
+---
+title: "Multi-cluster"
+description: "Configuring Kiali for a multi-cluster mesh."
+---
+
+Kiali has [experimental support for Istio multi-cluster installations]({{< relref "../Features/multi-cluster" >}}).
+
+![Kiali multi-cluster](/images/documentation/configuration/multi-cluster.png)
+
+Before proceeding with the setup, ensure you meet the requirements.
+
+#### Requirements
+
+1. **Primary-remote istio deployment.** Only the primary-remote istio deployment is currently supported.
+
+2. **Aggregated metrics and traces.** Kiali needs a single endpoint for metrics and a single endpoint for traces where it can consume aggregated metrics/traces across all clusters. There are many ways to aggregate metrics/traces such as prometheus federation or using OTEL collector pipelines but setting these up are outside of the scope of Kiali.
+
+3. **Anonymous or OpenID authentication strategy.** The unified multi-cluster configuration currently only supports anonymous or OpenID [authentication strategies]({{< relref "../Configuration/authentication" >}}). In addition, current support varies by provider for OpenID across clusters.
+
+#### Setup
+
+The unified Kiali multi-cluster setup requires the Kiali Service Account (SA) to have read access to each Kubernetes cluster in the mesh. This is separate from the user credentials that are required when a user logs into Kiali. The user credentials are used to check user access to a namespace and to perform write operations. In anonymous mode, the Kiali SA is used for all operations and write access is also required. To give the Kiali SA access to each remote cluster, a kubeconfig with credentials needs to be created and mounted into the Kiali pod. While the location of Kiali in relation to the controlplane and dataplane may change depending on your istio deployment model, the requirements will remain the same.
+
+1. **Create a remote kubeconfig secret.** You can use [this script](https://github.com/kiali/kiali/blob/master/hack/istio/multicluster/kiali-prepare-remote-cluster.sh) to simplify this process for you. Running this script will:
+
+   - Create a Kiali Service Account in the remote cluster.
+   - Create a role/role-binding for this service account in the remote cluster.
+   - Create a kubeconfig file and save this as a secret in the namespace where Kiali is deployed. The Kiali operator will auto-detect the secret and mount it into the Kiali pod.
+
+   In order to run this script you will need adequate permissions configured in your local kubeconfig, for both the cluster on which Kiali is deployed and the remote cluster. You will need to repeat this step for each remote cluster.
+
+   ```
+   curl -L -o kiali-prepare-remote-cluster.sh https://raw.githubusercontent.com/kiali/kiali/master/hack/istio/multicluster/kiali-prepare-remote-cluster.sh
+   chmod +x kiali-prepare-remote-cluster.sh
+   ./kiali-prepare-remote-cluster.sh --kiali-cluster-context east --remote-cluster-context west --view-only false
+   ```
+
+Adding remote kubeconfig secrets to Kiali effectively puts Kiali in "multi-cluster" mode and Kiali will begin using those credentials to communicate with the other clusters in the mesh.
+
+2. Optional - **Configure tracing with cluster ID.** By default, traces do not include their cluster name in the trace tags however this can be added using the istio telemetry API.
+
+```
+kubectl apply -f - <<EOF
+apiVersion: telemetry.istio.io/v1alpha1
+kind: Telemetry
+metadata:
+  name: mesh-default
+  namespace: istio-system
+spec:
+  # no selector specified, applies to all workloads
+  tracing:
+  -  customTags:
+      cluster:
+        environment:
+          name: "ISTIO_META_CLUSTER_ID"
+EOF
+```
+
+3. Optional - **Configure user access in your OIDC provider.** When using anonymous mode, the Kiali SA credentials will be used to display mesh info to the user. When not using anonymous mode, Kiali will check the user's access to each configured cluster's namespace before showing the user any resources from that namespace. Please refer to your OIDC provider's instructions for configuring user access to a kube cluster for this.
+
+4. Optional - **Narrow metrics to mesh.** If your unified metrics store also contains data outside of your mesh, you can limit which metrics Kiali will query for by setting the [query_scope](/docs/configuration/kialis.kiali.io#.spec.external_services.custom_dashboards.prometheus.query_scope) configuration.
+
+That's it! From here you can login to Kiali and manage your mesh across both clusters from a single Kiali instance.

content/en/docs/Features/multi-cluster.md

@@ -1,24 +1,56 @@
 ---
-title: "Multi-cluster Deployment"
+title: "Multi-cluster"
 description: "Advanced Mesh Deployment and Multi-cluster support."
 ---
 
-A basic Istio mesh deployment has a single control plane with a single data plane, deployed on a single Kubernetes cluster. But Istio supports a variety of advanced 
+{{% alert color="warning" %}}
+Support for multi-cluster deployments is currently **experimental** and subject to change.
+{{% /alert %}}
+
+A basic Istio mesh deployment has a single control plane with a single data plane, deployed on a single Kubernetes cluster. But Istio supports a variety of advanced
 [deployment models](https://istio.io/latest/docs/ops/deployment/deployment-models/). It allows a mesh to span multiple primary (control plane) and/or remote (data plane only) clusters, and can use a single or
-[multi-network](https://istio.io/latest/docs/ops/deployment/deployment-models/#multiple-networks) approach.  The only strict rule is that within a mesh service names are unique. A non-basic mesh deployment generally involves multiple clusters.  See [installation instructions](https://istio.io/docs/setup/install/multicluster/) for more detail on installing advanced mesh deployments.
+[multi-network](https://istio.io/latest/docs/ops/deployment/deployment-models/#multiple-networks) approach. The only strict rule is that within a mesh service names are unique. A non-basic mesh deployment generally involves multiple clusters. See [installation instructions](https://istio.io/docs/setup/install/multicluster/) for more detail on installing advanced mesh deployments.
+
+A single Kiali install can currently work with at most one mesh, one istiod, one metric store and one trace store but it can be configured for "single cluster" or "multi-cluster". All clusters must be part of the same mesh, have data planes controlled by the single istiod (control plane), and report to the same metric and trace store, whether directly or via some sort of aggregator. See the [multi-cluster configuration page]({{< relref "../Configuration/multi-cluster" >}}) for more information on requirements.
+
+For multi-cluster configurations, Kiali provides a unified view and management of your mesh across clusters.
+
+## Graph View: Cluster and Namespace Boxing
 
-Kiali v1.29 introduces experimental support for advanced deployment models. The recommended Kiali deployment model is to deploy an instance of Kiali along with each Istio primary control plane.  Each Kiali instance will work as it has in the past, with the configured Kubernetes, Prometheus and Jaeger instances.  It will concern itself with the istio config managed by the local primary.  But, there are two new additions:
+Istio provides cluster names in the traffic telemetry for multi-cluster installations. The Kiali graph can use this information to better visualize clusters and namespaces. The Display menu offers two multi-cluster related options: Cluster Boxes and Namespace Boxes. When enabled, either separately or together, the graph will generate boxes to help identify the relevant nodes and edges, and to see traffic traveling between them.
+
+Each box type supports selection and provides a side-panel summary of traffic. Below we see a Bookinfo traffic graph for when Bookinfo services are deployed across the East and West clusters. The West cluster box is selected. You see traffic for all services and workloads across both clusters. Single cluster configurations will show some traffic across clusters but not all.
+
+![Multi-cluster traffic graph](/images/documentation/features/multi-cluster-traffic-graph.png "Multi-cluster traffic graph")
 
 ## List View: Mesh Discovery
-Kiali will attempt to discover the clusters configured in the mesh.  And it will identify the *home* cluster, meaning the cluster on which it is installed and from which it presents its traffic, traces and Istio config.  In the following example there are two clusters defined in the mesh, _Kukulcan_ and _Tzotz_.  Kukulcan is identified as the home cluster in three places: the browser tab (not shown), the masthead, and with a star icon in the clusters list:
 
-![Mesh list view](/images/documentation/features/multi-cluster-mesh-v1.29.png "Mesh list view")
+Kiali will show cluster information for all clusters in the mesh. It will identify the home cluster, meaning the cluster on which it is installed and from which it presents its traffic, traces and Istio config. In the following example there are two clusters defined in the mesh, East and West. East is identified as the home cluster in three places: the browser tab (not shown), the masthead, and with a star icon in the clusters list:
 
-## Graph View: Cluster and Namespace Boxing
+![Multi-cluster mesh discovery](/images/documentation/features/multi-cluster-mesh-view.png "Multi-cluster mesh discovery")
+
+## Unified Multi-cluster configuration
+
+Unlike single-cluster configurations, multi-cluster configurations show list/details pages across all clusters.
+
+### List Views: Aggregated mesh view
+
+With a multi-cluster Kiali configuration, you can view all apps, workloads, services, and Istio config in your mesh from a single place. Istio configuration is currently read only for remote clusters.
+
+![Multi-cluster list pages](/images/documentation/features/multi-cluster-list.png "Multi-cluster list pages")
+
+### Detail Views: Dig into details across clusters
+
+The detail pages provide the same functionality across all clusters that you have access to for a single cluster, including viewing logs, metrics, traces, envoy details, and more.
+
+![Multi-cluster detail pages](/images/documentation/features/multi-cluster-details.png "Multi-cluster detail pages")
+
+### Overview: Cross cluster namespace info
 
-Starting in v1.8 Istio provides cluster names in the traffic telemetry for multi-cluster installations.  The Kiali graph can now use this information to better visualize clusters and namespaces.  The Display menu now offers two new options: Cluster Boxes and Namespace Boxes.  When enabled, either separately or together, the graph will generate boxes to help more easily identify the relevant nodes and edges, and to see traffic traveling between them.
+The overview page shows namespace information across all configured clusters.
 
-Each new box type supports selection and will provide a side-panel summary of traffic.  Below we see a Bookinfo traffic graph for when Bookinfo services are deployed across the Kukulcan and Tzotz clusters. The Kukulcan cluster box is selected. Because Kukulcan is the Kiali home cluster, you see traffic from the perspective of Kukulcan. Note that you do not see the internal traffic on Tzotz (the requests from Reviews to Ratings service).  To see traffic from the Tzotz cluster point of view, you would open a Kiali session on Tzotz, assuming you have privileges.
+![Multi-cluster overview](/images/documentation/features/multi-cluster-overview.png "Multi-cluster overview")
 
-![Multi-cluster traffic graph](/images/documentation/features/multi-cluster-graph-v1.29.png "Multi-cluster traffic graph")
+## Roadmap
 
+See [this issue](https://github.com/kiali/kiali/issues/5618) to see the multi-cluster roadmap for Kiali.