From b5f34a0eb829b956b0a4bc479478690bd91915c7 Mon Sep 17 00:00:00 2001 From: Angel Date: Tue, 16 Aug 2022 13:04:54 -0400 Subject: [PATCH] [docu-2457] Router Reference, Router Route creation (#4251) * router reference * Check * Add Router doc and reference doc * vale * Apply suggestions from code review Co-authored-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * suggestions from code review Co-authored-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_data/docs_nav_gateway_3.0.x.yml | 4 + .../configure-services-and-routes.md | 15 +++ src/gateway/reference/router-operators.md | 66 +++++++++++++ .../understanding-kong/how-to/router-atc.md | 93 +++++++++++++++++++ 4 files changed, 178 insertions(+) create mode 100644 src/gateway/reference/router-operators.md create mode 100644 src/gateway/understanding-kong/how-to/router-atc.md diff --git a/app/_data/docs_nav_gateway_3.0.x.yml b/app/_data/docs_nav_gateway_3.0.x.yml index b8d915bc8e13..c885bcc077f7 100644 --- a/app/_data/docs_nav_gateway_3.0.x.yml +++ b/app/_data/docs_nav_gateway_3.0.x.yml @@ -25,6 +25,8 @@ items: url: /understanding-kong/how-to/request-transformations - text: Securing the Database with AWS Secrets Manager url: /understanding-kong/how-to/aws-secrets-manager + - text: Configure Routes with Expressions + url: /understanding-kong/how-to/router-atc - text: Key Concepts items: - text: Services @@ -561,3 +563,5 @@ items: url: /reference/rate-limit - text: Performance Testing Framework Reference url: /reference/performance-testing-framework + - text: Router Operators + url: /reference/router-operators diff --git a/src/gateway/get-started/configure-services-and-routes.md b/src/gateway/get-started/configure-services-and-routes.md index ba7796e0bf59..48eadd490645 100644 --- a/src/gateway/get-started/configure-services-and-routes.md +++ b/src/gateway/get-started/configure-services-and-routes.md @@ -149,11 +149,26 @@ The response body displays the updated change: You can configure a route to point to an active service. The router helps {{site.base_gateway}} forward requests to upstream services. Now, you will configure the `/mock` route for the `example_service` service. This route has a specific path that users will use to send requests. A route is configured by sending a **POST** request to the [route object](/gateway/latest/admin-api/#route-object): +{% if_version eq:3.0.x %} ```sh curl -i -X POST http://localhost:8001/services/example_service/routes \ --data 'paths[]=/mock' \ --data name=mocking ``` +{% endif_version %} + + +{% if_version gte:3.1.x %} +```sh +curl --request POST \ + --url http://localhost:8001/services/example-service/routes \ + --header 'Content-Type: multipart/form-data' \ + --form 'atc=http.path == "/mock"' + --data name=mocking +``` +{% endif_version %} + + If the route was successfully created, the API returns a `201` response code and a response body like this: diff --git a/src/gateway/reference/router-operators.md b/src/gateway/reference/router-operators.md new file mode 100644 index 000000000000..1fddaa5cb6ae --- /dev/null +++ b/src/gateway/reference/router-operators.md @@ -0,0 +1,66 @@ +--- +title: Router Operator Reference for Kong Gateway +content-type: reference +--- + +With the release of version 3.0, {{site.base_gateway}} now ships with a new router. The new router can describe routes using a domain-specific language called Expressions. Expressions can describe routes or paths as patterns using regular expressions. This document serves as a reference for all of the available operators. If you want to learn how to configure routes using Expressions read [How to configure routes using Expressions](gateway/latest/understanding-kong/how-to/router-atc/). + + +## Available fields + +| Field | Description | +| --- | ----------- | +| `net.protocol` | The protocol used to communicate with the upstream application. | +| `tls.sni` | Server name indication. | +| `http.method` | HTTP methods that match a route. | +| `http.host` | Lists of domains that match a route. | +| `http.path` | Returns or sets the path. | +| `http.raw_path` | Returns or sets the escaped path. | +| `http.headers.*` | Lists of values that are expected in the header of a request. | + +## String + +| Operator | Name | Return Type | +| --- | ----------- | --- | +| == | Equals | Boolean| +| != | Not equals | Boolean| +| ~ | Regex matching | Boolean| +| ^= | Prefix matching | Boolean| +| =^ | Suffix matching | Boolean| +| in | Contains | Boolean| +| not in | Does not contain | Boolean| +| lower() | Lowercase | String| + +## Integer + +| Operator | Name | Return Type | +| --- | ----------- | --- | +| == | Equals | Boolean| +| != | Not equals| Boolean| +| > | Greater than | Boolean| +| >= | Greater than or equal | Boolean| +| < | Less than | Boolean| +| <= | Less than or equal | Boolean| + +## IP + +| Operator | Name | Return Type | +| --- | ----------- | --- | +| == | Equals | Boolean| +| != | Not equals | Boolean| +| in | Contains | Boolean| + +## Boolean + +| Operator | Name | Return Type | +| --- | ----------- | --- | +| && | And | Boolean| +| `||` | Or | Boolean| +| ! | Not | Boolean| + + + +## More information + +* [Expressions repository](https://github.com/Kong/atc-router#table-of-contents) +* [How to configure routes using Expressions](gateway/latest/understanding-kong/how-to/router-atc/) \ No newline at end of file diff --git a/src/gateway/understanding-kong/how-to/router-atc.md b/src/gateway/understanding-kong/how-to/router-atc.md new file mode 100644 index 000000000000..12f06408498c --- /dev/null +++ b/src/gateway/understanding-kong/how-to/router-atc.md @@ -0,0 +1,93 @@ +--- +title: How to Configure Routes using Expressions +content-type: how-to +--- + + +Expressions can describe routes or paths as patterns using regular expressions. This how-to guide will walk through switching to the new router, and configuring routes with the new expressive domain specific language, expressions. For a list of all available operators and configurable fields please review the [reference documentation](/gateway/latest/reference/router-operators). + +## Prerequisite + +Edit [kong.conf](/gateway/latest/kong-production/kong-conf) to contain the line `router_flavor = expressions` and restart {{site.base_gateway}}. + +## Create routes with Expressions + +To create a new router object using expressions, send a `POST` request to the [services endpoint](/gateway/latest/admin-api/#update-route) like this: +```sh +curl --request POST \ + --url http://localhost:8001/services/example-service/routes \ + --form atc='http.path == "/mock" +``` + +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 objects using operators. + +```sh +curl --request POST \ + --url http://localhost:8001/services/example-service/routes \ + --header 'Content-Type: multipart/form-data' \ + --form 'atc=(http.path == "/mock" || net.protocol == "https")' +``` +In this example the || operator created an expression that set variables for the following fields: + +``` +"protocols": ["http", "https"] +AND +"paths": ["/mock"] +``` + +You can use attributes that are unrelated to expressions within the same `POST` request: + +```sh +curl --request POST \ + --url http://localhost:8001/services/example-service/routes \ + --header 'Content-Type: multipart/form-data' \ + --form 'atc=(http.path == "/mock" || net.protocol == "https") \ + --form name=mocking +``` + +This would define a router object with the following attributes: + + +``` +"atc": "(http.path == \"\/mock\" || net.protocol == \"https\"), +"name": "mocking", + +``` +You can view the list of available attributes in the [reference documentation](/gateway/latest/admin-api/#request-body). + + + +### Create complex routes with Expressions + +You can describe complex route objects using operators within a `POST` request. + +```sh + +curl --request POST \ + --url http://localhost:8001/services/example-service/routes \ + --header 'Content-Type: multipart/form-data' \ + --form name=complex_object \ + --form 'atc=(net.protocol == "http" || net.protocol == "https") && + (http.method == "GET" || http.method == "POST") && + (http.host == "example.com" || http.host == "example.test") && + (http.path ^= "/mock" || http.path ^= "/mocking") && + http.headers.x_another_header == "example_header" && (http.headers.x_my_header == "example" || http.headers.x_my_header == "example2")' +``` + +This request returns a `200` status code with the following values: + +```sh +"protocols": ["http", "https"], +"methods": ["GET", "POST"], +"hosts": ["example.com", "example.test"], +"paths": ["/mock", "/mocking"], +"headers": {"x-another-header":["example_header"], "x-my-header":["example", "example2"]}, +``` + +For a list of all available operators, see the [reference documentation](/gateway/latest/reference/router-operators/). + + +## More information + +* [Expressions repository](https://github.com/Kong/atc-router#table-of-contents) +* [Expressions Reference](/gateway/latest/reference/router-operators) \ No newline at end of file