Mesh HTTP Route

This policy uses new policy matching algorithm. Do not combine with TrafficRoute.

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 typetop leveltofrom
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:

  1. spec:
  2.   targetRef: # top-level targetRef selects a group of proxies to configure
  3.     kind: Mesh|MeshSubset|MeshService|MeshServiceSubset 
  4.   to:
  5.     - targetRef: # targetRef selects a destination (outbound listener)
  6.         kind: MeshService
  7.         name: backend
  8.       rules:
  9.         - matches: [...] # various ways to match an HTTP request (path, method, query)
  10.           default: # configuration applied for the matched HTTP request
  11.             filters: [...]
  12.             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 on
    • type - one of Exact, PathPrefix , RegularExpression
    • value - actual value that’s going to be matched depending on the type
  • method - (optional) - HTTP2 method, available values are CONNECT, 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 succeed
    • type - one of Exact or RegularExpression
    • name - name of the query parameter
    • value - actual value that’s going to be matched depending on the type

Default conf

  • filters - (optional) - a list of modifications applied to the matched request
    • type - available values are RequestHeaderModifier, ResponseHeaderModifier, RequestRedirect, URLRewrite.
    • requestHeaderModifier - HeaderModifier, must be set if the type is RequestHeaderModifier.
    • responseHeaderModifier - HeaderModifier, must be set if the type is ResponseHeaderModifier.
    • requestRedirect - must be set if the type is RequestRedirect
      • scheme - one of http or http2
      • 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 the Location 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 are 301, 302, 303, 307, 308.
    • urlRewrite - must be set if the type is URLRewrite
      • 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 of ReplaceFullPath, ReplacePrefixMatch
        • replaceFullPath - must be set if the type is ReplaceFullPath
        • replacePrefixMatch - must be set if the type is ReplacePrefixMatch
    • requestMirror - must be set if the type is RequestMirror
      • 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 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

