You are browsing documentation for an older version. See the latest documentation here.

Using Expression Based Router

This feature is released as a tech preview (alpha-quality) and should not be depended upon in a production environment.

The expression-based routers, introduced in Kong Gateway 3.0, have higher performance and allow more precise priority specification than the traditional router. By using the expression-based router, Kong Ingress Controller can reduce most of generated routes with regular expression match on path, and therefore improve the performance of the router.

This page explains how Kong Ingress Controller can use the expression-based router, and the supported features and limitations of the current version.

Install Kong Ingress Controller with a Kong Gateway expression-based router

To install Kong Ingress Controller with a Kong Gateway expression-based router, you must configure environment variables in the container of Kong Ingress Controller and Kong Gateway.

Prerequisites

• Kong Ingress Controller 2.10.x or later
• Kong Gateway 3.0.x or later

Instructions

For Kong Ingress Controller, you must enable ExpressionRoutes and CombinedRoutes (enabled by default) so Kong Ingress Controller can translate Kubernetes resources to expression-based Kong Gateway routes. For Kong Gateway, you must configure KONG_ROUTER_FLAVOR for expressions to use expression-based router.

You can use the following values.yaml to install Kong Ingress Controller using the expression-based router by helm:

image:
  repository: kong
  tag: "3.3" # 3.0 or later

env:
  database: "off"
  router_flavor: "expressions" # sets KONG_ROUTER_FLAVOR to "expressions"

ingressController:
  enabled: true
  image:
    repository: kong/kubernetes-ingress-controller
    tag: "2.10" # 2.10 or later
  env:
    feature_gates: "ExpressionRoutes=true" # enables the "ExpressionRoutes" feature gate

Then, use Helm to install Kong Gateway:

  helm upgrade --install controller kong/kong -n kong --create-namespace -f values.yaml

Kubernetes resource support

The following table displays which Kubernetes resources are supported when translating to expression-based routes is enabled in Kong Ingress Controller:

Unsupported methods of overriding routes

Because Kubernetes objects can’t fully express Kong Gateway configuration specifications, Kong Ingress Controller provides methods to override services, routes, plugins, consumers, and other objects in Kong Gateway configurations after translating from Kubernetes objects. These methods include overriding using the KongIngress resource and annotations of resources. When the expression-based router is enabled, some of the methods of overriding routes in Kong Gateway configurations after translating are not supported:

• Overriding routes in Kong Gateway configurations using KongIngress isn’t supported when expression routes is enabled. The route fields of KongIngress resources will be ignored when Kong Ingress Controller translates Kubernetes resources to expression based routes.
• You can’t override Ingress with the konghq.com/path_handling and konghq.com/regex_priority annotations because the path_handling and regex_priority fields are not supported in Kong Gateway route configurations when Kong Gateway is running the expressions router.
• For HTTPRoute and GRPCRoute, the konghq.com/path_handling and konghq.com/regex_priority annotations aren’t supported for the same reason. Besides this, the konghq.com/host_aliases, konghq.com/methods, and konghq.com/headers annotations can’t be used to override hosts, methods, and headers.

Other unsupported features and breaking changes

• HTTPS redirect isn’t supported by the Kong Gateway expression-based router yet.
• The current translator assigns the same priority to all translated routes. When there are multiple route that match the request, the chosen route may be different than if you were using a traditional router.
• The standard of regular expressions changed to regex in Rust for the expression-based router (instead of PCRE2 in the traditional router), so previously valid regex may become invalid if you enable the expression-based router. For example, a non-escape character after \ like \/, \j becomes invalid in the regex of the expression-based router.