Configuring built-in routes with MeshHTTPRoute and MeshTCPRoute

Uses: Kong Mesh

MeshHTTPRoute

Here’s an example of a MeshHTTPRoute resource:

apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: edge-gateway-route
  namespace: kong-mesh-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

Copied!

apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: edge-gateway-route
  namespace: kong-mesh-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

Copied!

I am using MeshService

type: MeshHTTPRoute
name: edge-gateway-route
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

Copied!

type: MeshHTTPRoute
name: edge-gateway-route
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
          port: 5000

Copied!

Adjust konnect_mesh_control_plane.my_meshcontrolplane.id and konnect_mesh.my_mesh.name according to your current configuration.

resource "konnect_mesh_http_route" "edge_gateway_route" {
  provider = konnect-beta
  type = "MeshHTTPRoute"
  name = "edge-gateway-route"
  spec = {
    target_ref = {
      kind = "MeshGateway"
      name = "edge-gateway"
      tags = {
        port = "http-8080"
      }
    }
    to = [
      {
        target_ref = {
          kind = "Mesh"
        }
        hostnames = [
           = "example.com"
        ]
        rules = [
          {
            matches = [
              {
                path = {
                  type = "PathPrefix"
                  value = "/"
                }
              }
            ]
            default = {
              backend_refs = [
                {
                  kind = "MeshService"
                  name = "demo-app"
                  port = "5000"
                }
              ]
            }
          }
        ]
      }
    ]
  }
  labels   = {
  "kuma.io/mesh" = konnect_mesh.my_mesh.name
  }
  cp_id    = konnect_mesh_control_plane.my_meshcontrolplane.id
  mesh     = konnect_mesh.my_mesh.name
}

Copied!

Listener hostname

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

Copied!

Along with the following MeshHTTPRoute rule:

I am using MeshService

apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: http-route
  namespace: kong-mesh-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

Copied!

apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: http-route
  namespace: kong-mesh-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

Copied!

I am using MeshService

type: MeshHTTPRoute
name: http-route
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

Copied!

type: MeshHTTPRoute
name: http-route
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
          port: 8080

Copied!

Adjust konnect_mesh_control_plane.my_meshcontrolplane.id and konnect_mesh.my_mesh.name according to your current configuration.

resource "konnect_mesh_http_route" "http_route" {
  provider = konnect-beta
  type = "MeshHTTPRoute"
  name = "http-route"
  spec = {
    target_ref = {
      kind = "MeshGateway"
      name = "edge-gateway"
      tags = {
        hostname = "wild"
      }
    }
    to = [
      {
        target_ref = {
          kind = "Mesh"
        }
        rules = [
          {
            matches = [
              {
                path = {
                  type = "PathPrefix"
                  value = "/"
                }
              }
            ]
            default = {
              backend_refs = [
                {
                  kind = "MeshService"
                  name = "example"
                  port = "8080"
                }
              ]
            }
          }
        ]
      }
    ]
  }
  labels   = {
  "kuma.io/mesh" = konnect_mesh.my_mesh.name
  }
  cp_id    = konnect_mesh_control_plane.my_meshcontrolplane.id
  mesh     = konnect_mesh.my_mesh.name
}

Copied!

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.

Route hostnames

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

I am using MeshService

apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: http-route
  namespace: kong-mesh-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

Copied!

apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: http-route
  namespace: kong-mesh-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

Copied!

I am using MeshService

type: MeshHTTPRoute
name: http-route
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
  - targetRef:
      kind: Mesh
    hostnames:
    - dev.example.com
    rules:
    - matches:
      - path:
          type: PathPrefix
          value: "/"
      default:
        backendRefs:
        - kind: MeshService
          name: example-v2

Copied!

type: MeshHTTPRoute
name: http-route
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
          port: 8080
  - targetRef:
      kind: Mesh
    hostnames:
    - dev.example.com
    rules:
    - matches:
      - path:
          type: PathPrefix
          value: "/"
      default:
        backendRefs:
        - kind: MeshService
          name: example-v2
          port: 8080

