feat: Enterprise multi-cluster scalability

Signed-off-by: Ilya Buziuk <ibuziuk@redhat.com>

Author: ibuziuk

modules/administration-guide/pages/running-at-scale.adoc

@@ -174,15 +174,51 @@ Consider leveraging open-source solutions such as link:https://karpenter.sh/[Kar
 By design, {prod} is not multi-cluster aware, and you can only have one instance per cluster.
 However,
 you can run {prod} in a multi-cluster environment by deploying {prod} in each different cluster
-and using a load balancer or DNS-based routing to direct traffic to the appropriate instance based on the user’s location or other criteria.
+and using routing mechanisms to direct users to the appropriate instance.
 This approach can help
 improve performance and reliability by distributing the workload across multiple clusters
 and providing redundancy in case of cluster failures.
 
 .Scheme of a multi-cluster environment
 image::running-at-scale/snip_{project-context}-multi-cluster.png[Scheme of a multi-cluster environment]
 
-You can test running {prod-short} in a multi-cluster by using the link:https://developers.redhat.com/developer-sandbox[Developer Sandbox],
+.The Multicluster Redirector Solution
+
+Red Hat offers an open-source Quarkus-based service called the `devspaces-multicluster-redirector` that acts as a single gateway for developers, automatically redirecting them to the correct {prod} instance on the correct cluster based on their OpenShift group membership.
+The community-supported version is currently available in the link:https://github.com/codeready-toolchain/crw-multicluster-redirector[GitHub repository].
+
+.Architecture and Requirements
+
+A critical requirement for the multicluster redirector is that all users must be provisioned to the host cluster where the redirector deploys. Users authenticate through this cluster's OAuth flow, even if they never run workloads there. The host cluster's OpenShift groups determine the routing logic.
+
+.Configuration
+
+The routing configuration uses a `ConfigMap` named `devspaces-openshift-group-mapping` containing JSON that maps OpenShift groups to {prod} URLs:
+
+[source,json]
+----
+{
+  "team-alpha": "https://devspaces-alpha.example.com"
+}
+----
+
+The redirector watches this file and updates routing tables in real-time without requiring restarts.
+
+.Operational Flow
+
+The routing process follows these steps:
+
+. OAuth authentication via proxy sidecar
+. Identity and group information passed through HTTP headers
+. OpenShift API queries verify group memberships
+. Mapping lookup determines the appropriate {prod} URL
+. User redirects to their designated cluster instance
+
+When users belong to multiple OpenShift groups, the system displays a selection dashboard allowing developers to choose their desired {prod} instance.
+
+.Developer Sandbox Example
+
+You can test running {prod-short} in a multi-cluster environment by using the link:https://developers.redhat.com/developer-sandbox[Developer Sandbox],
 a free trial environment by Red Hat with pre-configured tools and services.
 From an infrastructure perspective,
 the Developer Sandbox consists of multiple link:https://www.redhat.com/en/technologies/cloud-computing/openshift/aws[ROSA] clusters.
@@ -191,12 +227,3 @@ the productized version of {prod} is installed
 and configured using link:https://argo-cd.readthedocs.io/en/stable/[Argo CD].
 Since the user base is spread across multiple clusters,
 link:https://workspaces.openshift.com/[workspaces.openshift.com] is used as a single entry point to the productized {prod} instances.
-You can find implementation details about the multicluster redirector in the following link:https://github.com/codeready-toolchain/crw-multicluster-redirector[GitHub repository].
-
-[IMPORTANT]
-====
-The multi-cluster architecture of link:https://workspaces.openshift.com/[workspaces.openshift.com] is part of the link:https://developers.redhat.com/developer-sandbox[Developer Sandbox].
-It is a Developer Sandbox-specific solution
-that cannot be reused as-is in other environments.
-However, you can use it as a reference for implementing a similar solution well-tailored to your specific multicluster needs.
-====