Skip to content

Enterprise multi-cluster scalability #3027

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ibuziuk wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Enterprise multi-cluster scalability #3027

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6850812
feat: Enterprise multi-cluster scalability
ibuziuk Feb 12, 2026
35194da
fixup! udpate structure
ibuziuk Feb 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 41 additions & 7 deletions modules/administration-guide/pages/running-at-scale.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,15 +174,14 @@ 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]
.Developer Sandbox Example

You can test running {prod-short} in a multi-cluster by using the link:https://developers.redhat.com/developer-sandbox[Developer Sandbox],
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.
Expand All @@ -191,12 +190,47 @@ 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.

image::running-at-scale/snip_{project-context}-multi-cluster.png[Scheme of a multi-cluster environment]

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.
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.
====

.The Multicluster Redirector Solution

Red Hat offers an open-source Quarkus-based service called the 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.