---
title: "PUT /gateway/v2/virtual-cluster"
method: PUT
path: "/gateway/v2/virtual-cluster"
tags: ["cli_virtual-cluster_gateway_v2_7"]
---

# PUT /gateway/v2/virtual-cluster

`PUT /gateway/v2/virtual-cluster`

## Request

- Base URL: `https://developers.conduktor.io` (the document declares no server; this is the origin it was published from)
- URL: `https://developers.conduktor.io/gateway/v2/virtual-cluster`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/conduktor/apis/conduktor-gateway-api/docs/gateway/v2/virtual-cluster/put.ts> (a function with typed inputs; its response is checked against the schema)

[![Generally Available](https://img.shields.io/badge/Lifecycle-Generally%20Available-blue)](#tag/Versioning)

Upsert a virtual cluster

## Query parameters

- `dryMode` boolean

## Request body

- VirtualCluster
  - `kind` string, required: The kind of the virtual cluster
  - `apiVersion` string, required: The api version of the virtual cluster
  - `metadata` VirtualClusterMetadata, required: Metadata of the virtual cluster
    - `name` string, ^[a-zA-Z0-9._-]+$, required: The name of the virtual cluster
  - `spec` VirtualClusterSpec, required: Spec of the virtual cluster
    - `aclEnabled` boolean: Enable ACL checks on all Kafka API calls to this virtual cluster. Depending on the value of the `aclMode` field, acls are required to be set in different ways. See the `aclMode` field for more details.
    - `aclMode` string: Different `aclMode` values control how ACLs will be managed on the virtual cluster - `KAFKA_API` : ACLs must be managed by the Kafka API as if the virtual cluster is a standard Kafka cluster. Forbids `acls` field from being set. - `REST_API` : ACLs must be managed by this resource on the REST API using the `acls` field. Requires `acls` list to be non-empty and `superUsers` must not be set. If `aclMode` is left unset the behaviour is different depending on the value of the `aclEnabled` field - `aclEnabled: true` : The system will assume a default `aclMode` of `KAFKA_API` - `aclEnabled: false` : The `aclMode` is left unset and can be set in the future by the user or the system. Forbids `acls` and `superUsers` from being set. Once `aclMode` is set (either by the user or the system) changing it is forbidden.
    - `superUsers` string[]: List of usernames for which the associated service accounts in this virtual cluster can bypass ACLs. - Must be set if the `aclMode` field is set to `KAFKA_API`. - Cannot be set if the `aclMode` field is set to `REST_API`. - The service accounts referenced by username must be managed independently using the REST Service-Account API.
    - `type` string: The type of the virtual cluster : Standard, Partner
    - `bootstrapServers` string: The bootstrap servers to create a connection to the virtual cluster. This field is automatically managed by the gateway
    - `clientProperties` MapGatewayAuthenticationModeV: Depending on gateway config, different kind of authentication can be used: - `MTLS` : Both client and server use TLS certificates to authenticate each other. - `PLAIN` : The client uses a token generated by the gateway to authenticate (connection can be either SSL or PLAINTEXT). - `OAUTHBEARER` : The client uses an OIDC token generated by the gateway to authenticate (connection can be either SSL or PLAINTEXT). ClientProperties is a dictionary mapping supported authentication modes to their respective properties. It contains placeholders to replace with your actual values: {{username}}, {{password}}, etc.
    - `acls` AclBinding[]: List of ACL bindings for the virtual cluster. - Must be set if the `aclMode` field is set to `REST_API`. - Cannot be set if `aclMode` field is set to `KAFKA_API`. - No validation will be done on the content of the acls (eg existence of users/topics etc)
      - `resourcePattern` ResourcePattern, required
        - `resourceType` 'ANY' | 'CLUSTER' | 'DELEGATION_TOKEN' | 'GROUP' | 'TOPIC' | 'TRANSACTIONAL_ID' | 'UNKNOWN', required
        - `name` string, required: The name or pattern matching the name associated with the resource. - Exactly maps onto the resource name on the Java API - Full examples might include the name of a user, topic, cluster or consumer group - Wildcards (ie `*`) are supported
        - `patternType` 'ANY' | 'LITERAL' | 'MATCH' | 'PREFIXED' | 'UNKNOWN', required
      - `principal` string, required: Who or what the ACL applies to. - Exactly maps onto the principal on the Java API - Examples might include `User:alice` or `User:*` (wildcard for all users)
      - `host` string, required
      - `operation` 'ALL' | 'ALTER' | 'ALTER_CONFIGS' | 'ANY' | 'CLUSTER_ACTION' | 'CREATE' | 'CREATE_TOKENS' | 'DELETE' | 'DESCRIBE' | 'DESCRIBE_CONFIGS' | 'DESCRIBE_TOKENS' | 'IDEMPOTENT_WRITE' | 'READ' | 'UNKNOWN' | 'WRITE', required
      - `permissionType` 'ALLOW' | 'DENY', required

## Response `200`

- ApplyResultVirtualCluster
  - `resource` VirtualCluster, required
    - `kind` string, required: The kind of the virtual cluster
    - `apiVersion` string, required: The api version of the virtual cluster
    - `metadata` VirtualClusterMetadata, required: Metadata of the virtual cluster
      - `name` string, ^[a-zA-Z0-9._-]+$, required: The name of the virtual cluster
    - `spec` VirtualClusterSpec, required: Spec of the virtual cluster
      - `aclEnabled` boolean: Enable ACL checks on all Kafka API calls to this virtual cluster. Depending on the value of the `aclMode` field, acls are required to be set in different ways. See the `aclMode` field for more details.
      - `aclMode` string: Different `aclMode` values control how ACLs will be managed on the virtual cluster - `KAFKA_API` : ACLs must be managed by the Kafka API as if the virtual cluster is a standard Kafka cluster. Forbids `acls` field from being set. - `REST_API` : ACLs must be managed by this resource on the REST API using the `acls` field. Requires `acls` list to be non-empty and `superUsers` must not be set. If `aclMode` is left unset the behaviour is different depending on the value of the `aclEnabled` field - `aclEnabled: true` : The system will assume a default `aclMode` of `KAFKA_API` - `aclEnabled: false` : The `aclMode` is left unset and can be set in the future by the user or the system. Forbids `acls` and `superUsers` from being set. Once `aclMode` is set (either by the user or the system) changing it is forbidden.
      - `superUsers` string[]: List of usernames for which the associated service accounts in this virtual cluster can bypass ACLs. - Must be set if the `aclMode` field is set to `KAFKA_API`. - Cannot be set if the `aclMode` field is set to `REST_API`. - The service accounts referenced by username must be managed independently using the REST Service-Account API.
      - `type` string: The type of the virtual cluster : Standard, Partner
      - `bootstrapServers` string: The bootstrap servers to create a connection to the virtual cluster. This field is automatically managed by the gateway
      - `clientProperties` MapGatewayAuthenticationModeV: Depending on gateway config, different kind of authentication can be used: - `MTLS` : Both client and server use TLS certificates to authenticate each other. - `PLAIN` : The client uses a token generated by the gateway to authenticate (connection can be either SSL or PLAINTEXT). - `OAUTHBEARER` : The client uses an OIDC token generated by the gateway to authenticate (connection can be either SSL or PLAINTEXT). ClientProperties is a dictionary mapping supported authentication modes to their respective properties. It contains placeholders to replace with your actual values: {{username}}, {{password}}, etc.
      - `acls` AclBinding[]: List of ACL bindings for the virtual cluster. - Must be set if the `aclMode` field is set to `REST_API`. - Cannot be set if `aclMode` field is set to `KAFKA_API`. - No validation will be done on the content of the acls (eg existence of users/topics etc)
        - `resourcePattern` ResourcePattern, required
          - `resourceType` 'ANY' | 'CLUSTER' | 'DELEGATION_TOKEN' | 'GROUP' | 'TOPIC' | 'TRANSACTIONAL_ID' | 'UNKNOWN', required
          - `name` string, required: The name or pattern matching the name associated with the resource. - Exactly maps onto the resource name on the Java API - Full examples might include the name of a user, topic, cluster or consumer group - Wildcards (ie `*`) are supported
          - `patternType` 'ANY' | 'LITERAL' | 'MATCH' | 'PREFIXED' | 'UNKNOWN', required
        - `principal` string, required: Who or what the ACL applies to. - Exactly maps onto the principal on the Java API - Examples might include `User:alice` or `User:*` (wildcard for all users)
        - `host` string, required
        - `operation` 'ALL' | 'ALTER' | 'ALTER_CONFIGS' | 'ANY' | 'CLUSTER_ACTION' | 'CREATE' | 'CREATE_TOKENS' | 'DELETE' | 'DESCRIBE' | 'DESCRIBE_CONFIGS' | 'DESCRIBE_TOKENS' | 'IDEMPOTENT_WRITE' | 'READ' | 'UNKNOWN' | 'WRITE', required
        - `permissionType` 'ALLOW' | 'DENY', required
  - `upsertResult` 'Created' | 'NotChanged' | 'Updated', required: The result of the upsert operation (created, updated, not changed)

## Other responses

- `400`: The request is not valid
- `401`: The given credentials are not valid
- `403`: The required feature is not included in the current license
- `409`: Cannot change prefix or type of an existing virtual cluster
- `500`: An unexpected error occurred in the server

---

[API](https://skmtc.dev/conduktor/apis/conduktor-gateway-api.md) - [All operations](https://skmtc.dev/conduktor/apis/conduktor-gateway-api/llms.txt) - [OpenAPI document](https://skmtc.dev/conduktor/apis/conduktor-gateway-api/revisions/73ad742aa630?raw)