Virtual clusters overview
A virtual cluster is a Gateway Manager construct that groups physical gateway clusters under a single name. Platform features—integrations, code on canvas, FlowAI, Configuration Manager, gateway services, and others—target a virtual cluster by name exactly as they would a physical cluster. Gateway Manager handles all routing and distribution behind that name, so no per-feature changes are required when you add resilience or scale-out to your gateway deployments.
For larger deployments, load-balanced virtual clusters let you compose independent, standalone gateway servers into a single logical cluster without a shared etcd database. Instead of scaling by adding runners to one etcd-clustered physical cluster, you add independent standalone gateways as members and Gateway Manager distributes jobs across them—reducing infrastructure footprint and removing cross-region database dependencies for multi-region deployments.
Virtual cluster types
When you create a virtual cluster, you choose a distribution type. The type determines how Gateway Manager routes jobs to member physical clusters.
Active/standby
One member serves traffic at a time. You designate a primary cluster and an ordered list of backup clusters. If the primary becomes unreachable, Gateway Manager automatically fails over to the first available backup. When the primary recovers, new jobs route back to it; jobs already running on the backup cluster complete normally.
Use active/standby when your primary goal is resilience against a cluster outage.
Load balancing
All members serve traffic simultaneously (active-active). Gateway Manager tracks a counter per member cluster: the counter increments when a job is sent to that member and decrements when the member responds. Each new job goes to the reachable member with the lowest counter value. No weighting for cluster capacity is applied. Position in the backup list breaks ties between members with equal counter values.
Use load balancing when you need to spread job volume across many gateway servers or across multiple regions.
You can change a virtual cluster’s distribution type at any time without recreating the cluster. Platform features that reference the cluster by name require no reconfiguration when the type changes.
When to use each type:
How jobs are distributed
Jobs are dispatched to a member cluster once, at submission time, and run to completion on that member regardless of virtual cluster type.
For active/standby virtual clusters, the primary cluster receives all new jobs when it’s reachable. Failover is automatic and ordered—if the primary becomes unreachable, Gateway Manager works through the backup list in sequence until it finds a reachable member.
For load-balanced virtual clusters, each Gateway 5 job is dispatched to the reachable member with the lowest outstanding job counter—the number of jobs Gateway Manager has sent to that member that haven’t yet responded. A single Platform workflow that makes multiple separate calls to Gateway 5 services sends each call as its own job, so a workflow can legitimately run different calls on different members. Each individual call still completes on the one member it was dispatched to.
Virtual clusters route new jobs away from an unreachable member automatically. If a member becomes unreachable while a job is running on it, that job doesn’t transfer to another member and must be resubmitted manually. Neither distribution type guarantees in-flight job recovery.
Member clusters
Virtual cluster members are always physical clusters registered in Gateway Manager. You can’t nest a virtual cluster inside another virtual cluster.
Every virtual cluster has one designated primary cluster and any number of additional clusters. For active/standby, additional clusters are backups in ordered failover sequence. For load balancing, all clusters—including the primary—serve traffic simultaneously; the primary/backup designation reflects configuration order but doesn’t affect distribution.
Service configuration and propagation
Services are configured on individual physical clusters using a configuration file (JSON or YAML) that defines decorators, repositories, and services. You can import or export a configuration at the virtual cluster level using the same actions available on physical clusters.
Importing to a virtual cluster propagates the configuration to all connected member clusters in one action. This is the recommended way to keep member services in sync. If the imported configuration contains resources that already exist on a member, the import won’t override them by default—use the Force option to overwrite existing resources.
Importing directly to a member cluster only affects that member—it does not propagate to other members in the virtual cluster. This is allowed and won’t cause errors, but it can create a service mismatch between members. If a mismatch occurs, the Failover Chain tab flags which services are missing on that member compared to the primary.
Exporting from a virtual cluster retrieves the configuration from the primary cluster only. Export when you want to capture the current state of the primary’s configuration to store, version, or use as the basis for a future import.
For procedures, see Import a gateway configuration and Export a gateway configuration.
RBAC on virtual clusters
Virtual clusters use the same RBAC model as physical clusters, including support for service groups. Access is scoped at the virtual cluster level—the virtual cluster is the permission boundary, not the individual physical clusters that make up its membership.
Granting a user group access to a virtual cluster gives those users implicit runtime access to all services on all member physical clusters. Admins are responsible for ensuring the member clusters and their registered services are appropriate for the user groups being granted virtual cluster access.
For details, see RBAC in Gateway Manager.
Northbound transparency
From the perspective of any platform feature that selects a cluster, virtual clusters and physical clusters are indistinguishable. Gateway Manager returns them in a single combined list. A workflow, integration, or other platform consumer selects a virtual cluster by name and receives results without any awareness of which physical member handled the job.