---
title: "Create a new virtual cluster"
method: POST
path: "/gateway_manager/v1/virtual-clusters"
tags: ["Gateway Manager"]
---

# Create a new virtual cluster

`POST /gateway_manager/v1/virtual-clusters`

## Request

- Base URL: `https://example.itential.io`
- URL: `https://example.itential.io/gateway_manager/v1/virtual-clusters`
- Auth: none declared

Creates a new virtual cluster that references registered physical clusters for primary and optional backup targets.

## Request body

- object
  - `virtualCluster` GatewayManagerV1VirtualClustersPostRequestBodyContentApplicationJsonSchemaVirtualCluster
    - `cluster_id` string, required: Unique cluster_id for the virtual cluster across all physical and virtual clusters
    - `description` string: Optional free text description
    - `enabled` boolean, required: Whether the virtual cluster is enabled
    - `readonly` boolean, required: Whether the virtual cluster is in readonly mode
    - `primary_cluster_id` string, required: The cluster_id of the primary physical cluster
    - `backup_cluster_ids` string[]: Ordered list of backup physical cluster IDs. Failover executes in array index order.
    - `groups` string[], required: An array of the names of the groups that will be associated with this virtual cluster. Any group that is associated with this virtual cluster will be able to take actions on it per the roles associated with that particular group

## Response `200`

Result of creating the virtual cluster

- GatewayManagerCreateVirtualClusterResponse200
  - `state` string
  - `id` string
  - `message` string

## Other responses

- `500`: Error response from API

## Changes

- **2026-10-31** `2095cc90e583`: 2 info
  - api tag `Gateway Manager` added
  - api tag `gatewayManager` removed

[Operation history](https://skmtc.dev/itential/apis/itential-2/changes/gateway_manager/v1/virtual-clusters/post.md)

---

[API](https://skmtc.dev/itential/apis/itential-2.md) - [All operations](https://skmtc.dev/itential/apis/itential-2/llms.txt) - [OpenAPI document](https://skmtc.dev/itential/apis/itential-2/revisions/2095cc90e583?raw)