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. 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
  28.           namespace: kuma-demo
  29.           port: 5000

I am using MeshService

  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
  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
  24.           port: 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. 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
  26.           namespace: app
  27.           port: 8080

I am using MeshService

  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
  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
  22.           port: 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: MeshService
  23.           name: example-v1_app_svc_8080
  24.   - targetRef:
  25.       kind: Mesh
  26.     hostnames:
  27.     - dev.example.com
  28.     rules:
  29.     - matches:
  30.       - path:
  31.           type: PathPrefix
  32.           value: "/"
  33.       default:
  34.         backendRefs:
  35.         - kind: MeshService
  36.           name: example-v2_app_svc_8080
  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: MeshService
  23.           name: example-v1
  24.           namespace: app
  25.           port: 8080
  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: MeshService
  38.           name: example-v2
  39.           namespace: app
  40.           port: 8080

I am using MeshService

  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: MeshService
  19.           name: example-v1
  20.   - targetRef:
  21.       kind: Mesh
  22.     hostnames:
  23.     - dev.example.com
  24.     rules:
  25.     - matches:
  26.       - path:
  27.           type: PathPrefix
  28.           value: "/"
  29.       default:
  30.         backendRefs:
  31.         - kind: MeshService
  32.           name: example-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: MeshService
  19.           name: example-v1
  20.           port: 8080
  21.   - targetRef:
  22.       kind: Mesh
  23.     hostnames:
  24.     - dev.example.com
  25.     rules:
  26.     - matches:
  27.       - path:
  28.           type: PathPrefix
  29.           value: "/"
  30.       default:
  31.         backendRefs:
  32.         - kind: MeshService
  33.           name: example-v2
  34.           port: 8080

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: MeshService
  19.           name: example-v1_app_svc_8080
  20.           weight: 90
  21.         - kind: MeshService
  22.           name: example-v2_app_svc_8080
  23.           weight: 10
  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: MeshService
  19.           name: example-v1
  20.           namespace: app
  21.           port: 8080
  22.           weight: 90
  23.         - kind: MeshService
  24.           name: example-v2
  25.           namespace: app
  26.           port: 8080
  27.           weight: 10

I am using MeshService

  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: MeshService
  15.           name: example-v1
  16.           weight: 90
  17.         - kind: MeshService
  18.           name: example-v2
  19.           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: MeshService
  15.           name: example-v1
  16.           port: 8080
  17.           weight: 90
  18.         - kind: MeshService
  19.           name: example-v2
  20.           port: 8080
  21.           weight: 10