Kuma Star

Careful!

You are browsing documentation for a version of Kuma that is not the latest release.

MeshGatewayRoute

New to Kuma? Don’t use this, check the MeshHTTPRoute policy or MeshTCPRoute policy instead.

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

MeshGatewayRoute is a Kuma dataplane policy that replaces TrafficRoute for Kuma 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.

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

Listener tags

When Kuma 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; Kuma 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 Kuma 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.

Kuma 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 Kuma 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

  • ## 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

  • ## 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

  • ## Filter

  • Type: object

  • This schema accepts additional properties.

  • Properties

  • ## Header Filter

  • Type: object

  • This schema accepts additional properties.

  • Properties

  • ## 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
    • 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

  • ## 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

  • ## 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

  • ## Tcp Route

  • TCP routes are valid for listeners that accept connections over TCP.

  • Type: object

  • This schema accepts additional properties.

  • Properties

  • ## Rule

  • repeated Match matches = 1;

  • Type: object

  • This schema accepts additional properties.

  • Properties

  • ## 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 Tue Apr 01 2025 13:57:37 GMT+0000 (Coordinated Universal Time)