You are browsing documentation for an older version. See the latest documentation here.

MeshGatewayRoute

MeshGatewayRoute is a policy used to configure Kong Mesh’s builtin gateway. It is used in combination with MeshGateway.

MeshGatewayRoute is a Kong Mesh dataplane policy that replaces TrafficRoute for Kong Mesh Gateway. It configures how a gateway should process network traffic. At the moment, it targets HTTP routing use cases. MeshGatewayRoutes are attached to gateways by matching their selector to the MeshGateway listener tags. This requires the kuma.io/service tag and, optionally, additional tags to match specific MeshGateway listeners.

The following MeshGatewayRoute routes traffic to the backend service and attaches to any listeners tagged with vhost=foo.example.com that attach to builtin gateways with kuma.io/service: edge-gateway.

Universal

Kubernetes

type: MeshGatewayRoute
mesh: default
name: foo.example.com-backend 
selectors:
- match:
    kuma.io/service: edge-gateway
    vhost: foo.example.com
conf:
  http:
    rules:
      - matches:
          - path:
              match: PREFIX
              value: /
        backends:
          - destination:
              kuma.io/service: backend

apiVersion: kuma.io/v1alpha1
kind: MeshGatewayRoute
mesh: default
metadata:
  name: foo.example.com-backend
spec:
  selectors:
    - match:
        kuma.io/service: edge-gateway
        vhost: foo.example.com
  conf:
    http:
      rules:
        - matches:
            - path:
                match: PREFIX
                value: /
          backends:
            - destination:
                kuma.io/service: backend

Listener tags

When Kong Mesh binds a MeshGatewayRoute to a MeshGateway, careful specification of tags lets you control whether the MeshGatewayRoute will bind to one or more of the listeners declared on the MeshGateway.

Each listener stanza on a MeshGateway has a set of tags; Kong Mesh creates the listener tags by combining these tags with the tags from the underlying builtin gateway Dataplane. A selector that matches only on the kuma.io/service tag will bind to all listeners on the MeshGateway, but a selector that includes listener tags will only bind to matching listeners. One application of this mechanism is to inject standard routes into all virtual hosts, without the need to modify MeshGatewayRoutes that configure specific applications.

Matching

MeshGatewayRoute allows HTTP requests to be matched by various criteria (for example uri path, HTTP headers). When Kong Mesh generates the final Envoy configuration for a builtin gateway Dataplane, it combines all the matching MeshGatewayRoutes into a single set of routing tables, partitioned by the virtual hostname, which is specified either in the MeshGateway listener or in the MeshGatewayRoute.

Kong Mesh sorts the rules in each table by specificity, so that routes with more specific match criteria are always ordered first. For example, a rule that matches on a HTTP header and a path is more specific than one that matches only on path, and the longest match path will be considered more specific. This ordering allows Kong Mesh to combine routing rules from multiple MeshGatewayRoute resources and still produce predictable results.

Filters

Every rule can include filters that further modifies requests. For example, by modifying headers and mirroring, redirecting, or rewriting requests.

For example, the following filters match /prefix, trim it from the path and set the Host header:

...
        - matches:
          - path:
              match: PREFIX
              value: /prefix/
          backends:
          - destination:
              kuma.io/service: backend
          filters:
          - requestHeader:
              set:
              - name: Host
                value: test.com
          - rewrite:
              replacePrefixMatch: "/"

Reference

$schema: http://json-schema.org/draft-04/schema#

$ref: #/definitions/MeshGatewayRoute

definitions

MeshGatewayRoute

## Mesh Gateway Route
Type: object
This schema accepts additional properties.
Properties
- selectors
  - Selectors is used to match this resource to MeshGateway listener.
  - Type: array
    - Items
    - $ref: #/definitions/kuma.mesh.v1alpha1.Selector
- conf
  - Conf specifies the route configuration.
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.Conf
  - This schema accepts additional properties.
  - Properties kuma.mesh.v1alpha1.MeshGatewayRoute.Backend
