diff --git a/app/_src/gateway/key-concepts/routes/expressions.md b/app/_src/gateway/key-concepts/routes/expressions.md index 75641f68f98e..75893abee253 100644 --- a/app/_src/gateway/key-concepts/routes/expressions.md +++ b/app/_src/gateway/key-concepts/routes/expressions.md @@ -3,22 +3,21 @@ title: How to Configure Routes using Expressions content-type: how-to --- -Configuring routes using Expressions allows for more flexibility and performance -when dealing with complex or large sized configurations. -This how-to guide will walk through switching to the Expressions router, and configuring routes with the new expressive domain specific language. -Please be sure to familiar yourself with the [Expressions Language Reference](/gateway/latest/reference/expressions-language/overview/) -before processing through the rest of this guide. +Configuring routes using expressions allows for more flexibility and better performance +when dealing with complex or large configurations. +This how-to guide explains how to switch to the expressions router and how to configure routes with the new expressive domain specific language. +Familiar yourself with the [Expressions Language Reference](/gateway/latest/reference/expressions-language/) +before proceeding through the rest of this guide. -## Prerequisite +## Prerequisites -Edit [kong.conf](/gateway/latest/production/kong-conf/) to contain the line `router_flavor = expressions` and restart {{site.base_gateway}}. -> **Note:** Once you enable expressions, the match fields that traditionally exist on the Route object (such as `paths`, `methods`) will no longer - be configurable and you must specify Expressions in the `expression` field. A new field `priority` will be made available - that allows specifying the order of evaluation of configured Expression routes. +Edit the [kong.conf](/gateway/latest/production/kong-conf/) to contain the line `router_flavor = expressions` and restart {{site.base_gateway}}. +{:.note} +> **Note:** Once you enable expressions, the match fields that traditionally exist on the route object (such as `paths` and `methods`) will no longer be configurable and you must specify Expressions in the `expression` field. A new field `priority` will be made available that allows specifying the order of evaluation of configured Expression routes. -## Create routes with Expressions +## Create routes with expressions -To create a new Route object using expressions, send a `POST` request to the [services endpoint](/gateway/latest/admin-api/#update-route) like this: +To create a new route object using expressions, send a `POST` request to the [services endpoint](/gateway/latest/admin-api/#update-route): ```sh curl --request POST \ --url http://localhost:8001/services/example-service/routes \ @@ -26,7 +25,7 @@ curl --request POST \ ``` In this example, you associated a new route object with the path `/mock` to the existing service `example-service`. -The Expressions DSL also allows you to create complex router match conditions. +The Expressions DSL also allows you to create complex router match conditions: ```sh curl --request POST \ @@ -35,9 +34,9 @@ curl --request POST \ --form-string 'expression=(http.path == "/mock" || net.protocol == "https")' ``` -### Create complex routes with Expressions +### Create complex routes with expressions -You can describe complex route objects using operators within a `POST` request. +You can describe complex route objects using operators within a `POST` request: ```sh @@ -52,30 +51,30 @@ curl --request POST \ http.headers.x_another_header == "example_header" && (http.headers.x_my_header == "example" || http.headers.x_my_header == "example2")' ``` -Please refer to the [Expressions Language Quickstart](/gateway/latest/reference/expressions-language/quickstart/#examples-http) page for common use cases -and how to write Expressions route for them. +See the [expressions language overview](/gateway/latest/reference/expressions-language/) page for common use cases +and how to write expressions routes for them. -For a list of all available language features, see the [Expressions Language References](/gateway/latest/reference/expressions-language/language-references/). +For a list of all available language features, see the [expressions language reference](/gateway/latest/reference/expressions-language/language-references/). ## Matching fields -Here are the available matching fields, as well as their associated type when using Expressions based router. +The following table describes the available matching fields, as well as their associated type when using an expressions based router. | Field | Type | Available in HTTP Subsystem | Available in Stream Subsystem | Description | |---------------------------------------|------------|-----------------------------|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `net.protocol` | `String` | ✅ | ✅ | Protocol of the route. Roughly equivalent to the `protocols` field on the `Route` entity. **Note:** Configured `protocols` on the `Route` entity are always added to the top level of the generated route but additional constraints can be provided by using the `net.prococol` field directly inside the expression. | | `tls.sni` | `String` | ✅ | ✅ | If the connection is over TLS, the `server_name` extention from the ClientHello packet. | -| `http.method` | `String` | ✅ | ❌ | The method of the incoming HTTP request. (e.g. `"GET"`, `"POST"`) | +| `http.method` | `String` | ✅ | ❌ | The method of the incoming HTTP request. (for example, `"GET"` or `"POST"`) | | `http.host` | `String` | ✅ | ❌ | The `Host` header of the incoming HTTP request. | | `http.path` | `String` | ✅ | ❌ | The normalized request path. This field value does **not** contain any query parameters that might exist. | -| `http.headers.` | `String[]` | ✅ | ❌ | The value(s) of request header ``. **Note:** The header name is always normalized to the underscore and lowercase form, so `Foo-Bar`, `Foo_Bar` and `fOo-BAr` all becomes value of the `http.headers.foo_bar` field. | +| `http.headers.` | `String[]` | ✅ | ❌ | The value(s) of request header ``. **Note:** The header name is always normalized to the underscore and lowercase form, so `Foo-Bar`, `Foo_Bar`, and `fOo-BAr` all become values of the `http.headers.foo_bar` field. | | `http.queries.` | `String[]` | ✅ | ❌ | The value(s) of query parameter ``. | | `net.src.ip` | `IpAddr` | ❌ | ✅ | IP address of the client. | -| `net.src.port` | `Int` | ❌ | ✅ | The port number using by the client to connect. | -| `net.dst.ip` | `IpAddr` | ❌ | ✅ | Listening IP address where Kong accepted the incoming connection. | -| `net.dst.port` | `Int` | ❌ | ✅ | Listening port number where Kong accepted the incoming connection. | +| `net.src.port` | `Int` | ❌ | ✅ | The port number used by the client to connect. | +| `net.dst.ip` | `IpAddr` | ❌ | ✅ | Listening IP address where {{site.base_gateway}} accepted the incoming connection. | +| `net.dst.port` | `Int` | ❌ | ✅ | Listening port number where {{site.base_gateway}} accepted the incoming connection. | ## More information -* [Expressions Language Reference](/gateway/latest/reference/expressions-language/overview/) +* [Expressions Language Reference](/gateway/latest/reference/expressions-language/) * [Repository for the Expressions router engine](https://github.com/Kong/atc-router) diff --git a/app/_src/gateway/key-concepts/routes/index.md b/app/_src/gateway/key-concepts/routes/index.md index 9f513d3c79f7..9ae6a605d423 100644 --- a/app/_src/gateway/key-concepts/routes/index.md +++ b/app/_src/gateway/key-concepts/routes/index.md @@ -98,7 +98,7 @@ to route a request, the latency introduced by {{site.base_gateway}} can suffer and its CPU usage can increase. In installations with thousands of routes, replacing regular expression routes by simple prefix routes can improve throughput and latency of -{{site.base_gateway}}. If regex must be used due to exact +{{site.base_gateway}}. If regex must be used because an exact path match must be performed, using the [expressions router](expressions) will significantly improve {{site.base_gateway}}'s performance in this case. @@ -119,7 +119,7 @@ Routes can be configured dynamically to rewrite the requested URL to a different {{site.base_gateway}} can also handle more complex URL rewriting cases by using regular expression capture groups in the route path and the [Request Transformer Advanced](/hub/kong-inc/request-transformer-advanced/) plugin. For example, this can be used when you must replace `/api//old` with `/new/api/`. -{{site.base_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](/gateway/{{page.kong_version}}/key-concepts/routes/expressions/). +{{site.base_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](/gateway/{{page.kong_version}}/key-concepts/routes/expressions/). ## Plugins for routes diff --git a/app/_src/gateway/reference/expressions-language/language-references.md b/app/_src/gateway/reference/expressions-language/language-references.md index 4fe16de3c267..be43009e5ca4 100644 --- a/app/_src/gateway/reference/expressions-language/language-references.md +++ b/app/_src/gateway/reference/expressions-language/language-references.md @@ -155,7 +155,7 @@ This operator is used to check the existence of a string inside another string. For example, `http.path contains "foo"` will return `true` if `foo` can be found anywhere inside `http.path`. This will match a `http.path` that looks like `/foo`, `/abc/foo`, or `/xfooy`, for example. -### Type/operator semantics +### Type and operator semantics Here are the allowed combination of field types and constant types with each operator: diff --git a/app/_src/gateway/reference/expressions-language/performance.md b/app/_src/gateway/reference/expressions-language/performance.md index 521cf8c665c7..8d20917837be 100644 --- a/app/_src/gateway/reference/expressions-language/performance.md +++ b/app/_src/gateway/reference/expressions-language/performance.md @@ -1,60 +1,60 @@ --- -title: Performance Optimizations +title: Expressions Performance Optimizations content-type: reference --- -Performance is critical when it comes to proxying API traffic. Learn how to optimize the -Expressions you write to get the most performance out of the routing engine. +Performance is critical when it comes to proxying API traffic. This guide explains how to optimize the +expressions you write to get the most performance out of the routing engine. ## Number of routes +### Route matching priority order + Expressions routes are always evaluated in the descending `priority` order they were defined. -Therefore, it is helpful to put more likely matched routes before (i.e. higher priority) +Therefore, it is helpful to put more likely matched routes before (as in, higher priority) less frequently matched routes. -### Examples +The following examples show how you would prioritize two routes based on if they were likely to be matched or not. -Route 1: +Example route 1: ``` -expression: http.path == "/very/hot/request/path" +expression: http.path == "/likely/matched/request/path" priority: 100 ``` -Route 2: +Example route 2: ``` -expression: http.path == "/not/so/hot/request/path" +expression: http.path == "/unlikely/matched/request/path" priority: 50 ``` -It is also desirable to reduce the number of `Route` entity created by leveraging the -logical combination capability of the Expressions language. +It's also best to reduce the number of `Route` entities created by leveraging the +logical combination capability of the expressions language. -### Examples +### Combining routes -If multiple routes results in the same `Service` and `Plugin` config being used, -they should be combined into a single Expression `Route` with logical or operator `||`: +If multiple routes result in the same `Service` and `Plugin` config being used, +they should be combined into a single expression `Route` with the `||` logical or operator. By combining routes into a single expression, this results in fewer `Route` objects created and better performance. -Route 1: +Example route 1: ``` service: example-service expression: http.path == "/hello" ``` -Route 2: +Example route 2: ``` service: example-service expression: http.path == "/world" ``` -Could instead be combined as: +These two routes can instead be combined as: ``` service: example-service expression: http.path == "/hello" || http.path == "/world" ``` -which results in less `Route` object created, and better performance. - ## Regular expressions usage Regular expressions (regexes) are powerful tool that can be used to match strings based on @@ -63,30 +63,28 @@ evaluate at runtime and hard to optimize. Therefore, there are some common scenarios where regex usages can be eliminated, resulting in significantly better matching performance. -### Examples - -When performing exact matches (non-prefix patches) of request path, use the `==` operator, -instead of regex: +When performing exact matches (non-prefix patches) of a request path, use the `==` operator +instead of regex. -**Fast:** +**Faster performance example:** ``` http.path == "/foo/bar" ``` -**Slow:** +**Slower performance example:** ``` http.path ~ r#"^/foo/bar$"# ``` -When performing exact matches with optional slash `/` at the end, it is tempting to write -regexes. However, this is completely unnecessary with the Expressions language: +When performing exact matches with the `/` optional slash at the end, it is tempting to write +regexes. However, this is completely unnecessary with the expressions language. -**Fast:** +**Faster performance example:** ``` http.path == "/foo/bar" || http.path == "/foo/bar/" ``` -**Slow:** +**Slower performance example:** ``` http.path ~ r#"^/foo/?$"# ```