← Gateway Entities

Routes

Uses: Kong Gateway decK KIC Terraform

What is a route?

A route is a path to a resource within an upstream application. Services can store collections of objects like plugin configurations, and policies, and they can be associated with routes. In Kong Gateway, routes typically map to endpoints that are exposed through the Kong Gateway application. Routes can also define rules that match requests to associated services. Because of this, one route can reference multiple endpoints. A basic route should have a name, path or paths, and reference an existing service.

You can also configure routes with:

Protocols: The protocol used to communicate with the upstream application.
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
Redirect status codes: HTTPS status codes
Tags: Optional set of strings to group routes with

Route and service interaction

Routes, in conjunction with services, let you expose your services to applications with Kong Gateway. Kong Gateway abstracts the service from the applications by using routes. Since the application always uses the route to make a request, changes to the services, like versioning, don’t impact how applications make the request. Routes also allow the same service to be used by multiple applications and apply different policies based on the route used.

For example, if you have an external application and an internal application that need to access the example_service service, but the external application should be limited in how often it can query the service to assure no denial of service. If a rate limit policy is configured for the service when the internal application calls the service, the internal application is limited as well. Routes can solve this problem.

In the example above, two routes can be created, say /external and /internal, and both routes can point to example_service. A policy can be configured to limit how often the /external route is used and the route can be communicated to the external client for use. When the external client tries to access the service via Kong Gateway using /external, they are rate limited. But when the internal client accesses the service using Kong Gateway using /internal, the internal client will not be limited.

Dynamically rewrite request URLs with routes

Routes can be configured dynamically to rewrite the requested URL to a different URL for the upstream. For example, your legacy upstream endpoint may have a base URI like /api/old/. However, you want your publicly accessible API endpoint to now be named /new/api. To route the service’s upstream endpoint to the new URL, you could set up a service with the path /api/old/ and a route with the path /new/api.

Kong Gateway can also handle more complex URL rewriting cases by using regular expression capture groups in the route path and the Request Transformer Advanced plugin. For example, this can be used when you must replace /api/<function>/old with /new/api/<function>.

Kong Gateway 3.0.x or later ships with a new router. The new router can use regex expression capture groups to describe routes using a domain-specific language called Expressions. Expressions can describe routes or paths as patterns using regular expressions. For more information about how to configure the router using Expressions, see How to configure routes using expressions.

Schema

Set up a Route

The following creates a new route called example-route with basic configuration:

_format_version: '3.0'
routes:
  - name: example-route
    paths:
    - "/mock"

To create a route, call the Admin API’s /routes endpoint.

curl -X POST http://localhost:8001/routes/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "example-route",
      "paths": [
        "/mock"
      ]
    }
    '

To create a route, call the Konnect control plane config API’s /routes endpoint.

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",
      "paths": [
        "/mock"
      ]
    }
    '

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.

See the Konnect API reference to learn about region-specific URLs and personal access tokens.

Routes are defined using native Kubernetes resources such as Ingress and HTTPRoute. This example uses HTTPRoute, but you can also use Ingress if needed. See the Kong Ingress Controller documentation for Ingress docs.

To create a route in Kong Gateway, create a HTTPRoute resource that points to a service in your cluster:

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

Prerequisite: Configure your Personal Access Token

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" {
  paths = ["/mock"]

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}