## Backend
Backend selects a target for HTTP request forwarding.
Type: object
This schema accepts additional properties.
Properties
- weight
  - Weight is the proportion of requests this backend will receive when a forwarding rules specifies multiple backends. Traffic weight is computed as "weight/sum(all weights)". A weight of 0 means that the destination will be ignored.
  - Type: integer
- destination
  - Destination is a selector to match the individual endpoints to which the gateway will forward.
  - Type: object
  - This schema accepts additional properties.
  - Properties kuma.mesh.v1alpha1.MeshGatewayRoute.Conf
## Conf
Type: object
This schema accepts additional properties.
Properties
- tcp
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.TcpRoute
  - This schema accepts additional properties.
  - Properties
- http
  - #### TlsRoute tls = 3;
  - TlsRoute tls = 3;
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute
  - This schema accepts additional properties.
  - Properties kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute
## Http Route
HTTP routes are valid for listeners that accept HTTP/1.1 and HTTP/2 over both TCP and TLS.
Type: object
This schema accepts additional properties.
Properties
- hostnames
  - Hostnames lists the server names for which this route is valid. The hostnames are matched against the TLS Server Name Indication extension if this is a TLS session. They are also matched against the HTTP host (authority) header in the client's HTTP request.
  - Type: array
    - Items
    - Type: string
- rules
  - Rules specifies how the gateway should match and process HTTP requests.
  - Type: array
    - Items
    - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Rule kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter
## Filter
Type: object
This schema accepts additional properties.
Properties
- request_header
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter.HeaderFilter
  - This schema accepts additional properties.
  - Properties
- mirror
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter.Mirror
  - This schema accepts additional properties.
  - Properties
- redirect
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter.Redirect
  - This schema accepts additional properties.
  - Properties
- rewrite
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter.Rewrite
  - This schema accepts additional properties.
  - Properties
- response_header
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter.HeaderFilter
  - This schema accepts additional properties.
  - Properties kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter.HeaderFilter
## Header Filter
Type: object
This schema accepts additional properties.
Properties
- set
  - Type: array
    - Items
    - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter.HeaderFilter.Header
- add
  - Type: array
    - Items
    - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter.HeaderFilter.Header
- remove
  - Type: array
    - Items
    - Type: string kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter.HeaderFilter.Header
## Header
Type: object
This schema accepts additional properties.
Properties
- name
  - Type: string
- value
  - Type: string kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter.Mirror
## Mirror
The mirror filter sends a percentage of HTTP requests to the given backend. The gateway ignores any responses to these requests.
Type: object
This schema accepts additional properties.
Properties
- backend
  - Backend denotes the service to which requests will be mirrored. The "weight" field must not be given.
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.Backend
  - This schema accepts additional properties.
  - Properties
- percentage
  - Percentage specifies the percentage of requests to mirror to the backend (in the range 0.0 - 100.0, inclusive).
  - Type: number kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter.Redirect
## Redirect
The redirect filter responds to the HTTP request immediately, without forwarding it to any backend. The response is a HTTP redirect message.
Type: object
This schema accepts additional properties.
Properties
- scheme
  - The scheme for the redirect URL. Usually "http" or "https".
  - Type: string
- hostname
  - The hostname to redirect to.
  - Type: string
- port
  - The port to redirect to.
  - Type: integer
- status_code
  - The HTTP response status code. This must be in the range 300 - 308.
  - Type: integer
- path
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter.Rewrite
  - This schema accepts additional properties.
  - Properties kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter.Rewrite
## Rewrite
Type: object
This schema accepts additional properties.
Properties
- replace_full
  - Type: string
- replaceprefixmatch
  - Note that rewriting "/prefix" to "/" will do the right thing: - the path "/prefix" is rewritten to "/" - the path "/prefix/rest" is rewritten to "/rest"
  - Type: string
- hosttobackend_hostname
  - Option to indicate that during forwarding, the host header should be swapped with the hostname of the upstream host chosen by the Envoy's cluster manager. BE AWARE: - it's mutually exclusive with request_header filter which explicitly replaces "host" header
  - Type: boolean kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Match
