このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
Mesh HTTP Route
This policy uses new policy matching algorithm. It’s recommended to migrate from TrafficRoute. See “Interactions with
TrafficRoute
” section for more information.
The MeshHTTPRoute
policy allows altering and redirecting HTTP requests
depending on where the request coming from and where it’s going to.
MeshHTTPRoute
does not route cross-zone traffic yet.
TargetRef support matrix
TargetRef type | top level | to | from |
---|---|---|---|
Mesh | ✅ | ❌ | ❌ |
MeshSubset | ✅ | ❌ | ❌ |
MeshService | ✅ | ✅ | ❌ |
MeshServiceSubset | ✅ | ❌ | ❌ |
If you don’t understand this table you should read matching docs.
Configuration
Unlike others outbound policies MeshHTTPRoute
doesn’t contain default
directly in the to
array.
The default
section is nested inside rules
, so the policy structure looks like this:
spec:
to:
- targetRef: {...}
rules:
- matches: [...] # various ways to match an HTTP request (path, method, query)
default: # configuration applied for the matched HTTP request
filters: [...]
backendRefs: [...]
Remember to tag your
Service
ports withappProtocol: http
to use them in aMeshHTTPRoute
!
Gateways
In order to route HTTP traffic for a MeshGateway, you need to target the
MeshGateway in spec.targetRef
and set spec.to[].targetRef.kind: Mesh
.
Interactions with MeshTCPRoute
MeshHTTPRoute
takes priority over MeshTCPRoute
when a proxy is targeted by both and the matching MeshTCPRoute
is ignored.
Interactions with TrafficRoute
MeshHTTPRoute
takes priority over TrafficRoute
when a proxy is targeted by both policies.
All legacy policies like Retry
, TrafficLog
, Timeout
etc. only match on routes defined by TrafficRoute
.
All new recommended policies like MeshRetry
, MeshAccessLog
, MeshTimeout
etc. match on routes defined by MeshHTTPRoute
and TrafficRoute
.
If you don’t use legacy policies, it’s recommended to remove any existing TrafficRoute
.
Otherwise, it’s recommended to migrate to new policies and then removing TrafficRoute
.
Examples
Traffic split
We can use MeshHTTPRoute
to split an HTTP traffic between services with different tags
implementing A/B testing or canary deployments.
Here is an example of a MeshHTTPRoute
that splits the traffic from
frontend_kuma-demo_svc_8080
to backend_kuma-demo_svc_3001
between versions,
but only on endpoints starting with /api
. All other endpoints will go to version: 1.0
.
Traffic modifications
We can use MeshHTTPRoute
to modify outgoing requests, by setting new path
or changing request and response headers.
Here is an example of a MeshHTTPRoute
that adds x-custom-header
with value xyz
when frontend_kuma-demo_svc_8080
tries to consume backend_kuma-demo_svc_3001
.
Merging
When several MeshHTTPRoute
policies target the same data plane proxy they’re merged.
Similar to the new policies the merging order is determined by
the top level targetRef.
The difference is in spec.to[].rules
.
Kong Mesh treats rules
as a key-value map
where matches
is a key and default
is a value. For example MeshHTTPRoute policies:
# MeshHTTPRoute-1
rules:
- matches: # key-1
- path:
type: Exact
name: /orders
method: GET
default: CONF_1 # value
- matches: # key-2
- path:
type: Exact
name: /payments
method: POST
default: CONF_2 # value
---
# MeshHTTPRoute-2
rules:
- matches: # key-3
- path:
type: Exact
name: /orders
method: GET
default: CONF_3 # value
- matches: # key-4
- path:
type: Exact
name: /payments
method: POST
default: CONF_4 # value
merged in the following list of rules:
rules:
- matches:
- path:
type: Exact
name: /orders
method: GET
default: merge(CONF_1, CONF_3) # because 'key-1' == 'key-3'
- matches:
- path:
type: Exact
name: /payments
method: POST
default: merge(CONF_2, CONF_4) # because 'key-2' == 'key-4'
All policy options
Matches
-
path
- (optional) - HTTP path to match the request on-
type
- one ofExact
,Prefix
,RegularExpression
-
value
- actual value that’s going to be matched depending on thetype
-
-
method
- (optional) - HTTP2 method, available values areCONNECT
,DELETE
,GET
,HEAD
,OPTIONS
,PATCH
,POST
,PUT
,TRACE
-
queryParams
- (optional) - list of HTTP URL query parameters. Multiple matches are combined together such that all listed matches must succeed-
type
- one ofExact
orRegularExpression
-
name
- name of the query parameter -
value
- actual value that’s going to be matched depending on thetype
-
Default conf
-
filters
- (optional) - a list of modifications applied to the matched request-
type
- available values areRequestHeaderModifier
,ResponseHeaderModifier
,RequestRedirect
,URLRewrite
. -
requestHeaderModifier
- HeaderModifier, must be set if thetype
isRequestHeaderModifier
. -
responseHeaderModifier
- HeaderModifier, must be set if thetype
isResponseHeaderModifier
. -
requestRedirect
- must be set if thetype
isRequestRedirect
-
scheme
- one ofhttp
orhttp2
-
hostname
- is the fully qualified domain name of a network host. This matches the RFC 1123 definition of a hostname with 1 notable exception that numeric IP addresses are not allowed. -
port
- is the port to be used in the value of theLocation
header in the response. When empty, port (if specified) of the request is used. -
statusCode
- is the HTTP status code to be used in response. Available values are301
,302
,303
,307
,308
.
-
-
urlRewrite
- must be set if thetype
isURLRewrite
-
hostname
- (optional) - is the fully qualified domain name of a network host. This matches the RFC 1123 definition of a hostname with 1 notable exception that numeric IP addresses are not allowed. -
path
- (optional)-
type
- one ofReplaceFullPath
,ReplacePrefixMatch
-
replaceFullPath
- must be set if thetype
isReplaceFullPath
-
replacePrefixMatch
- must be set if thetype
isReplacePrefixMatch
-
-
-
-
backendRefs
- BackendRef (optional), list of destinations to redirect requests to
Header modification
-
set
- (optional) - list of headers to set. Overrides value if the header exists.-
name
- header’s name -
value
- header’s value
-
-
add
- (optional) - list of headers to add. Appends value if the header exists.-
name
- header’s name -
value
- header’s value
-
-
remove
- (optional) - list of headers’ names to remove
Backends
-
kind
- one ofMeshService
,MeshServiceSubset
-
name
- service name -
tags
- service tags, must be specified if thekind
isMeshServiceSubset
-
weight
- when a request matches the route, the choice of an upstream cluster is determined by its weight. Total weight is a sum of all weights inbackendRefs
list.