このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
About Expressions Language
With the release of version 3.0, Kong Gateway now includes a rule based engine using a domain-specific expressions language. Expressions can be used to perform tasks such as defining complex routing logic that were previously not possible with the pre-3.0 era router. This guide is a reference for the expressions language and explains how it can be used.
About the expressions language
The expressions language is a strongly typed Domain-Specific Language (DSL) that allows you to define comparison operations on various input data. The results of the comparisons can be combined with logical operations, which allows complex routing logic to be written while ensuring good runtime matching performance.
Key concepts
-
Field: The field contains value extracted from the incoming request. For example,
the request path or the value of a header field. The field value could also be absent
in some cases. An absent field value will always cause the predicate to yield
false
no matter the operator. The field always displays to the left of the predicate. - Constant value: The constant value is what the field is compared to based on the provided operator. The constant value always displays to the right of the predicate.
- Operator: An operator defines the desired comparison action to be performed on the field against the provided constant value. The operator always displays in the middle of the predicate, between the field and constant value.
-
Predicate: A predicate compares a field against a pre-defined value using the provided operator and
returns
true
if the field passed the comparison orfalse
if it didn’t. - Route: A route is one or more predicates combined together with logical operators.
- Router: A router is a collection of routes that are all evaluated against incoming requests until a match can be found.
- Priority: The priority is a positive integer that defines the order of evaluation of the router. The bigger the priority, the sooner a route will be evaluated. In the case of duplicate priority values between two routes in the same router, their order of evaluation is undefined.
A predicate is structured like the following:
http.path ^= "/foo/bar"
This predicate example has the following structure:
-
http.path
: Field -
^=
: Operator -
"/foo/bar"
: Constant value
How routes are executed
At runtime, Kong Gateway builds two separate routers for the HTTP and Stream (TCP, TLS, UDP) subsystem.
Routes are inserted into each router with the appropriate priority
field set. The router is
updated incrementally as configured routes change.
When a request/connection comes in, Kong Gateway looks at which field your configured routes require,
and supplies the value of these fields to the router execution context. This is evaluated against
the configured routes in descending order (routes with a higher priority
number are evaluated first).
As soon as a route yields a match, the router stops matching and the matched route is used to process the current request/connection.
Figure 1: Diagram of how Kong Gateway executes routes. The diagram shows that Kong Gateway selects the route that both matches the expression and then selects the matching route with the highest priority.
Expression router examples (HTTP)
Prefix based path matching
Prefix based path matching is one of the most commonly used methods for routing. For example, if you want to match HTTP requests that have a path starting with /foo/bar
, you can write the following route:
http.path ^= "/foo/bar"
Regex based path matching
If you prefer to match a HTTP requests path against a regex, you can write the following route:
http.path ~ r#"/foo/bar/\d+"#
Case insensitive path matching
If you want to ignore case when performing the path match, use the lower()
modifier on the field
to ensure it always returns a lowercase value:
lower(http.path) == "/foo/bar"
This will match requests with a path of /foo/bar
and /FOO/bAr
, for example.
Match by header value
If you want to match incoming requests by the value of header X-Foo
, do the following:
http.headers.x_foo ~ r#"bar\d"#
If there are multiple header values for X-Foo
and the client sends more than
one X-Foo
header with different value, the above example will ensure each instance of the
value will match the regex r#"bar\d"#
. This is called “all” style matching, meaning each instance
of the field value must pass the comparison for the predicate to return true
. This is the default behavior.
If you do not want this behavior, you can turn on “any” style of matching which returns
true
for the predicate as soon as any of the values pass the comparison:
any(http.headers.x_foo) ~ r#"bar\d"#
This will return true
as soon as any value of http.headers.x_foo
matches regex r#"bar\d"#
.
Different transformations can be chained together. The following is also a valid use case that performs case-insensitive matching:
any(lower(http.headers.x_foo)) ~ r#"bar\d"#
Regex captures
You can define regex capture groups in any regex operation which will be made available
later for plugins to use. Currently, this is only supported with the http.path
field:
http.path ~ r#"/foo/(?P<component>.+)"#
The matched value of component
will be made available later to plugins such as
Request Transformer Advanced.
Expression router examples (TCP, TLS, UDP)
Match by source IP and destination port
net.src.ip in 192.168.1.0/24 && net.dst.port == 8080
This matches all clients in the 192.168.1.0/24
subnet and the destination port (which is listened to by Kong)
is 8080
. IPv6 addresses are also supported.
Match by SNI (for TLS routes)
tls.sni =^ ".example.com"
This matches all TLS connections with the .example.com
SNI ending.
More information
- Language References - Once you are familiar with the expression router basics, see this documentation to understand everything the expressions language has to provide.
- How to configure Routes using Expressions. - Learn how to configure routes using expressions as well as which fields are available.
- Performance - Understand performance characteristics when using the expressions router and how to optimize your routes.
- Expressions repository