Itential GatewayVirtual clusters

Create a virtual cluster

Gateway Manager 1.2.2+

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 and Export a gateway configuration.