Copied!

Adjust konnect_mesh_control_plane.my_meshcontrolplane.id and konnect_mesh.my_mesh.name according to your current configuration.

resource "konnect_mesh_http_route" "http_route" {
  provider = konnect-beta
  type = "MeshHTTPRoute"
  name = "http-route"
  spec = {
    target_ref = {
      kind = "MeshGateway"
      name = "edge-gateway"
    }
    to = [
      {
        target_ref = {
          kind = "Mesh"
        }
        rules = [
          {
            matches = [
              {
                path = {
                  type = "PathPrefix"
                  value = "/"
                }
              }
            ]
            default = {
              backend_refs = [
                {
                  kind = "MeshService"
                  name = "example-v1"
                  port = "8080"
                }
              ]
            }
          }
        ]
      },
      {
        target_ref = {
          kind = "Mesh"
        }
        hostnames = [
           = "dev.example.com"
        ]
        rules = [
          {
            matches = [
              {
                path = {
                  type = "PathPrefix"
                  value = "/"
                }
              }
            ]
            default = {
              backend_refs = [
                {
                  kind = "MeshService"
                  name = "example-v2"
                  port = "8080"
                }
              ]
            }
          }
        ]
      }
    ]
  }
  labels   = {
  "kuma.io/mesh" = konnect_mesh.my_mesh.name
  }
  cp_id    = konnect_mesh_control_plane.my_meshcontrolplane.id
  mesh     = konnect_mesh.my_mesh.name
}

Copied!

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:

I am using MeshService

apiVersion: kuma.io/v1alpha1
kind: MeshTCPRoute
metadata:
  name: tcp-route
  namespace: kong-mesh-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

Copied!

apiVersion: kuma.io/v1alpha1
kind: MeshTCPRoute
metadata:
  name: tcp-route
  namespace: kong-mesh-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

Copied!

I am using MeshService

type: MeshTCPRoute
name: tcp-route
mesh: default
spec:
  targetRef:
    kind: MeshGateway
    name: edge-gateway
  to:
  - targetRef:
      kind: Mesh
    rules:
    - default:
        backendRefs:
        - kind: MeshService
          name: example-v1
          weight: 90
        - kind: MeshService
          name: example-v2
          weight: 10

Copied!

type: MeshTCPRoute
name: tcp-route
mesh: default
spec:
  targetRef:
    kind: MeshGateway
    name: edge-gateway
  to:
  - targetRef:
      kind: Mesh
    rules:
    - default:
        backendRefs:
        - kind: MeshService
          name: example-v1
          port: 8080
          weight: 90
        - kind: MeshService
          name: example-v2
          port: 8080
          weight: 10

Copied!

Adjust konnect_mesh_control_plane.my_meshcontrolplane.id and konnect_mesh.my_mesh.name according to your current configuration.

resource "konnect_mesh_tcp_route" "tcp_route" {
  provider = konnect-beta
  type = "MeshTCPRoute"
  name = "tcp-route"
  spec = {
    target_ref = {
      kind = "MeshGateway"
      name = "edge-gateway"
    }
    to = [
      {
        target_ref = {
          kind = "Mesh"
        }
        rules = [
          {
            default = {
              backend_refs = [
                {
                  kind = "MeshService"
                  name = "example-v1"
                  port = "8080"
                  weight = "90"
                },
                {
                  kind = "MeshService"
                  name = "example-v2"
                  port = "8080"
                  weight = "10"
                }
              ]
            }
          }
        ]
      }
    ]
  }
  labels   = {
  "kuma.io/mesh" = konnect_mesh.my_mesh.name
  }
  cp_id    = konnect_mesh_control_plane.my_meshcontrolplane.id
  mesh     = konnect_mesh.my_mesh.name
}

Copied!

Configuring built-in routes with MeshHTTPRoute and MeshTCPRoute

MeshHTTPRoute

Listener hostname

Route hostnames

`MeshTCPRoute`

Help us make these docs great!

Still need help?