---
title: "Forward to Virtual Cluster"
url: "https://nov18-dev.movespot.fyi/apis/konnect-control-planes-configuration-for-event-gateways-1/versions/f4366232-3186-4be9-93bd-be3e4b16fb19/schemas/ForwardToVirtualClusterPolicy"
---

> Full API specification: https://nov18-dev.movespot.fyi/apis/konnect-control-planes-configuration-for-event-gateways-1/versions/f4366232-3186-4be9-93bd-be3e4b16fb19.md

# Forward to Virtual Cluster

Forwards requests to virtual clusters configured with port routing or SNI routing. While there can be multiple of these policies configured on a listener, there can only be one instance of `port_mapping`. When multiple policies are configured, the first one that matches the connection is used. If no policy matches, the connection is rejected. When using `port_mapping`, there must be a mapping port for each broker on the backend cluster see `ForwardToClusterBySNIConfig` for more details.

## OpenAPI definition

```yaml
openapi: 3.0.0
info:
  title: Konnect Control Planes Configuration for Event Gateways
  version: 1.0.0
servers:
  - url: https://us.api.konghq.com/v1
    description: United-States Production region
  - url: https://eu.api.konghq.com/v1
    description: Europe Production region
  - url: https://au.api.konghq.com/v1
    description: Australia Production region
  - url: https://me.api.konghq.com/v1
    description: Middle-East Production region
  - url: https://in.api.konghq.com/v1
    description: India Production region
  - url: https://sg.api.konghq.com/v1
    description: Singapore Production region
components:
  schemas:
    Labels:
      description: >
        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 "_".
      type: object
      example:
        env: test
      additionalProperties:
        type: string
        pattern: ^[a-z0-9A-Z]{1}([a-z0-9A-Z-._]*[a-z0-9A-Z]+)?$
        minLength: 1
        maxLength: 63
      maxProperties: 50
      title: Labels
    ForwardToClusterBySNIConfig:
      description: >
        The configuration to forward requests to virtual clusters configured
        with SNI routing.
      type: object
      properties:
        type:
          type: string
          enum:
            - sni
          x-terraform-transform-const: true
        sni_suffix:
          description: >
            Optional suffix for TLS SNI validation.


            This suffix is concatenated with the virtual cluster "dns.label"
            label to form the base name for the SNI.

            If not provided, the virtual cluster "dns.label" label alone is used
            as the base name for the SNI.

            For example with sni_suffix: `.example.com` and virtual cluster
            "dns.label" label: `my-cluster`,

            the SNI suffix for it is `my-cluster.example.com`.

            If "dns.label" label is absent on the virtual cluster, the traffic
            won't be routed there.


            The bootstrap host is `bootstrap.my-cluster.example.com` and then
            each broker is addressable at `broker-0.my-cluster.example.com`,
            `broker-1.my-cluster.example.com`, etc.

            This means that your deployment needs to have a wildcard certificate
            for the domain and a DNS resolver that routes
            `*.my-cluster.example.com` to the proxy.


            The accepted format is a DNS subdomain starting with either `.` or
            `-`. For example, `-keg.example.com`, `.keg.example.com`,
            `.namespace.svc.cluster.local`, and `.localhost` are all valid,

            while `keg.example.com` is not.
          type: string
          example: .example.com
          pattern: ^[\.-]([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)*([a-z0-9-]*[a-z0-9])$
        advertised_port:
          description: >
            Virtual brokers are advertised to clients with this port instead of
            listen_port. Useful when proxy is

            behind loadbalancer listening on different port.
          type: integer
          maximum: 65535
          minimum: 1
        broker_host_format:
          description: >-
            Configures DNS names assigned to brokers in virtual clusters.


            - `per_cluster_suffix` is the default and allocates one level in the
            hierarchy for virtual clusters:
            `broker-{node_id}.{virtual_cluster}.{sni_suffix}`

            - `shared_suffix` puts all brokers from every virtual clusters into
            the same level: `broker-{node_id}-{virtual_cluster}.{sni_suffix}`.
            This makes it easier to manage certificates for this listener.


            **Requires a minimum runtime version of `1.1`**.
          type: object
          properties:
            type:
              type: string
              default: per_cluster_suffix
              enum:
                - per_cluster_suffix
                - shared_suffix
          required:
            - type
          x-min-runtime-version: "1.1"
      additionalProperties: false
      required:
        - type
    ForwardToClusterByPortMappingConfig:
      description: >
        The configuration to forward request to `destination` and rewrite ports
        accordingly.

        All broker ids must fit in the range of ports defined in the listener,
        if it doesn't the metadata request will

        return an error.


        For example with ports: [9000, "9092-9094", "9100"] and `bootstrap_port:
        at_start` and brokers with ids

        1, 2, 3, 4 we will map: bootstrap to 9000 broker 1 to 9001, broker 2 to
        9002, broker 3 to 9003, and broker 4

        to 9004 and fail the metadata request as these ports are not open.


        However, with the same configuration but with brokers with ids:
        92,93,94,100 we will map: bootstrap to 9000,

        broker 92 to 9092, broker 93 to 9093, broker 94 to 9094, and broker 100
        to 9100.


        In most cases users should use a single range `["9090-9094"] ` and
        `bootstrap_port: at_start` and connect with

        `<host>:9090` as bootstrap server. Being able to use multiple ranges is
        only useful when when dealing with

        gaps in broker ids.


        It is strongly discouraged to use port mapping in production.
      type: object
      properties:
        type:
          type: string
          enum:
            - port_mapping
          x-terraform-transform-const: true
        destination:
          $ref: "#/components/schemas/VirtualClusterReference"
        advertised_host:
          description: Virtual brokers are advertised to clients using this host. Any kind
            of host supported by kafka can be used. If not defined, it's
            listen_address. If listen_address is `0.0.0.0` it's the destination
            IP of the TCP connection.
          type: string
          pattern: ^[a-z0-9](?:[a-z0-9\-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9\-]{0,61}[a-z0-9])?)*$
        bootstrap_port:
          description: >
            If set to `at_start`, the first port will be used as a bootstrap
            port.

            It provides a stable endpoint to use as the bootstrap server for
            clients, regardless of broker

            IDs in the cluster.


            Additionally, it offsets all ports by one, so for example, if there
            are 3 brokers (id=1, id=2, id=3)

            then we will use 4 ports: 9092 (bootstrap), 9093 (id=1), 9094
            (id=2), 9095 (id=3)

            With `none` we will use 3 ports: 9092 (id=1), 9093 (id=2), 9094
            (id=3).
          type: string
          default: at_start
          enum:
            - none
            - at_start
        min_broker_id:
          description: The lowest broker node ID in the cluster.
          type: integer
          default: 0
      additionalProperties: false
      required:
        - type
        - destination
        - advertised_host
    VirtualClusterReference:
      description: A reference to a virtual cluster.
      anyOf:
        - $ref: "#/components/schemas/VirtualClusterReferenceById"
        - $ref: "#/components/schemas/VirtualClusterReferenceByName"
      x-terraform-preferred: "#/components/schemas/VirtualClusterReferenceById"
    VirtualClusterReferenceById:
      description: Reference a virtual cluster by its unique identifier.
      type: object
      properties:
        id:
          description: The unique identifier of the virtual cluster.
          type: string
          format: uuid
          minLength: 1
      required:
        - id
    VirtualClusterReferenceByName:
      description: Reference a virtual cluster by its unique name.
      type: object
      properties:
        name:
          $ref: "#/components/schemas/VirtualClusterName"
      required:
        - name
    VirtualClusterName:
      description: The name of the virtual cluster.
      type: string
      maxLength: 255
      minLength: 1
      x-unicode-pattern: ^[\p{L}\p{N}][\p{L}\p{N} _\-\.:/+']*[\p{L}\p{N}]$
    ForwardToVirtualClusterPolicy:
      description: >
        Forwards requests to virtual clusters configured with port routing or
        SNI routing.

        While there can be multiple of these policies configured on a listener,
        there can only be one instance of

        `port_mapping`.

        When multiple policies are configured, the first one that matches the
        connection is used.

        If no policy matches, the connection is rejected.


        When using `port_mapping`, there must be a mapping port for each broker
        on the backend cluster see

        `ForwardToClusterBySNIConfig` for more details.
      type: object
      properties:
        type:
          description: The type name of the policy.
          type: string
          enum:
            - forward_to_virtual_cluster
          maxLength: 255
          minLength: 1
          x-terraform-transform-const: true
        name:
          description: A unique user-defined name of the policy.
          type: string
          maxLength: 255
          x-unicode-pattern: ^[\p{L}\p{N}][\p{L}\p{N} _\-\.:/+']*[\p{L}\p{N}]$
        description:
          description: A human-readable description of the policy.
          type: string
          default: ""
          maxLength: 512
        enabled:
          description: Whether the policy is enabled.
          type: boolean
          default: true
        labels:
          $ref: "#/components/schemas/Labels"
        config:
          description: The configuration of the policy.
          type: object
          discriminator:
            propertyName: type
            mapping:
              port_mapping: "#/components/schemas/ForwardToClusterByPortMappingConfig"
              sni: "#/components/schemas/ForwardToClusterBySNIConfig"
          oneOf:
            - $ref: "#/components/schemas/ForwardToClusterBySNIConfig"
            - $ref: "#/components/schemas/ForwardToClusterByPortMappingConfig"
      required:
        - type
        - config
      title: Forward to Virtual Cluster
```
