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