Configuring built-in routes

For configuring how traffic is forwarded from a listener to your mesh services, use MeshHTTPRoute and MeshTCPRoute.

Using these route resources with a gateway requires using spec.targetRef to target gateway data plane proxies. Otherwise, filtering and routing traffic is configured as outlined in the docs.

Note that when using MeshHTTPRoute and MeshTCPRoute with builtin gateways, spec.to[].targetRef is restricted to kind: Mesh.

MeshHTTPRoute

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshHTTPRoute
  3. metadata:
  4.   name: edge-gateway-route
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: default
  8. spec:
  9.   targetRef:
  10.     kind: MeshGateway
  11.     name: edge-gateway
  12.     tags:
  13.       port: http/8080
  14.   to:
  15.   - targetRef:
  16.       kind: Mesh
  17.     hostnames:
  18.     - example.com
  19.     rules:
  20.     - matches:
  21.       - path:
  22.           type: PathPrefix
  23.           value: "/"
  24.       default:
  25.         backendRefs:
  26.         - kind: MeshService
  27.           name: demo-app_kuma-demo_svc_5000
  1. type: MeshHTTPRoute
  2. name: edge-gateway-route
  3. mesh: default
  4. spec:
  5.   targetRef:
  6.     kind: MeshGateway
  7.     name: edge-gateway
  8.     tags:
  9.       port: http/8080
  10.   to:
  11.   - targetRef:
  12.       kind: Mesh
  13.     hostnames:
  14.     - example.com
  15.     rules:
  16.     - matches:
  17.       - path:
  18.           type: PathPrefix
  19.           value: "/"
  20.       default:
  21.         backendRefs:
  22.         - kind: MeshService
  23.           name: demo-app_kuma-demo_svc_5000

Listener hostname

Remember that MeshGateway listeners have an optional hostname field that limits the traffic accepted by the listener depending on the protocol:

  • HTTP: Host header must match
  • TLS: SNI must match
  • HTTPS: Both SNI and Host must match

When attaching routes to specific listeners the routes are isolated from each other. If we consider the following listeners:

  1. conf:
  2.   listeners:
  3.   - port: 8080
  4.     protocol: HTTP
  5.     hostname: foo.example.com
  6.     tags:
  7.       hostname: foo
  8.   - port: 8080
  9.     protocol: HTTP
  10.     hostname: *.example.com
  11.     tags:
  12.       hostname: wild

along with the following MeshHTTPRoute rule, the only one present in the mesh:

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshHTTPRoute
  3. metadata:
  4.   name: http-route
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: default
  8. spec:
  9.   targetRef:
  10.     kind: MeshGateway
  11.     name: edge-gateway
  12.     tags:
  13.       hostname: wild
  14.   to:
  15.   - targetRef:
  16.       kind: Mesh
  17.     rules:
  18.     - matches:
  19.       - path:
  20.           type: PathPrefix
  21.           value: "/"
  22.       default:
  23.         backendRefs:
  24.         - kind: MeshService
  25.           name: example_app_svc_8080
  1. type: MeshHTTPRoute
  2. name: http-route
  3. mesh: default
  4. spec:
  5.   targetRef:
  6.     kind: MeshGateway
  7.     name: edge-gateway
  8.     tags:
  9.       hostname: wild
  10.   to:
  11.   - targetRef:
  12.       kind: Mesh
  13.     rules:
  14.     - matches:
  15.       - path:
  16.           type: PathPrefix
  17.           value: "/"
  18.       default:
  19.         backendRefs:
  20.         - kind: MeshService
  21.           name: example_app_svc_8080

This route explicitly attaches to the second listener with hostname: *.example.com.

This means that requests to foo.example.com, which match the first listener because it’s more specific, will return a 404 because there are no routes attached for that listener.

MeshHTTPRoute hostnames

MeshHTTPRoute rules can themselves specify an additional list of hostnames to further limit the traffic handled by those rules. Consider the following example:

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshHTTPRoute
  3. metadata:
  4.   name: http-route
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: default
  8. spec:
  9.   targetRef:
  10.     kind: MeshGateway
  11.     name: edge-gateway
  12.   to:
  13.   - targetRef:
  14.       kind: Mesh
  15.     rules:
  16.     - matches:
  17.       - path:
  18.           type: PathPrefix
  19.           value: "/"
  20.       default:
  21.         backendRefs:
  22.         - kind: MeshServiceSubset
  23.           name: example_app_svc_8080
  24.           tags:
  25.             version: v1
  26.   - targetRef:
  27.       kind: Mesh
  28.     hostnames:
  29.     - dev.example.com
  30.     rules:
  31.     - matches:
  32.       - path:
  33.           type: PathPrefix
  34.           value: "/"
  35.       default:
  36.         backendRefs:
  37.         - kind: MeshServiceSubset
  38.           name: example_app_svc_8080
  39.           tags:
  40.             version: v2
  1. type: MeshHTTPRoute
  2. name: http-route
  3. mesh: default
  4. spec:
  5.   targetRef:
  6.     kind: MeshGateway
  7.     name: edge-gateway
  8.   to:
  9.   - targetRef:
  10.       kind: Mesh
  11.     rules:
  12.     - matches:
  13.       - path:
  14.           type: PathPrefix
  15.           value: "/"
  16.       default:
  17.         backendRefs:
  18.         - kind: MeshServiceSubset
  19.           name: example_app_svc_8080
  20.           tags:
  21.             version: v1
  22.   - targetRef:
  23.       kind: Mesh
  24.     hostnames:
  25.     - dev.example.com
  26.     rules:
  27.     - matches:
  28.       - path:
  29.           type: PathPrefix
  30.           value: "/"
  31.       default:
  32.         backendRefs:
  33.         - kind: MeshServiceSubset
  34.           name: example_app_svc_8080
  35.           tags:
  36.             version: v2

This route would send all traffic to dev.example.com to the v2 backend but other traffic to v1.

MeshTCPRoute

If your traffic isn’t HTTP, you can use MeshTCPRoute to balance traffic between services.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshTCPRoute
  3. metadata:
  4.   name: tcp-route
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: default
  8. spec:
  9.   targetRef:
  10.     kind: MeshGateway
  11.     name: edge-gateway
  12.   to:
  13.   - targetRef:
  14.       kind: Mesh
  15.     rules:
  16.     - default:
  17.         backendRefs:
  18.         - kind: MeshServiceSubset
  19.           name: example_app_svc_8080
  20.           tags:
  21.             version: v1
  22.           weight: 90
  23.         - kind: MeshServiceSubset
  24.           name: example_app_svc_8080
  25.           tags:
  26.             version: v2
  27.           weight: 10
  1. type: MeshTCPRoute
  2. name: tcp-route
  3. mesh: default
  4. spec:
  5.   targetRef:
  6.     kind: MeshGateway
  7.     name: edge-gateway
  8.   to:
  9.   - targetRef:
  10.       kind: Mesh
  11.     rules:
  12.     - default:
  13.         backendRefs:
  14.         - kind: MeshServiceSubset
  15.           name: example_app_svc_8080
  16.           tags:
  17.             version: v1
  18.           weight: 90
  19.         - kind: MeshServiceSubset
  20.           name: example_app_svc_8080
  21.           tags:
  22.             version: v2
  23.           weight: 10