You are browsing documentation for an outdated 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.
- Kong Ingress Controller 2.10.x or later
- Kong Gateway 3.0.x or later
For Kong Ingress Controller, you must enable
CombinedRoutes (enabled by default) so Kong Ingress Controller can translate Kubernetes resources to expression-based
Kong Gateway routes. For Kong Gateway, you must configure
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:
tag: "3.3" # 3.0 or later
router_flavor: "expressions" # sets KONG_ROUTER_FLAVOR to "expressions"
tag: "2.10" # 2.10 or later
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/regex_priority annotations because the
regex_priority fields are not supported in Kong Gateway route configurations when Kong Gateway is running the
konghq.com/regex_priority annotations aren’t supported for the same reason. Besides this, the
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
\j becomes invalid in the regex of the expression-based router.