## Match
Match specifies the criteria for when a HTTP request matches a rule. The match is only considered successful if all of the specified conditions succeed (AND semantics). At least one match condition must be given.
Type: object
This schema accepts additional properties.
Properties
- path
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Match.Path
  - This schema accepts additional properties.
  - Properties
- method
  - #### Http Method
  - The value is restricted to the following:
    1. "NONE"
    2. 0
    3. "CONNECT"
    4. 1
    5. "DELETE"
    6. 2
    7. "GET"
    8. 3
    9. "HEAD"
    10. 4
    11. "OPTIONS"
    12. 5
    13. "PATCH"
    14. 6
    15. "POST"
    16. 7
    17. "PUT"
    18. 8
    19. "TRACE"
    20. 9
- headers
  - Type: array
    - Items
    - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Match.Header
- query_parameters
  - Type: array
    - Items
    - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Match.Query kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Match.Header
## Header
Header matches a value in a HTTP request header. Not that if the header is defined to have multiple values, a REGEX match must be used to match a specific value.
Type: object
This schema accepts additional properties.
Properties
- match
  - #### Match Type
  - The value is restricted to the following:
    1. "EXACT"
    2. 0
    3. "REGEX"
    4. 1
    5. "ABSENT"
    6. 2
    7. "PRESENT"
    8. 3
- name
  - Name of the HTTP header containing the value to match.
  - Type: string
- value
  - Value that the HTTP header value should be matched against.
  - Type: string kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Match.Path
## Path
Path matches may be "EXACT", "PREFIX", or "REGEX" matches. If the match type is not specified, "EXACT" is the default.
Type: object
This schema accepts additional properties.
Properties
- match
  - #### Match Type
  - The value is restricted to the following:
    1. "EXACT"
    2. 0
    3. "PREFIX"
    4. 1
    5. "REGEX"
    6. 2
- value
  - Value is the path to match against. For EXACT and PREFIX match types, it must be a HTTP URI path. For the REGEX match type, it must be a RE2 regular expression. Note that a PREFIX match succeeds only if the prefix is the the entire path or is followed by a /. I.e. a prefix of the path in terms of path elements.
  - Type: string
  - Length: ≥ 1

kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Match.Query

## Query
Query matches against HTTP request query parameters.
Type: object
This schema accepts additional properties.
Properties
- match
  - #### Match Type
  - The value is restricted to the following:
    1. "EXACT"
    2. 0
    3. "REGEX"
    4. 1
- name
  - Name of the query parameter containing the value to match.
  - Type: string
- value
  - Value that the query parameter value should be matched against.
  - Type: string kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Rule
## Rule
Type: object
This schema accepts additional properties.
Properties
- matches
  - Matches are checked in order. If any match is successful, the rule is selected (OR semantics).
  - Type: array
    - Items
    - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Match
- filters
  - Filters are request processing steps that are applied to matched requests. If the redirect filter is specified, it must be the only filter given.
  - Type: array
    - Items
    - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter
- backends
  - Backends is the set of services to which the gateway will forward requests. If a redirect filter is specified, no backends are allowed. Otherwise, at least one backend must be given.
  - Type: array
    - Items
    - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.Backend kuma.mesh.v1alpha1.MeshGatewayRoute.TcpRoute
## Tcp Route
TCP routes are valid for listeners that accept connections over TCP.
Type: object
This schema accepts additional properties.
Properties
- rules
  - Type: array
    - Items
    - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.TcpRoute.Rule kuma.mesh.v1alpha1.MeshGatewayRoute.TcpRoute.Rule
## Rule
repeated Match matches = 1;
Type: object
This schema accepts additional properties.
Properties
- backends
  - Type: array
    - Items
    - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.Backend kuma.mesh.v1alpha1.Selector
## Selector
Selector defines structure for selecting tags for given dataplane
Type: object
This schema accepts additional properties.
Properties
- match
  - Tags to match, can be used for both source and destinations
  - Type: object
  - This schema accepts additional properties.
  - Properties

Generated with json-schema-md-doc Fri May 09 2025 21:38:30 GMT+0000 (Coordinated Universal Time)