---
title: "Get a Virtual Cluster"
method: GET
path: "/v1/event-gateways/{gatewayId}/virtual-clusters/{virtualClusterId}"
tags: ["Event Gateway Virtual Clusters"]
---

# Get a Virtual Cluster

`GET /v1/event-gateways/{gatewayId}/virtual-clusters/{virtualClusterId}`

Returns information about a specific virtual cluster associated with the Event Gateway.

## Response `200`

A single virtual cluster object.

- VirtualCluster — A representation of a Kafka cluster that maps to a backend cluster.
  - `id` string, uuid, required — The unique identifier of the virtual cluster.
  - `description` string — A human-readable description of the virtual cluster.
  - `destination` BackendClusterReference, required — The backend cluster associated with the virtual cluster.
    - `id` string, uuid, required — The unique identifier of the backend cluster.
    - `name` string, required — The unique name of the backend cluster.
  - `authentication` VirtualClusterAuthenticationSensitiveDataAwareScheme[], required — How to handle authentication from clients. It tries to authenticate with every rule sequentially one by one. It succeeds on the first match, and fails if no rule matches.
    - union
      - VirtualClusterAuthenticationAnonymous
        - `type` 'anonymous', required
      - VirtualClusterAuthenticationSaslPlainSensitiveDataAware — SASL/PLAIN authentication scheme for the virtual cluster.
        - `type` 'sasl_plain', required
        - `mediation` 'passthrough' | 'terminate', required — The mediation type for SASL/PLAIN authentication.
        - `principals` VirtualClusterAuthenticationPrincipalSensitiveDataAware[] — List of principals to be able to authenticate with, used with `terminate` mediation.
          - `username` string, required — A literal value or a reference to an existing secret as a template string expression. The value is stored and returned by the API as-is, not treated as sensitive information.
          - `password` string — A sensitive value containing the secret or a reference to a secret as a template string expression. If the value is provided as plain text, it is encrypted at rest and omitted from API responses. If provided as an expression, the expression itself is stored and returned by the API.
        - `fetch_kong_identity_principal` FetchKongIdentityPrincipal — Fetches principal metadata from Kong Identity after successful authentication. The principal is looked up by a custom key matched against the authenticated identity. **Requires a minimum runtime version of `1.2`**.
          - `directory` string, required — Kong Identity directory to use for principal lookup.
          - `fetch_by` FetchKongIdentityPrincipalFetchBy, required — Defines how to look up the principal in Kong Identity. **Requires a minimum runtime version of `1.2`**.
            - `key` string, required — The metadata key in Kong Identity to match the authenticated identity against. Value for the lookup is a `username` in case of `sasl_plain` or `sasl_scram`. In case of `client_certificate` it's a principal mapped by the listener TLSServer policy.
          - `failure_mode` 'error' | 'ignore', required — Behavior when the Kong Identity principal lookup fails. * `error` - fail the authentication if the principal lookup fails. * `ignore` - proceed without principal metadata if the lookup fails. **Requires a minimum runtime version of `1.2`**.
      - VirtualClusterAuthenticationSaslScram — SASL/SCRAM authentication scheme for the virtual cluster.
        - `type` 'sasl_scram', required
        - `algorithm` 'sha256' | 'sha512', required — The algorithm used for SASL/SCRAM authentication.
        - `fetch_kong_identity_principal` FetchKongIdentityPrincipal — Fetches principal metadata from Kong Identity after successful authentication. The principal is looked up by a custom key matched against the authenticated identity. **Requires a minimum runtime version of `1.2`**.
          - `directory` string, required — Kong Identity directory to use for principal lookup.
          - `fetch_by` FetchKongIdentityPrincipalFetchBy, required — Defines how to look up the principal in Kong Identity. **Requires a minimum runtime version of `1.2`**.
            - `key` string, required — The metadata key in Kong Identity to match the authenticated identity against. Value for the lookup is a `username` in case of `sasl_plain` or `sasl_scram`. In case of `client_certificate` it's a principal mapped by the listener TLSServer policy.
          - `failure_mode` 'error' | 'ignore', required — Behavior when the Kong Identity principal lookup fails. * `error` - fail the authentication if the principal lookup fails. * `ignore` - proceed without principal metadata if the lookup fails. **Requires a minimum runtime version of `1.2`**.
      - VirtualClusterAuthenticationOauthBearer — Oauth Bearer authentication scheme for the virtual cluster.
        - `type` 'oauth_bearer', required
        - `mediation` 'passthrough' | 'validate_forward' | 'terminate', required — Methods to mediate authentication: * passthrough - pass authentication from the client through proxy to the backend cluster without any kind of validation * validate_forward - pass authentication from the client through proxy to the backend cluster. Proxy does the validation before forwarding it to the client. * terminate - terminate authentication at the proxy level and originate authentication to the backend cluster using the configuration defined at BackendCluster's authentication. SASL auth is not originated if authentication on the backend_cluster is not configured.
        - `claims_mapping` VirtualClusterAuthenticationClaimsMapping — Maps JWT claims in the case when sub and scope are presented as different claims in your JWT token.
          - `sub` string — Maps the subject claim.
          - `scope` string — Maps the scope claim.
        - `jwks` VirtualClusterAuthenticationJWKS — JSON Web Key Set configuration for verifying token signatures.
          - `endpoint` string, uri, required — URL for JWKS endpoint.
          - `timeout` string — Total time from establishing connection to receive a response from JWKS endpoint.
          - `cache_expiration` string — Duration after which the gateway will fetch and cache JWKS.
        - `validate` VirtualClusterAuthenticationValidate — Validation rules.
          - `audiences` VirtualClusterAuthenticationAudience[] — List of expected audience values. One of them has to match the audience claim in the token.
            - `name` string, required
          - `issuer` string — Expected token issuer in the token.
        - `fetch_kong_identity_principal` FetchKongIdentityPrincipalOauthBearer — Fetches principal metadata from Kong Identity after successful OAUTHBEARER authentication. The principal is looked up by the iss and sub claims from the JWT token. **Requires a minimum runtime version of `1.2`**.
          - `directory` string, required — Kong Identity directory to use for principal lookup.
          - `failure_mode` 'error' | 'ignore', required — Behavior when the Kong Identity principal lookup fails. * `error` - fail the authentication if the principal lookup fails. * `ignore` - proceed without principal metadata if the lookup fails. **Requires a minimum runtime version of `1.2`**.
      - VirtualClusterAuthenticationClientCertificate — Client certificate (mTLS) authentication scheme for the virtual cluster. **Requires a minimum runtime version of `1.1`**.
        - `type` 'client_certificate', required
        - `fetch_kong_identity_principal` FetchKongIdentityPrincipal — Fetches principal metadata from Kong Identity after successful authentication. The principal is looked up by a custom key matched against the authenticated identity. **Requires a minimum runtime version of `1.2`**.
          - `directory` string, required — Kong Identity directory to use for principal lookup.
          - `fetch_by` FetchKongIdentityPrincipalFetchBy, required — Defines how to look up the principal in Kong Identity. **Requires a minimum runtime version of `1.2`**.
            - `key` string, required — The metadata key in Kong Identity to match the authenticated identity against. Value for the lookup is a `username` in case of `sasl_plain` or `sasl_scram`. In case of `client_certificate` it's a principal mapped by the listener TLSServer policy.
          - `failure_mode` 'error' | 'ignore', required — Behavior when the Kong Identity principal lookup fails. * `error` - fail the authentication if the principal lookup fails. * `ignore` - proceed without principal metadata if the lookup fails. **Requires a minimum runtime version of `1.2`**.
  - `namespace` VirtualClusterNamespace — Namespace allows to implement multitenancy using a single backend cluster. It allows to either hide or enforce a static prefix on resources (topics, consumer group IDs, transaction IDs).
    - `mode` 'hide_prefix' | 'enforce_prefix', required — * hide_prefix - the configured prefix is hidden from clients for topics and IDs when reading. Created resources are written with the prefix on the backend cluster. * enforce_prefix - the configured prefix remains visible to clients. Created resources must include the prefix or the request will fail.
    - `prefix` string, required — The namespace is differentiated by this chosen prefix. For example, if the prefix is set to "analytics_" the topic named "analytics_user_clicks" is available to the clients of the virtual cluster. Topics without the prefix will be ignored unless added via `additional.topics`.
    - `additional` VirtualClusterNamespaceAdditionalProperties
      - `topics` VirtualClusterNamespaceTopicSelector[] — Additional backend topics to expose even if they don't match the namespace prefix. The topics are not affected by the hide/enforce prefix mode. If the client tries to create a topic that matches this list, the request is rejected.
        - union
          - object
            - `type` 'glob', required
            - `glob` string, glob, required — Expose any backend topic that matches this glob pattern (e.g., `operations_data_*`).
            - `conflict` 'warn' | 'ignore' — How to inform the user about conflicts where multiple backend topics would map to the same virtual topic name. * warn - log in the Event Gateway logs. Additionally, it sets knep_namespace_topic_conflict to 1. * ignore - do not do anything. It does not cause knep_namespace_topic_conflict metric to be set to 1.
          - object
            - `type` 'exact_list', required
            - `exact_list` NamespaceExactAllowListItem[] — Explicit allow-list of backend topic names.
              - …
            - `conflict` 'warn' | 'ignore' — How to inform the user about conflicts where multiple backend topics would map to the same virtual topic name. * warn - log in the Event Gateway logs. Additionally, it sets knep_namespace_topic_conflict to 1. * ignore - do not do anything. It does not cause knep_namespace_topic_conflict metric to be set to 1.
      - `consumer_groups` VirtualClusterNamespaceIdSelector[] — Consumer group IDs to expose even if they don't start with the namespace prefix.
        - union
          - object
            - `type` 'glob', required
            - `glob` string, glob, required — Expose any id that matches this glob pattern (e.g., `my_id_*`).
          - object
            - `type` 'exact_list', required
            - `exact_list` object[]
              - …
  - `topic_aliases` VirtualClusterTopicAlias[] — Topic aliases allow exposing backend topics under additional names. An alias creates a new entry point to the same physical data. The alias `topic` field references namespace-visible names (if namespace is configured). Aliases are independent of namespace and can be used without it. **Requires a minimum runtime version of `1.2`**.
    - `alias` string, required — The client-visible topic name.
    - `topic` string, required — The namespace-visible topic name this alias resolves to.
    - `condition` string — CEL expression evaluated against the connection's auth context. If omitted or empty, the alias is active for all connections.
    - `conflict` 'warn' | 'ignore' — How to handle conflicts where an alias shadows a physical topic. * warn - activate the alias but log a warning and set the conflict metric to 1. * ignore - activate the alias silently.
  - `name` string, required — The name of the virtual cluster.
  - `dns_label` string, required — The DNS label used in the bootstrap server URL to identify the virtual cluster when using SNI routing. The format follows the RFC1035: 1-63 chars, lowercase alphanumeric or '-', must start and end with an alphanumeric character.
  - `acl_mode` 'enforce_on_gateway' | 'passthrough', required — Configures whether or not ACL policies are enforced on the gateway. - `enforce_on_gateway` means the gateway enforces its own ACL policies for this virtual cluster and does not forward ACL-related commands to the backend cluster. Note that if there are no ACL policies configured, all access is denied. - `passthrough` tells the gateway to forward all ACL-related commands.
  - `labels` Labels — Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_".
  - `created_at` string, date-time, required — An ISO-8601 timestamp representation of entity creation date.
  - `updated_at` string, date-time, required — An ISO-8601 timestamp representation of entity update date.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found

---

[API](https://skmtc.net/kong/apis/konnect-api-go-sdk.md) · [All operations](https://skmtc.net/kong/apis/konnect-api-go-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kong/konnect-api-go-sdk/versions/f920f418f552/schema)