Careful!
You are browsing documentation for a version of Kuma that is not the latest release.
Looking for even older versions? Learn more.
Mesh HTTP Route
This policy uses new policy matching algorithm.
Do not combine with TrafficRoute except for the default route-all
route, which should be kept..
The MeshHTTPRoute
policy allows altering and redirecting HTTP requests
depending on where the request coming from and where it’s going to.
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:
targetRef: # top-level targetRef selects a group of proxies to configure
kind: Mesh|MeshSubset|MeshService|MeshServiceSubset
to:
- targetRef: # targetRef selects a destination (outbound listener)
kind: MeshService
name: backend
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 with appProtocol: http
to use
them in a MeshHTTPRoute
!
Matches
path
- (optional) - HTTP path to match the request ontype
- one ofExact
,PathPrefix
,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 ANDed together such that all listed matches must succeedtype
- one ofExact
orRegularExpression
name
- name of the query parametervalue
- actual value that’s going to be matched depending on thetype
Default conf
filters
- (optional) - a list of modifications applied to the matched requesttype
- 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
requestMirror
- must be set if thetype
isRequestMirror
percentage
- percentage of requests to mirror. If not specified, all requests to the target cluster will be mirrored.backendRef
- BackendRef, destination to mirror request to
backendRefs
- BackendRef (optional), list of destinations to redirect requests to
HeaderModifier
set
- (optional) - list of headers to set. Overrides value if the header exists.name
- header’s namevalue
- header’s value
add
- (optional) - list of headers to add. Appends value if the header exists.name
- header’s namevalue
- header’s value
remove
- (optional) - list of headers’ names to remove
BackendRef
kind
- one ofMeshService
,MeshServiceSubset
name
- service nametags
- 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.
Interactions with MeshTCPRoute
MeshHTTPRoute
takes priority over MeshTCPRoute
when both are defined for the same service, and the matching MeshTCPRoute
is ignored.
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
.
apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
name: http-route-1
namespace: kuma-system
labels:
kuma.io/mesh: default
spec:
targetRef:
kind: MeshService
name: frontend_kuma-demo_svc_8080
to:
- targetRef:
kind: MeshService
name: backend_kuma-demo_svc_3001
rules:
- matches:
- path:
type: PathPrefix
value: /
default:
backendRefs:
- kind: MeshServiceSubset
name: backend_kuma-demo_svc_3001
tags:
version: "v0"
weight: 90
- kind: MeshServiceSubset
name: backend_kuma-demo_svc_3001
tags:
version: "v1"
weight: 10
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
.
apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
name: http-route-1
namespace: kuma-system
labels:
kuma.io/mesh: default
spec:
targetRef:
kind: MeshService
name: frontend_kuma-demo_svc_8080
to:
- targetRef:
kind: MeshService
name: backend_kuma-demo_svc_3001
rules:
- matches:
- path:
type: Exact
value: /
default:
filters:
- type: RequestHeaderModifier
requestHeaderModifier:
set:
- name: x-custom-header
value: xyz
Traffic mirror
MeshHTTPRoute
can mirror a fraction of requests to another service.
This can be useful when testing a new version of the app with the production payload without
interrupting real users.
apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
name: http-route-1
namespace: kuma-system
labels:
kuma.io/mesh: default
spec:
targetRef:
kind: MeshService
name: frontend_kuma-demo_svc_8080
to:
- targetRef:
kind: MeshService
name: backend_kuma-demo_svc_3001
rules:
- matches:
- headers:
- type: Exact
name: mirror-this-request
value: "true"
default:
filters:
- type: RequestMirror
requestMirror:
percentage: 30
backendRef:
kind: MeshServiceSubset
name: backend_kuma-demo_svc_3001
tags:
version: v1_experimental
backendRefs:
- kind: MeshServiceSubset
name: backend_kuma-demo_svc_3001
tags:
version: v0
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
.
Kuma 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'