このページは、まだ日本語ではご利用いただけません。翻訳中です。
MeshGatewayRoute
New to Kuma? Don’t use this, check the
MeshHTTPRoute
policy orMeshTCPRoute
policy instead.
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
.
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 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.
- $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.Conf
- selectors
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
- weight
kuma.mesh.v1alpha1.MeshGatewayRoute.Conf
- ## Conf
- Type:
object
- This schema accepts additional properties.
- Properties
- tcp
- http
- #### TlsRoute tls = 3;
- TlsRoute tls = 3;
- $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute
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
- hostnames
kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter
- ## Filter
- Type:
object
- This schema accepts additional properties.
- Properties
- request_header
- mirror
- redirect
- rewrite
- response_header
kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter.HeaderFilter
- ## Header Filter
- Type:
object
- This schema accepts additional properties.
- Properties
- set
- Type:
array
- Type:
- add
- Type:
array
- Type:
- remove
- Type:
array
- Items
- Type:
string
- Type:
- set
kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter.HeaderFilter.Header
- ## Header
- Type:
object
- This schema accepts additional properties.
- Properties
- name
- Type:
string
- Type:
- value
- Type:
string
- Type:
- name
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.
- $ref: #/definitions/kuma.mesh.v1alpha1.MeshGatewayRoute.Backend
- percentage
- Percentage specifies the percentage of requests to mirror to the backend (in the range 0.0 - 100.0, inclusive).
- Type:
number
- backend
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
- scheme
kuma.mesh.v1alpha1.MeshGatewayRoute.HttpRoute.Filter.Rewrite
- ## Rewrite
- Type:
object
- This schema accepts additional properties.
- Properties
- replace_full
- Type:
string
- Type:
- 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 requestheader filter which explicitly replaces "host" header_
- Type:
boolean
- replace_full
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
- method
- #### Http Method
- The value is restricted to the following:
- "NONE"
0
- "CONNECT"
1
- "DELETE"
2
- "GET"
3
- "HEAD"
4
- "OPTIONS"
5
- "PATCH"
6
- "POST"
7
- "PUT"
8
- "TRACE"
9
- headers
- Type:
array
- Type:
- query_parameters
- Type:
array
- Type:
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:
- "EXACT"
0
- "REGEX"
1
- "ABSENT"
2
- "PRESENT"
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
- match
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:
- "EXACT"
0
- "PREFIX"
1
- "REGEX"
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
- match
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:
- "EXACT"
0
- "REGEX"
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
- match
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
- 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
- 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
- matches
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
- Type:
- rules
kuma.mesh.v1alpha1.MeshGatewayRoute.TcpRoute.Rule
- ## Rule
- repeated Match matches = 1;
- Type:
object
- This schema accepts additional properties.
- Properties
- backends
- Type:
array
- Type:
- backends
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
- match
Generated with json-schema-md-doc