BackendRef

  • kind - one of MeshService, MeshServiceSubset
  • name - service name
  • tags - service tags, must be specified if the kind is MeshServiceSubset
  • 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 in backendRefs list.

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.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshHTTPRoute
  3. metadata:
  4.   name: http-route-1
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: default
  8. spec:
  9.   targetRef:
  10.     kind: MeshService
  11.     name: frontend_kuma-demo_svc_8080
  12.   to:
  13.     - targetRef:
  14.         kind: MeshService
  15.         name: backend_kuma-demo_svc_3001
  16.       rules:
  17.         - matches:
  18.             - path:
  19.                 type: PathPrefix
  20.                 value: /api
  21.           default:
  22.             backendRefs:
  23.               - kind: MeshServiceSubset
  24.                 name: backend_kuma-demo_svc_3001
  25.                 tags:
  26.                   version: "1.0"
  27.                 weight: 90
  28.               - kind: MeshServiceSubset
  29.                 name: backend_kuma-demo_svc_3001
  30.                 tags:
  31.                   version: "2.0"
  32.                 weight: 10
  1. type: MeshHTTPRoute
  2. name: http-route-1
  3. mesh: default
  4. spec:
  5.   targetRef:
  6.     kind: MeshService
  7.     name: frontend_kuma-demo_svc_8080
  8.   to:
  9.     - targetRef:
  10.         kind: MeshService
  11.         name: backend_kuma-demo_svc_3001
  12.       rules:
  13.         - matches:
  14.             - path:
  15.                 type: PathPrefix
  16.                 value: /api
  17.           default:
  18.             backendRefs:
  19.               - kind: MeshServiceSubset
  20.                 name: backend_kuma-demo_svc_3001
  21.                 tags:
  22.                   version: "1.0"
  23.                 weight: 90
  24.               - kind: MeshServiceSubset
  25.                 name: backend_kuma-demo_svc_3001
  26.                 tags:
  27.                   version: "2.0"
  28.                 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.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshHTTPRoute
  3. metadata:
  4.   name: http-route-1
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: default
  8. spec:
  9.   targetRef:
  10.     kind: MeshService
  11.     name: frontend_kuma-demo_svc_8080
  12.   to:
  13.     - targetRef:
  14.         kind: MeshService
  15.         name: backend_kuma-demo_svc_3001
  16.       rules:
  17.         - matches:
  18.             - path:
  19.                 type: Exact
  20.                 value: /
  21.           default:
  22.             filters:
  23.               - type: RequestHeaderModifier
  24.                 requestHeaderModifier:
  25.                   set:
  26.                     - name: x-custom-header
  27.                       value: xyz
  1. type: MeshHTTPRoute
  2. name: http-route-1
  3. mesh: default
  4. spec:
  5.   targetRef:
  6.     kind: MeshService
  7.     name: frontend_kuma-demo_svc_8080
  8.   to:
  9.     - targetRef:
  10.         kind: MeshService
  11.         name: backend_kuma-demo_svc_3001
  12.       rules:
  13.         - matches:
  14.             - path:
  15.                 type: Exact
  16.                 value: /
  17.           default:
  18.             filters:
  19.               - type: RequestHeaderModifier
  20.                 requestHeaderModifier:
  21.                   set:
  22.                     - name: x-custom-header
  23.                       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.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshHTTPRoute
  3. metadata:
  4.   name: http-route-1
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: default
  8. spec:
  9.   targetRef:
  10.     kind: MeshService
  11.     name: frontend_kuma-demo_svc_8080
  12.   to:
  13.     - targetRef:
  14.         kind: MeshService
  15.         name: backend_kuma-demo_svc_3001
  16.       rules:
  17.         - matches:
  18.             - headers:
  19.                 - type: Exact
  20.                   name: mirror-this-request
  21.                   value: "true"
  22.           default:
  23.             filters:
  24.               - type: RequestMirror
  25.                 requestMirror:
  26.                   percentage: 30
  27.                   backendRef:
  28.                     kind: MeshServiceSubset
  29.                     name: backend_kuma-demo_svc_3001
  30.                     tags:
  31.                       version: v1/experimental
  32.             backendRefs:
  33.               - kind: MeshServiceSubset
  34.                 name: backend_kuma-demo_svc_3001
  35.                 tags:
  36.                   version: v0
  1. type: MeshHTTPRoute
  2. name: http-route-1
  3. mesh: default
  4. spec:
  5.   targetRef:
  6.     kind: MeshService
  7.     name: frontend_kuma-demo_svc_8080
  8.   to:
  9.     - targetRef:
  10.         kind: MeshService
  11.         name: backend_kuma-demo_svc_3001
  12.       rules:
  13.         - matches:
  14.             - headers:
  15.                 - type: Exact
  16.                   name: mirror-this-request
  17.                   value: "true"
  18.           default:
  19.             filters:
  20.               - type: RequestMirror
  21.                 requestMirror:
  22.                   percentage: 30
  23.                   backendRef:
  24.                     kind: MeshServiceSubset
  25.                     name: backend_kuma-demo_svc_3001
  26.                     tags:
  27.                       version: v1/experimental
  28.             backendRefs:
  29.               - kind: MeshServiceSubset
  30.                 name: backend_kuma-demo_svc_3001
  31.                 tags:
  32.                   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:

  1. # MeshHTTPRoute-1
  2. rules:
  3.   - matches: # key-1
  4.       - path:
  5.           type: Exact
  6.           name: /orders
  7.         method: GET
  8.     default: CONF_1 # value
  9.   - matches: # key-2
  10.       - path:
  11.           type: Exact
  12.           name: /payments
  13.         method: POST
  14.     default: CONF_2 # value
  15. ---
  16. # MeshHTTPRoute-2
  17. rules:
  18.   - matches: # key-3
  19.       - path:
  20.           type: Exact
  21.           name: /orders
  22.         method: GET
  23.     default: CONF_3 # value
  24.   - matches: # key-4
  25.       - path:
  26.           type: Exact
  27.           name: /payments
  28.         method: POST
  29.     default: CONF_4 # value

merged in the following list of rules:

  1. rules:
  2.   - matches: 
  3.       - path:
  4.           type: Exact
  5.           name: /orders
  6.         method: GET
  7.     default: merge(CONF_1, CONF_3) # because 'key-1' == 'key-3'
  8.   - matches:
  9.       - path:
  10.           type: Exact
  11.           name: /payments
  12.         method: POST
  13.     default: merge(CONF_2, CONF_4) # because 'key-2' == 'key-4'

All policy options