Routes

Routes fulfill two responsibilities in Kong Gateway:

1. Match incoming requests and route them to the correct Gateway Service
2. Use plugins to transform the request/response proxied using this Route

A Route must be attached to a Gateway Service, and may have one or more plugins attached.

Routes, in conjunction with Gateway Services, let you expose upstream services to clients with Kong Gateway. Routes also allow the same client to access multiple applications and apply different policies based on the Route used.

For example, say you have two client applications that need to access the example_service Gateway Service: an internal client and an external client. The external client should be limited in how often it can query the Gateway Service to avoid a denial of service. If you apply a rate limit policy to the Gateway Service and the internal client calls it, the internal client is also limited. Routes can solve this problem.

In this example, you can create two Routes with different hosts to handle the two clients, say internal.example.com and external.example.com, and point both of them to example_service. You can configure a policy to limit how often the external Route is used. When the external client tries to access the Gateway Service via Kong Gateway using external.example.com, it’s rate limited. But when the internal client accesses the Gateway Service using Kong Gateway using internal.example.com, the internal client isn’t limited.

The following diagram illustrates this example:

Common use cases for Routes:

Kong Gateway provides two methods to define Routes: the traditional JSON format, and a more powerful DSL-based expressions format. The router used is configured via the router_flavor property in kong.conf.

The router you should use depends on your use case and Kong Gateway version:

• Expressions router: The recommended method for anyone running Kong Gateway 3.4.x or later. Handles complex routing logic efficiently.
• Traditional router: The original Kong Gateway routing configuration format. Provide your matching criteria in JSON format.

Setting router_flavor to expressions allows you to configure both expression based and JSON based routing criteria at the same time. If an expression Route matches, the JSON format router won’t run, regardless of the JSON priority set.

To disable the DSL-based format, set router_flavor to traditional_compat. Only JSON routes will be accepted with this configuration.

You can match incoming requests against the following routing criteria:

• Protocols: The protocol used to communicate with the upstream service
• Hosts: Lists of domains that match a Route
• Methods: HTTP methods that match a Route
• Headers: Lists of values that are expected in the header of a request
• Port: The request’s source/destination port
• SNI: The server name indicated in a TLS request

For detailed examples of each, see the dedicated expressions or traditional sections.

For each incoming request, Kong Gateway must determine which Gateway Service will handle it based on the Routes that are defined.

The Kong Gateway router orders all defined Routes by their priority and uses the highest priority matching Route to proxy the request.

Priority matching

To maximise performance, the Kong Gateway router orders all defined Routes by their priority and uses the highest priority matching Route to handle a request. How Routes are prioritized depends on the router mode you’re using.

For more information, see the detailed expressions or traditional sections.

Route behavior

The Route entity allows you to configure proxy behavior on a per route basis by setting the strip_path, preserve_host, and path_handling values.

In most cases, strip_path and preserve_host should be false (this is the default value), and path_handling should be set to v0.

strip_path

It may be desirable to specify a path prefix to match a Route, but not include it in the upstream request. To do so, use the strip_path boolean property by configuring a Route like so:

{
    "paths": ["/service"],
    "strip_path": true,
    "service": {
        "id": "..."
    }
}

Enabling this flag instructs Kong Gateway that when matching this Route, and proceeding with the proxying to a service, it should not include the matched part of the URL path in the upstream request’s URL. For example, the following client’s request to the above Route:

GET /service/path/to/resource HTTP/1.1
Host: ...

This causes Kong Gateway to send the following upstream request:

GET /path/to/resource HTTP/1.1
Host: ...

The same way, if a regex path is defined on a Route that has strip_path enabled, the entirety of the request URL matching sequence will be stripped. For example:

{
    "paths": ["/version/\d+/service"],
    "strip_path": true,
    "service": {
        "id": "..."
    }
}

The following HTTP request matching the provided regex path:

GET /version/1/service/path/to/resource HTTP/1.1
Host: ...

Is proxied upstream by Kong Gateway as:

GET /path/to/resource HTTP/1.1
Host: ...

preserve_host

