このページは、まだ日本語ではご利用いただけません。翻訳中です。
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 is coming from and where it’s going to.
TargetRef support matrix
targetRef |
Allowed kinds |
---|---|
targetRef.kind |
Mesh , MeshSubset
|
to[].targetRef.kind |
MeshService |
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 different MeshServices
implementing A/B testing or canary deployments.
If we want to split traffic between v1
and v2
versions of the same service,
first we have to create MeshServices backend-v1
and backend-v2
that select
backend application instances according to the version.
apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
name: http-split
namespace: kuma-demo
labels:
kuma.io/mesh: default
spec:
targetRef:
kind: MeshSubset
tags:
app: frontend
to:
- targetRef:
kind: MeshService
name: backend
namespace: kuma-demo
sectionName: http
rules:
- matches:
- path:
type: PathPrefix
value: "/"
default:
backendRefs:
- kind: MeshService
name: backend-v1
namespace: kuma-demo
port: 3001
weight: 90
- kind: MeshService
name: backend-v2
namespace: kuma-demo
port: 3001
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
tries to consume backend
.
apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
name: http-route-1
namespace: kuma-demo
labels:
kuma.io/mesh: default
spec:
targetRef:
kind: MeshSubset
tags:
app: frontend
to:
- targetRef:
kind: MeshService
name: backend
namespace: kuma-demo
sectionName: http
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-demo
labels:
kuma.io/mesh: default
spec:
targetRef:
kind: MeshSubset
tags:
app: frontend
to:
- targetRef:
kind: MeshService
name: backend
namespace: kuma-demo
sectionName: http
rules:
- matches:
- headers:
- type: Exact
name: mirror-this-request
value: 'true'
default:
filters:
- type: RequestMirror
requestMirror:
percentage: 30
backendRef:
kind: MeshService
name: backend-v1-experimental
namespace: kuma-demo
port: 3001
backendRefs:
- kind: MeshService
name: backend
namespace: kuma-demo
port: 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
,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 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
-
-
-
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
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
,MeshExtenalService
-
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.
Spec is the specification of the Kuma MeshHTTPRoute resource.
Type: object
Properties
- targetRef
- TargetRef is a reference to the resource the policy takes an effect on.The resource could be either a real store object or virtual resourcedefined inplace.
- Type:
object
- Properties
- kind
- Kind of the referenced resource
- Type:
string
- The value is restricted to the following:
- "Mesh"
- "MeshSubset"
- "MeshGateway"
- "MeshService"
- "MeshExternalService"
- "MeshMultiZoneService"
- "MeshServiceSubset"
- "MeshHTTPRoute"
- labels
- Labels are used to select group of MeshServices that match labels. Either Labels orName and Namespace can be used.
- Type:
object
- This schema accepts additional properties.
- Properties
- mesh
- Mesh is reserved for future use to identify cross mesh resources.
- Type:
string
- name
- Name of the referenced resource. Can only be used with kinds:
MeshService
,MeshServiceSubset
andMeshGatewayRoute
- Type:
string
- Name of the referenced resource. Can only be used with kinds:
- namespace
- Namespace specifies the namespace of target resource. If empty only resources in policy namespacewill be targeted.
- Type:
string
- proxyTypes
- ProxyTypes specifies the data plane types that are subject to the policy. When not specified,all data plane types are targeted by the policy.
- Type:
array
- Item Count: ≥ 1
- Items
- Type:
string
- The value is restricted to the following:
- "Sidecar"
- "Gateway"
- sectionName
- SectionName is used to target specific section of resource.For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.
- Type:
string
- tags
- Tags used to select a subset of proxies by tags. Can only be used with kinds
MeshSubset
andMeshServiceSubset
- Type:
object
- This schema accepts additional properties.
- Properties
- Tags used to select a subset of proxies by tags. Can only be used with kinds
- kind
- to
- To matches destination services of requests and holds configuration.
- Type:
array
- Items
- Type:
object
- Properties
- hostnames
- Hostnames is only valid when targeting MeshGateway and limits theeffects of the rules to requests to this hostname.Given hostnames must intersect with the hostname of the listeners theroute attaches to.
- Type:
array
- Items
- Type:
string
- rules
- Rules contains the routing rules applies to a combination of top-leveltargetRef and the targetRef in this entry.
- Type:
array
- Items
- Type:
object
- Properties
- default
required
- Default holds routing rules that can be merged with rules from otherpolicies.
- Type:
object
- Properties
- backendRefs
- Type:
array
- Items
- BackendRef defines where to forward traffic.
- Type:
object
- Properties
- kind
- Kind of the referenced resource
- Type:
string
- The value is restricted to the following:
- "Mesh"
- "MeshSubset"
- "MeshGateway"
- "MeshService"
- "MeshExternalService"
- "MeshMultiZoneService"
- "MeshServiceSubset"
- "MeshHTTPRoute"
- labels
- Labels are used to select group of MeshServices that match labels. Either Labels orName and Namespace can be used.
- Type:
object
- This schema accepts additional properties.
- Properties
- mesh
- Mesh is reserved for future use to identify cross mesh resources.
- Type:
string
- name
- Name of the referenced resource. Can only be used with kinds:
MeshService
,MeshServiceSubset
andMeshGatewayRoute
- Type:
string
- Name of the referenced resource. Can only be used with kinds:
- namespace
- Namespace specifies the namespace of target resource. If empty only resources in policy namespacewill be targeted.
- Type:
string
- port
- Port is only supported when this ref refers to a real MeshService object
- Type:
integer
- proxyTypes
- ProxyTypes specifies the data plane types that are subject to the policy. When not specified,all data plane types are targeted by the policy.
- Type:
array
- Item Count: ≥ 1
- Items
- Type:
string
- The value is restricted to the following:
- "Sidecar"
- "Gateway"
- sectionName
- SectionName is used to target specific section of resource.For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.
- Type:
string
- tags
- Tags used to select a subset of proxies by tags. Can only be used with kinds
MeshSubset
andMeshServiceSubset
- Type:
object
- This schema accepts additional properties.
- Properties
- Tags used to select a subset of proxies by tags. Can only be used with kinds
- weight
- Type:
integer
- Default:
1
- Range: ≥ 0
- Type:
- kind
- Type:
- filters
- Type:
array
- Items
- Type:
object
- Properties
- requestHeaderModifier
- Only one action is supported per header name.Configuration to set or add multiple values for a header must use RFC 7230header value formatting, separating each value with a comma.
- Type:
object
- Properties
- add
- Type:
array
- Item Count: ≤ 16
- Items
- Type:
object
- Properties
- name
required
- Type:
string
- The value must match this pattern:
^[a-z0-9!#$%&'*+\-.^_\x60|~]+$
- Length: between 1 and 256
- Type:
- value
required
- Type:
string
- Type:
- name
- Type:
- remove
- Type:
array
- Item Count: ≤ 16
- Items
- Type:
string
- Type:
- set
- Type:
array
- Item Count: ≤ 16
- Items
- Type:
object
- Properties
- name
required
- Type:
string
- The value must match this pattern:
^[a-z0-9!#$%&'*+\-.^_\x60|~]+$
- Length: between 1 and 256
- Type:
- value
required
- Type:
string
- Type:
- name
- Type:
- add
- requestMirror
- Type:
object
- Properties
- backendRef
required
- BackendRef defines where to forward traffic.
- Type:
object
- Properties
- kind
- Kind of the referenced resource
- Type:
string
- The value is restricted to the following:
- "Mesh"
- "MeshSubset"
- "MeshGateway"
- "MeshService"
- "MeshExternalService"
- "MeshMultiZoneService"
- "MeshServiceSubset"
- "MeshHTTPRoute"
- labels
- Labels are used to select group of MeshServices that match labels. Either Labels orName and Namespace can be used.
- Type:
object
- This schema accepts additional properties.
- Properties
- mesh
- Mesh is reserved for future use to identify cross mesh resources.
- Type:
string
- name
- Name of the referenced resource. Can only be used with kinds:
MeshService
,MeshServiceSubset
andMeshGatewayRoute
- Type:
string
- Name of the referenced resource. Can only be used with kinds:
- namespace
- Namespace specifies the namespace of target resource. If empty only resources in policy namespacewill be targeted.
- Type:
string
- port
- Port is only supported when this ref refers to a real MeshService object
- Type:
integer
- proxyTypes
- ProxyTypes specifies the data plane types that are subject to the policy. When not specified,all data plane types are targeted by the policy.
- Type:
array
- Item Count: ≥ 1
- Items
- Type:
string
- The value is restricted to the following:
- "Sidecar"
- "Gateway"
- sectionName
- SectionName is used to target specific section of resource.For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.
- Type:
string
- tags
- Tags used to select a subset of proxies by tags. Can only be used with kinds
MeshSubset
andMeshServiceSubset
- Type:
object
- This schema accepts additional properties.
- Properties
- Tags used to select a subset of proxies by tags. Can only be used with kinds
- weight
- Type:
integer
- Default:
1
- Range: ≥ 0
- Type:
- kind
- percentage
- Percentage of requests to mirror. If not specified, all requeststo the target cluster will be mirrored.
- backendRef
- Type:
- requestRedirect
- Type:
object
- Properties
- hostname
- PreciseHostname is the fully qualified domain name of a network host. Thismatches the RFC 1123 definition of a hostname with 1 notable exception thatnumeric IP addresses are not allowed.Note that as per RFC1035 and RFC1123, a label must consist of lower casealphanumeric characters or '-', and must start and end with an alphanumericcharacter. No other punctuation is allowed.
- Type:
string
- The value must match this pattern:
^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
- Length: between 1 and 253
- path
- Path defines parameters used to modify the path of the incoming request.The modified path is then used to construct the location header.When empty, the request path is used as-is.
- Type:
object
- Properties
- replaceFullPath
- Type:
string
- Type:
- replacePrefixMatch
- Type:
string
- Type:
- type
required
- Type:
string
- The value is restricted to the following:
- "ReplaceFullPath"
- "ReplacePrefixMatch"
- Type:
- replaceFullPath
- port
- Port is the port to be used in the value of the
Location
header in the response.When empty, port (if specified) of the request is used. - Type:
integer
- Range: between 1 and 65535
- Port is the port to be used in the value of the
- scheme
- Type:
string
- The value is restricted to the following:
- "http"
- "https"
- Type:
- statusCode
- StatusCode is the HTTP status code to be used in response.
- Type:
integer
- The value is restricted to the following:
301
302
303
307
308
- Default:
302
- hostname
- Type:
- responseHeaderModifier
- Only one action is supported per header name.Configuration to set or add multiple values for a header must use RFC 7230header value formatting, separating each value with a comma.
- Type:
object
- Properties
- add
- Type:
array
- Item Count: ≤ 16
- Items
- Type:
object
- Properties
- name
required
- Type:
string
- The value must match this pattern:
^[a-z0-9!#$%&'*+\-.^_\x60|~]+$
- Length: between 1 and 256
- Type:
- value
required
- Type:
string
- Type:
- name
- Type:
- remove
- Type:
array
- Item Count: ≤ 16
- Items
- Type:
string
- Type:
- set
- Type:
array
- Item Count: ≤ 16
- Items
- Type:
object
- Properties
- name
required
- Type:
string
- The value must match this pattern:
^[a-z0-9!#$%&'*+\-.^_\x60|~]+$
- Length: between 1 and 256
- Type:
- value
required
- Type:
string
- Type:
- name
- Type:
- add
- type
required
- Type:
string
- The value is restricted to the following:
- "RequestHeaderModifier"
- "ResponseHeaderModifier"
- "RequestRedirect"
- "URLRewrite"
- "RequestMirror"
- Type:
- urlRewrite
- Type:
object
- Properties
- hostToBackendHostname
- HostToBackendHostname rewrites the hostname to the hostname of theupstream host. This option is only available when targeting MeshGateways.
- Type:
boolean
- hostname
- Hostname is the value to be used to replace the host header value during forwarding.
- Type:
string
- The value must match this pattern:
^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
- Length: between 1 and 253
- path
- Path defines a path rewrite.
- Type:
object
- Properties
- replaceFullPath
- Type:
string
- Type:
- replacePrefixMatch
- Type:
string
- Type:
- type
required
- Type:
string
- The value is restricted to the following:
- "ReplaceFullPath"
- "ReplacePrefixMatch"
- Type:
- replaceFullPath
- hostToBackendHostname
- Type:
- requestHeaderModifier
- Type:
- backendRefs
- matches
required
- Matches describes how to match HTTP requests this rule should be appliedto.
- Type:
array
- Item Count: ≥ 1
- Items
- Type:
object
- Properties
- headers
- Type:
array
- Items
- HeaderMatch describes how to select an HTTP route by matching HTTP requestheaders.
- Type:
object
- Properties
- name
required
- Name is the name of the HTTP Header to be matched. Name MUST be lower caseas they will be handled with case insensitivity (See https://tools.ietf.org/html/rfc7230#section-3.2).
- Type:
string
- The value must match this pattern:
^[a-z0-9!#$%&'*+\-.^_\x60|~]+$
- Length: between 1 and 256
- type
- Type specifies how to match against the value of the header.
- Type:
string
- The value is restricted to the following:
- "Exact"
- "Present"
- "RegularExpression"
- "Absent"
- "Prefix"
- Default: "Exact"
- value
- Value is the value of HTTP Header to be matched.
- Type:
string
- name
- Type:
- method
- Type:
string
- The value is restricted to the following:
- "CONNECT"
- "DELETE"
- "GET"
- "HEAD"
- "OPTIONS"
- "PATCH"
- "POST"
- "PUT"
- "TRACE"
- Type:
- path
- Type:
object
- Properties
- type
required
- Type:
string
- The value is restricted to the following:
- "Exact"
- "PathPrefix"
- "RegularExpression"
- Type:
- value
required
- Exact or prefix matches must be an absolute path. A prefix matches onlyif separated by a slash or the entire path.
- Type:
string
- Length: ≥ 1
- type
- Type:
- queryParams
- QueryParams matches based on HTTP URL query parameters. Multiple matchesare ANDed together such that all listed matches must succeed.
- Type:
array
- Items
- Type:
object
- Properties
- name
required
- Type:
string
- Length: ≥ 1
- Type:
- type
required
- Type:
string
- The value is restricted to the following:
- "Exact"
- "RegularExpression"
- Type:
- value
required
- Type:
string
- Type:
- name
- headers
- default
- targetRef
- TargetRef is a reference to the resource that represents a group ofrequest destinations.
- Type:
object
- Properties
- kind
- Kind of the referenced resource
- Type:
string
- The value is restricted to the following:
- "Mesh"
- "MeshSubset"
- "MeshGateway"
- "MeshService"
- "MeshExternalService"
- "MeshMultiZoneService"
- "MeshServiceSubset"
- "MeshHTTPRoute"
- labels
- Labels are used to select group of MeshServices that match labels. Either Labels orName and Namespace can be used.
- Type:
object
- This schema accepts additional properties.
- Properties
- mesh
- Mesh is reserved for future use to identify cross mesh resources.
- Type:
string
- name
- Name of the referenced resource. Can only be used with kinds:
MeshService
,MeshServiceSubset
andMeshGatewayRoute
- Type:
string
- Name of the referenced resource. Can only be used with kinds:
- namespace
- Namespace specifies the namespace of target resource. If empty only resources in policy namespacewill be targeted.
- Type:
string
- proxyTypes
- ProxyTypes specifies the data plane types that are subject to the policy. When not specified,all data plane types are targeted by the policy.
- Type:
array
- Item Count: ≥ 1
- Items
- Type:
string
- The value is restricted to the following:
- "Sidecar"
- "Gateway"
- sectionName
- SectionName is used to target specific section of resource.For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.
- Type:
string
- tags
- Tags used to select a subset of proxies by tags. Can only be used with kinds
MeshSubset
andMeshServiceSubset
- Type:
object
- This schema accepts additional properties.
- Properties
- Tags used to select a subset of proxies by tags. Can only be used with kinds
- kind
- hostnames
Generated with json-schema-md-doc