> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/5/virtual-clusters/create-virtual-cluster/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Create a virtual cluster

Gateway Manager 1.2.3+

A virtual cluster groups physical gateway clusters under a single name and routes jobs across them automatically. When you create a virtual cluster, you choose a distribution type:

* **Active/Standby** — one cluster serves traffic while others stand by in ordered failover sequence. Use this for resilience against a cluster outage.
* **Load Balancing** — all clusters serve traffic simultaneously. Gateway Manager distributes each job to the member with the fewest active jobs. Use this for scale-out across many gateways or regions.

The creation flow is the same for both types. The **Distribution** field determines the type, and a live preview on the right updates as you configure the cluster.

## Prerequisites

* You have admin-level permissions in Gateway Manager. The `gateway:read` and `gateway:create` roles apply to virtual clusters—no separate virtual cluster roles are required.
* At least one physical cluster is registered in Gateway Manager.

## Create the virtual cluster

1. In Gateway Manager, select **Gateway Manager** from the left navigation.
2. Select **Add Gateway Cluster**.
3. In the **Cluster type** dropdown, select **Virtual Cluster**.
4. Enter a **Cluster ID**. This is how platform features identify and select this cluster—choose something that reflects the scope or purpose of the cluster group.
5. Optionally, enter a **Description**.
6. In the **Authorization group** field, assign an authorization group. A user must belong to this group and have the `gateway:read` role assigned to that group to access the virtual cluster.
7. In the **Distribution** dropdown, select the type:
   * **Active/Standby** — the preview panel on the right shows **Failover Chain (Preview)** and updates as you add clusters.
   * **Load Balancing** — the preview panel switches to **Cluster Pool (Preview)** with the label "Work is distributed across all connected clusters based on current load."
8. In the **Primary Physical Cluster** dropdown, select the physical cluster that should serve as the primary. For active/standby, this cluster serves traffic under normal conditions. For load balancing, this is the first active member.
9. To add additional clusters, select **Add Backup Cluster** and choose a physical cluster from the dropdown.
   * For active/standby, additional clusters are backups in ordered failover sequence—Gateway Manager attempts them top to bottom. Drag clusters to reorder them.
   * For load balancing, additional clusters are active members. Jobs are distributed across all reachable members simultaneously.
10. Select **Create Cluster**.

When you add a cluster to a virtual cluster that is already enabled, all users with access to the virtual cluster immediately gain implicit runtime access to the newly added cluster and its services. Verify that the cluster and its services are appropriate for all user groups assigned to this virtual cluster before saving.

## Enable the cluster

Newly created virtual clusters are **Disabled** by default and won't appear as available or form a connection until enabled. To enable the cluster:

1. Select the virtual cluster in the cluster list to open its detail view.
2. In the **Failover Chain** tab, toggle the cluster status to **Enabled**.
   Once enabled, the cluster appears as available to platform features and begins forming connections to its member clusters.

## Verify the cluster

After enabling, confirm the following in the cluster list:

* The **Status** column shows **Enabled**.
* The **Connection** column shows a connection indicator with a member count (for example, `◢ 2/3 Connected`).
* Selecting the cluster opens the detail view. The **Failover Chain** tab shows the primary and backup clusters in the correct configuration, with each member's connection status and last connected timestamp.

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.

## Best practices

**Verify service parity across member clusters.** The **Failover Chain** tab flags backup clusters that are missing services present on the primary with a warning indicator. Review these warnings before routing production traffic through the virtual cluster. Service matching uses name and type as the comparison key—it doesn't verify that services with the same name execute equivalent code. Confirm that services are functionally equivalent across all members.

**Keep member services in sync by importing at the virtual cluster level.** Importing a configuration on the virtual cluster propagates it to all member physical clusters in one action. Importing directly on an individual member cluster only affects that member and can create a service mismatch with the primary — if that happens, the **Failover Chain** tab flags which services are missing on that member. Export from the virtual cluster when you want to capture the primary cluster's current configuration to store or version. For procedures, see [Import a gateway configuration](../import-gateway-configuration) and [Export a gateway configuration](../export-gateway-configuration).

## Related topics

* [Virtual clusters overview](./overview)
* [Monitor virtual cluster status](./monitor-virtual-cluster-status)
* [Edit a virtual cluster](./edit-virtual-cluster)
* [RBAC in Gateway Manager](../rbac-gateway-manager)
* [Choose a deployment architecture](../choose-deployment-architecture)