When proxying, Kong Gateway’s default behavior is to set the upstream request’s Host header to the hostname specified in the Gateway Service’s host. The preserve_host field accepts a boolean flag instructing Kong Gateway not to do so.

For example, when the preserve_host property is not changed and a Route is configured like so:

{
    "hosts": ["service.com"],
    "service": {
        "id": "..."
    }
}

A possible request from a client to Kong Gateway could be:

GET / HTTP/1.1
Host: service.com

Kong Gateway would extract the Host header value from the Service’s host property, and would send the following upstream request:

GET / HTTP/1.1
Host: <my-service-host.com>

However, by explicitly configuring a Route with preserve_host=true:

{
    "hosts": ["service.com"],
    "preserve_host": true,
    "service": {
        "id": "..."
    }
}

And assuming the same request from the client:

GET / HTTP/1.1
Host: service.com

Kong Gateway would preserve the Host on the client request and would send the following upstream request instead:

GET / HTTP/1.1
Host: service.com

path_handling

The path_handling parameter accepts v0 or v1.

• v0 is the behavior used in Kong 0.x, 2.x, and 3.x. It treats service.path, route.path and request path as segments of a URL. It will always join them via slashes. Given a Service path /s, Route path /r and request path /re, the concatenated path will be /s/re. If the resulting path is a single slash, no further transformation is done to it. If it’s longer, then the trailing slash is removed.

• v1 is the behavior used in Kong 1.x. It treats service.path as a prefix, and ignores the initial slashes of the request and Route paths. Given Service path /s, Route path /r and request path /re, the concatenated path will be /sre.

path_handling v1 is not supported in the expressions router and may be removed in a future version of Kong Gateway. We strongly recommend using v0.

Both versions of the algorithm detect “double slashes” when combining paths, replacing them by single slashes.

Routing performance recommendations

You can use the following recommendations to increase routing performance:

• In expressions mode, we recommend putting more likely matched Routes before (as in, higher priority) those that are less frequently matched.
• Regular expressions in Routes use more resources to evaluate than simple prefixes. In installations with thousands of Routes, replacing a regular expression with simple prefix can improve throughput and latency of Kong Gateway. If a regex must be used because an exact path match must be performed, using the expressions router will significantly improve Kong Gateway’s performance in this case.

The Routes entity can dynamically serve TLS certificates on a per-connection basis. TLS certificates are managed by two resources:

• Certificates
• SNIs

To do this, create a Certificate associated with an SNI, and then create a secure Route that uses the Certificate:

_format_version: "3.0"
routes:
  - name: example-route
    host: "*.tls-example.com"
    protocol:
    - https
    - tls
    paths:
    - "/mock"
    snis:
    - my-sni

curl -i -X POST http://localhost:8001/routes/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "example-route",
      "host": "*.tls-example.com",
      "protocol": [
        "https",
        "tls"
      ],
      "paths": [
        "/mock"
      ],
      "snis": [
        "my-sni"
      ]
    }
    '

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/routes/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "example-route",
      "host": "*.tls-example.com",
      "protocol": [
        "https",
        "tls"
      ],
      "paths": [
        "/mock"
      ],
      "snis": [
        "my-sni"
      ]
    }
    '

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-route
  annotations:
    konghq.com/strip-path: 'true'
spec:
  parentRefs:
  - name: kong
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /mock
    backendRefs:
    - name: example-route-demo-service
      kind: Service
      port: 1027

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

resource "konnect_gateway_route" "my_route" {
  host = "*.tls-example.com"
  protocol = ["https", "tls"]
  paths = ["/mock"]
  snis = ["my-sni"]

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

In this case, the Certificate is already associated with the SNI, so by default it will apply to the Route. Alternatively you can use an SNI Wildcard with the Certificate to automatically apply it to the existing Route.

Proxying TLS passthrough traffic

Kong Gateway supports TLS passthrough. Kong Gateway uses the connecting SNI extension to find the matching Route and Service when forwarding a TLS request upstream. The Route configuration to proxy TLS traffic is unique to every deployment, but the two main configuration variables are:

• Create a Route with the tls_passthrough protocol and assign an SNI.
• Create a Service, associated with the Route, with the protocol set to tcp.