Kuma Star

Careful!

You are browsing documentation for the next version of Kuma. Use this version at your own risk.

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

apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: edge-gateway-route
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshGateway
    name: edge-gateway
    tags:
      port: http-8080
  to:
  - targetRef:
      kind: Mesh
    hostnames:
    - example.com
    rules:
    - matches:
      - path:
          type: PathPrefix
          value: "/"
      default:
        backendRefs:
        - kind: MeshService
          name: demo-app_kuma-demo_svc_5000

apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: edge-gateway-route
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshGateway
    name: edge-gateway
    tags:
      port: http-8080
  to:
  - targetRef:
      kind: Mesh
    hostnames:
    - example.com
    rules:
    - matches:
      - path:
          type: PathPrefix
          value: "/"
      default:
        backendRefs:
        - kind: MeshService
          name: demo-app
          namespace: kuma-demo
          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:

conf:
  listeners:
  - port: 8080
    protocol: HTTP
    hostname: foo.example.com
    tags:
      hostname: foo
  - port: 8080
    protocol: HTTP
    hostname: *.example.com
    tags:
      hostname: wild

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

apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: http-route
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshGateway
    name: edge-gateway
    tags:
      hostname: wild
  to:
  - targetRef:
      kind: Mesh
    rules:
    - matches:
      - path:
          type: PathPrefix
          value: "/"
      default:
        backendRefs:
        - kind: MeshService
          name: example_app_svc_8080

apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: http-route
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshGateway
    name: edge-gateway
    tags:
      hostname: wild
  to:
  - targetRef:
      kind: Mesh
    rules:
    - matches:
      - path:
          type: PathPrefix
          value: "/"
      default:
        backendRefs:
        - kind: MeshService
          name: example
          namespace: app
          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:

apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: http-route
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshGateway
    name: edge-gateway
  to:
  - targetRef:
      kind: Mesh
    rules:
    - matches:
      - path:
          type: PathPrefix
          value: "/"
      default:
        backendRefs:
        - kind: MeshService
          name: example-v1_app_svc_8080
  - targetRef:
      kind: Mesh
    hostnames:
    - dev.example.com
    rules:
    - matches:
      - path:
          type: PathPrefix
          value: "/"
      default:
        backendRefs:
        - kind: MeshService
          name: example-v2_app_svc_8080

apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: http-route
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshGateway
    name: edge-gateway
  to:
  - targetRef:
      kind: Mesh
    rules:
    - matches:
      - path:
          type: PathPrefix
          value: "/"
      default:
        backendRefs:
        - kind: MeshService
          name: example-v1
          namespace: app
          port: 8080
  - targetRef:
      kind: Mesh
    hostnames:
    - dev.example.com
    rules:
    - matches:
      - path:
          type: PathPrefix
          value: "/"
      default:
        backendRefs:
        - kind: MeshService
          name: example-v2
          namespace: app
          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.

apiVersion: kuma.io/v1alpha1
kind: MeshTCPRoute
metadata:
  name: tcp-route
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshGateway
    name: edge-gateway
  to:
  - targetRef:
      kind: Mesh
    rules:
    - default:
        backendRefs:
        - kind: MeshService
          name: example-v1_app_svc_8080
          weight: 90
        - kind: MeshService
          name: example-v2_app_svc_8080
          weight: 10

apiVersion: kuma.io/v1alpha1
kind: MeshTCPRoute
metadata:
  name: tcp-route
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshGateway
    name: edge-gateway
  to:
  - targetRef:
      kind: Mesh
    rules:
    - default:
        backendRefs:
        - kind: MeshService
          name: example-v1
          namespace: app
          port: 8080
          weight: 90
        - kind: MeshService
          name: example-v2
          namespace: app
          port: 8080
          weight: 10