Routes entity page, router expressions, proxying #168

cloudjumpercat · 2024-12-10T22:00:58Z

TODO

Preview Links

Checklist

Every page is page one
Tested how-to docs. If not, note why here.
All pages contain metadata
Updated sources.yaml. For more info review track docs changes
Any new docs link to existing docs.

Signed-off-by: Diana <[email protected]>

netlify · 2024-12-10T22:01:45Z

✅ Deploy Preview for kongdeveloper ready!

Name	Link
🔨 Latest commit	`1def049`
🔍 Latest deploy log	https://app.netlify.com/sites/kongdeveloper/deploys/676458bac664ce0008bc80cf
😎 Deploy Preview	https://deploy-preview-168--kongdeveloper.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

Signed-off-by: Diana <[email protected]>

lena-larionova

Some minor adjustments - I was working on the "Services" page and realized this section moved to "Routes", so just adding my edits from that.

app/_gateway_entities/route.md

Co-authored-by: lena-larionova <[email protected]>

Signed-off-by: Diana <[email protected]>

app/gateway/traffic-control/proxy.md

Signed-off-by: Diana <[email protected]>

cloudjumpercat · 2024-12-16T20:32:03Z

app/_gateway_entities/route.md

+When the external application tries to access the Service via {{site.base_gateway}} using `/external`, they're rate limited. 
+But when the internal application accesses the Service using {{site.base_gateway}} using `/internal`, the internal application isn't limited.
+
+## How routing works


For reviewers: I added routing here and removed the existing routing standalone page. My thinking, routing made the most sense in context with routes. I think it would be difficult to create something more than a very basic route without understanding routing, so in the spirit of every page is page one, I added it here.

But I did wonder if it should be a standalone page still and this section could be an include.

cloudjumpercat · 2024-12-16T20:33:44Z

app/_gateway_entities/route.md

+* In `expressions` mode, we recommend putting more likely matched Routes before (as in, higher priority) those that are less frequently matched.
+* Regular expressions in Routes use more resources to evaluate than simple prefixes. In installations with thousands of Routes, replacing regular expression with simple prefix can improve throughput and latency of {{site.base_gateway}}. If regex must be used because an exact path match must be performed, using the [expressions router](/gateway/routing/expressions/) will significantly improve {{site.base_gateway}}’s performance in this case.
+
+## Route use cases


For reviewers: should this be bumped up the page?

I would say yes

app/_how-tos/dynamically-rewrite-simple-request-urls-with-routes.md

cloudjumpercat · 2024-12-16T20:38:50Z

app/gateway/traffic-control/proxy.md

+
+{{ page.description }} This page details information about how {{site.base_gateway}} handles proxying. The following diagram shows how proxying is handled by {{site.base_gateway}}:
+
+{% mermaid %}


For reviewers: I used ChatGPT help on this diagram, but I revised everything and the input I provided it was the ordered list below this diagram. Still, I'd like a review for tech accuracy, especially the parts about the load balancer. I think ChatGPT got it wrong, so I made some changes to that part and wanted to confirm that I did them correctly.

cloudjumpercat · 2024-12-16T20:41:42Z

app/gateway/traffic-control/proxy.md

@@ -0,0 +1,191 @@
+---
+title: Proxying with {{site.base_gateway}}


For reviewers: Is this too much info for the proxying page? Should proxying just contain info about proxying and the connective parts (ex. listeners, routing, plugins, etc) should go on a traffic control landing page with proxying as another card/section instead? This is similar to what we had in the offsite proxy branch: main...proxy-reference#diff-8922116eb8441698da97efe2beeb185fb024118f8add77981f8eeb930867bbc6

I thought listeners, etc. could be helpful on this page to understanding proxying, but wasn't sure if others felt it was out of place.

cloudjumpercat · 2024-12-16T21:03:24Z

app/gateway/traffic-control/proxy.md

+  Kong's configuration capabilities: the **Admin API** (`8001` by default).
+    {:.important}
+   > **Important**: If you need to expose the `admin_listen` port to the internet in a production environment,
+   > {% if_version lte:2.8.x %}[secure it with authentication](/gateway/{{include.release}}/admin-api/secure-admin-api/).{% endif_version %}{% if_version gte:3.0.x %}[secure it with authentication](/gateway/{{include.release}}/production/running-kong/secure-admin-api/).{% endif_version %}


For reviewers: I couldn't find the Admin API in the dev site, does anyone have a link to it?

cloudjumpercat · 2024-12-16T21:04:00Z

app/gateway/traffic-control/proxy.md

+1. If multiple Routes match, the {{site.base_gateway}} router then orders all defined Routes by their priority and uses the highest priority matching Route to handle a request.
+1. If a given request matches the rules of a specific route, {{site.base_gateway}} will
+run any global, Route, or Service [plugins]() before it proxies the request. They are run in the following order: Route, Service <!--when does the global config get run?--> These configured plugins will run their `access` phase, which you can find more
+information about in the [Plugin development guide][plugin-development-guide].


For reviewers: I don't think we added the autogenerated PDK yet. How do we want to handle links to autogenerated pages?

Signed-off-by: Diana <[email protected]>

Guaris · 2024-12-16T22:27:19Z

app/_how-tos/dynamically-rewrite-simple-request-urls-with-routes.md

+products:
+    - gateway
+
+works_on:


Since it works on both can the platform be agnostic?

app/_how-tos/dynamically-rewrite-simple-request-urls-with-routes.md

Guaris · 2024-12-17T16:45:31Z

app/_how-tos/dynamically-rewrite-simple-request-urls-with-routes.md

+Now you can create a Route with your new path, `/new-path`, that points to the new Upstream.
+


This adds a second route and associates it to the service. So by this point you have:
1 service pointing to the upstream url http://httpbin.konghq.com/anything
2. routes proxying to it, one at /anything, and one at /new-path.
3. And an optional stray route from the prereq

sorry, i left this undone, you should remove the original /anything route

I've removed the original route.

Guaris · 2024-12-17T16:47:10Z

app/_how-tos/dynamically-rewrite-simple-request-urls-with-routes.md

+To validate that the URL was successfully rewritten and the request is now being matched to the new Upstream instead of the old one, run the following:
+
+```bash
+curl -i http://localhost:8000/new-path


I think a better test would be seeing what URL you are getting from the old path, and from the new one.

@Guaris I like this idea. I think the idea is that traffic is routed away from the old path to the new one, like a redirect (let me know if this is wrong), so if you go to the old path, should it redirect you to the new path?

@Guaris I think this is working correctly with http://localhost:8000/new-path as this is the response I get:

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 486 Connection: keep-alive Server: gunicorn/19.9.0 Date: Wed, 18 Dec 2024 21:14:18 GMT Access-Control-Allow-Origin: * Access-Control-Allow-Credentials: true X-Kong-Upstream-Latency: 352 X-Kong-Proxy-Latency: 488 Via: 1.1 kong/3.9.0.0-enterprise-edition X-Kong-Request-Id: 0bfd8c4c54274e4ffbbfcd2c5c939c65 { "args": {}, "data": "", "files": {}, "form": {}, "headers": { "Accept": "*/*", "Connection": "keep-alive", "Host": "httpbin.konghq.com", "User-Agent": "curl/8.4.0", "X-Forwarded-Host": "localhost", "X-Forwarded-Path": "/new-path", "X-Forwarded-Prefix": "/new-path", "X-Kong-Request-Id": "0bfd8c4c54274e4ffbbfcd2c5c939c65" }, "json": null, "method": "GET", "origin": "172.27.0.1", "url": "http://localhost/anything" }

Guaris · 2024-12-17T16:48:48Z

app/_how-tos/dynamically-rewrite-simple-request-urls-with-routes.md

+
+tldr:
+  q: How can I divert traffic from an old URL to a new one with {{site.base_gateway}}?
+  a: Set up a Gateway Service with the old URL path and create a new a Route with new path.For example, your legacy upstream endpoint may have a base URI like `/api/old/`. However, you want your publicly accessible API endpoint to now be named `/new/api`. To route the Service’s upstream endpoint to the new URL, you can set up a Service with the path `/api/old/` and a Route with the path `/new/api`.


I thinjk the /api/new and /api/old are good examples of what you are trying to do but because the deck file and steps dont reflect that I got thrown off. I think that the api/old and api/new can be illustrated through the steps better than as the answer int he tld;r

Signed-off-by: Diana <[email protected]>

lena-larionova

Partial review of the entity pages, ran out of time for the rest.

app/_gateway_entities/target.md

lena-larionova · 2024-12-17T23:50:03Z

app/_gateway_entities/route.md

-* Hosts: Lists of domains that match a route
-* Methods: HTTP methods that match a route
-* Headers: Lists of values that are expected in the header of a request
-* Redirect status codes: HTTPS status codes
-* Tags: Optional set of strings to group routes with
+When you configure Routes, you can also specify the following:

-## Route and service interaction
+* **Protocols:** The protocol used to communicate with the [Upstream](/gateway/entities/upstream/) application.
+* **Hosts:** Lists of domains that match a Route
+* **Methods:** HTTP methods that match a Route
+* **Headers:** Lists of values that are expected in the header of a request
+* **Redirect status codes:** HTTPS status codes
+* **Tags:** Optional set of strings to group Routes with


Is this list still useful? We have the Route schema on the page now, so this info is already here. Plus, there are almost definitely more options than this now.

app/_gateway_entities/route.md

lena-larionova · 2024-12-18T00:21:47Z

For the Routes entity page: I'm having a hard time seeing the big picture right now. It's a hefty page, and I wonder if all of the content that's been migrated over needs to be there. Is there anything here that's actually covered by having the schema on the page now?

I don't have the answer to this at all - but I am curious if there's a better way to organize this content.

Signed-off-by: Diana <[email protected]>

cloudjumpercat · 2024-12-18T15:19:18Z

app/gateway/routing/expressions.md

-```
-tls.sni =^ ".example.com"
-```
+![Router matching flow](https://docs.konghq.com/assets/images/products/gateway/reference/expressions-language/router-matching-flow.png)


For reviewers: I wrote this down to convert to Mermaid, but I'm just doing a 1:1 copy pretty much and wanted to get this reviewed. I'm going to need to learn how to escape some characters in Mermaid, so this might take me a bit.

app/_gateway_entities/route.md

lmilan · 2024-12-18T17:38:27Z

app/_gateway_entities/route.md

+
+Routing a request based on its Host header is the most straightforward way to proxy traffic through Kong Gateway, especially since this is the intended usage of the HTTP Host header. `hosts` accepts multiple values, which must be comma-separated when specifying them via the Admin API, and is represented in a JSON payload. You can also use wildcards in hostnames. Wildcard hostnames must contain only one asterisk at the leftmost or rightmost label of the domain.
+
+When proxying, Kong Gateway’s default behavior is to set the Upstream request’s Host header to the hostname specified in the Service’s `host`. The `preserve_host` field accepts a boolean flag instructing Kong Gateway not to do so.


Suggested change

When proxying, Kong Gateway’s default behavior is to set the Upstream request’s Host header to the hostname specified in the Service’s `host`. The `preserve_host` field accepts a boolean flag instructing Kong Gateway not to do so.

When proxying, {{site.base_gateway}}’s default behavior is to set the Upstream request’s Host header to the hostname specified in the Service’s `host`. The `preserve_host` field accepts a boolean flag instructing Kong Gateway not to do so.

app/gateway/routing/expressions-router-reference.md

lmilan · 2024-12-18T18:27:25Z

app/gateway/routing/expressions-router-reference.md

+
+## Allowed type and operator combinations
+
+Here are the allowed combination of field types and constant types with each operator.


Suggested change

Here are the allowed combination of field types and constant types with each operator.

Here are the allowed combinations of field types and constant types with each operator.

app/gateway/routing/expressions-router-reference.md

app/gateway/traffic-control/proxy.md

Signed-off-by: Diana <[email protected]>

Co-authored-by: Angel <[email protected]>

Signed-off-by: Diana <[email protected]>

app/_gateway_entities/upstream.md

Co-authored-by: Lucie Milan <[email protected]> Co-authored-by: lena-larionova <[email protected]>

Signed-off-by: Diana <[email protected]>

cloudjumpercat · 2024-12-19T00:32:54Z

The Request Transformer broken link will be resolved with updating the branch

… a different PR Signed-off-by: Diana <[email protected]>

Signed-off-by: Diana <[email protected]>

fabianrbz · 2024-12-19T16:41:15Z

app/gateway/traffic-control/proxy.md

+| `X-Forwarded-Port: <port>`              | `<port>` is the port of the server which accepted a request. If `$realip_remote_addr` is one of the **trusted** addresses, the request header with the same name gets forwarded if provided. Otherwise, the value of the `$server_port` variable provided by [ngx_http_core_module](https://nginx.org/docs/http/ngx_http_core_module.html#var_server_port) will be used. |
+| `X-Forwarded-Prefix: <path>`            | `<path>` is the path of the request which was accepted by {{site.base_gateway}}. If `$realip_remote_addr` is one of the **trusted** addresses, the request header with the same name gets forwarded if provided. Otherwise, the value of the `$request_uri` variable (with the query string stripped) provided by [ngx_http_core_module](https://nginx.org/docs/http/ngx_http_core_module.html#var_server_port) will be used. **Note**: {{site.base_gateway}} returns `"/"` for an empty path, but it doesn't do any other normalization on the request path. |
+| All other headers | Forwarded as-is by {{site.base_gateway}} | 
+<!--vale on-->


Suggested change





@cloudjumpercat for some reason adding a new line here fixes the rendering issue 🤷

Signed-off-by: Diana <[email protected]>

cloudjumpercat added 2 commits December 10, 2024 13:19

Start revising routes entity page

2d0e1ab

Signed-off-by: Diana <[email protected]>

Continue revising routes entity, start drafting the rewrite URLs how to

2804553

Signed-off-by: Diana <[email protected]>

cloudjumpercat added 4 commits December 11, 2024 08:30

Fix vale spelling error

9a845e9

Signed-off-by: Diana <[email protected]>

Capitalize entities

117daae

Signed-off-by: Diana <[email protected]>

Revise how to after testing

c3c8da6

Signed-off-by: Diana <[email protected]>

Plan out routing section for matching and priority section split

ccbd48e

Signed-off-by: Diana <[email protected]>

lena-larionova reviewed Dec 12, 2024

View reviewed changes

app/_gateway_entities/route.md Outdated Show resolved Hide resolved

app/_gateway_entities/route.md Outdated Show resolved Hide resolved

app/_gateway_entities/route.md Outdated Show resolved Hide resolved

cloudjumpercat and others added 3 commits December 12, 2024 08:49

Apply suggestions from code review

e9b3935

Co-authored-by: lena-larionova <[email protected]>

Edit routes, upstream, add proxy page, update source file with doc links

5a74da6

Signed-off-by: Diana <[email protected]>

Merge branch 'main' into routes-entity

2bd7119

fabianrbz reviewed Dec 13, 2024

View reviewed changes

app/gateway/traffic-control/proxy.md Outdated Show resolved Hide resolved

cloudjumpercat added 2 commits December 13, 2024 11:11

Fix broken breadcrumb link

89adbb6

Signed-off-by: Diana <[email protected]>

Revise a whole bunch of pages

45b8d04

Signed-off-by: Diana <[email protected]>

cloudjumpercat changed the title ~~Routes entity page (and supporting pages)~~ Routes, Targets, Upstream entity pages/ router expressions/ proxying/ load balancing Dec 13, 2024

Revise proxy reference and routing

5cf9492

Signed-off-by: Diana <[email protected]>

cloudjumpercat commented Dec 16, 2024

View reviewed changes

app/_how-tos/dynamically-rewrite-simple-request-urls-with-routes.md Outdated Show resolved Hide resolved

cloudjumpercat commented Dec 16, 2024

View reviewed changes

Start adding the needed expressions router pages

6c175ce

Signed-off-by: Diana <[email protected]>

Guaris reviewed Dec 16, 2024

View reviewed changes

Guaris mentioned this pull request Dec 16, 2024

Cors, mocking, dns config reference #173

Merged

5 tasks

Guaris requested changes Dec 17, 2024

View reviewed changes

Add drafts of all expressions docs

3aefeb7

Signed-off-by: Diana <[email protected]>

lena-larionova reviewed Dec 18, 2024

View reviewed changes

Finish expressions router concept page

3336680

Signed-off-by: Diana <[email protected]>

cloudjumpercat commented Dec 18, 2024

View reviewed changes

lmilan reviewed Dec 18, 2024

View reviewed changes

cloudjumpercat and others added 3 commits December 18, 2024 14:23

Remove expressions router how to and move enabling info to other pages

1f69366

Signed-off-by: Diana <[email protected]>

Apply suggestions from code review

7165bbc

Co-authored-by: Angel <[email protected]>

Apply Angel's remaining feedback to the rewrite urls how to

81e2355

Signed-off-by: Diana <[email protected]>

cloudjumpercat commented Dec 18, 2024

View reviewed changes

app/_gateway_entities/upstream.md Outdated Show resolved Hide resolved

cloudjumpercat and others added 2 commits December 18, 2024 15:55

Apply suggestions from code review

34e2faa

Co-authored-by: Lucie Milan <[email protected]> Co-authored-by: lena-larionova <[email protected]>

Apply Lena's feedback to Upstream entity page

586509d

Signed-off-by: Diana <[email protected]>

This was referenced Dec 18, 2024

GW Entity upstreams #179

Merged

GW Entity Targets #178

Merged

cloudjumpercat added 4 commits December 18, 2024 17:45

Revise Routes entity based on feedback

e819205

Signed-off-by: Diana <[email protected]>

Revise proxy reference

1a1733d

Signed-off-by: Diana <[email protected]>

Minor link fixes, make vale happy again

990afc6

Signed-off-by: Diana <[email protected]>

Fix broken links

fc92c6f

Signed-off-by: Diana <[email protected]>

cloudjumpercat added 2 commits December 18, 2024 18:37

Remove upstream and target entity pages since they are now handled in…

c5eb4b1

… a different PR Signed-off-by: Diana <[email protected]>

Convert expressions router image to mermaid

318b8d6

Signed-off-by: Diana <[email protected]>

lmilan approved these changes Dec 19, 2024

View reviewed changes

cloudjumpercat marked this pull request as ready for review December 19, 2024 14:06

cloudjumpercat requested a review from a team as a code owner December 19, 2024 14:06

cloudjumpercat changed the title ~~Routes, Targets, Upstream entity pages/ router expressions/ proxying/ load balancing~~ Routes entity page, router expressions, proxying Dec 19, 2024

Merge branch 'main' into routes-entity

4300032

fabianrbz reviewed Dec 19, 2024

View reviewed changes

Apply remaining feedback

1def049

Signed-off-by: Diana <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Routes entity page, router expressions, proxying #168

Routes entity page, router expressions, proxying #168

cloudjumpercat commented Dec 10, 2024 •

edited

Loading

netlify bot commented Dec 10, 2024 •

edited

Loading

lena-larionova left a comment

cloudjumpercat Dec 16, 2024

cloudjumpercat Dec 16, 2024

lmilan Dec 18, 2024

cloudjumpercat Dec 16, 2024

cloudjumpercat Dec 16, 2024

cloudjumpercat Dec 16, 2024

cloudjumpercat Dec 16, 2024

Guaris Dec 16, 2024

Guaris Dec 17, 2024

Guaris Dec 17, 2024

cloudjumpercat Dec 18, 2024

Guaris Dec 17, 2024

cloudjumpercat Dec 17, 2024

cloudjumpercat Dec 18, 2024

Guaris Dec 17, 2024

lena-larionova left a comment

lena-larionova Dec 17, 2024

lena-larionova commented Dec 18, 2024

cloudjumpercat Dec 18, 2024

lmilan Dec 18, 2024

lmilan Dec 18, 2024

cloudjumpercat commented Dec 19, 2024

fabianrbz Dec 19, 2024


		{{ page.description }} This page details information about how {{site.base_gateway}} handles proxying. The following diagram shows how proxying is handled by {{site.base_gateway}}:

		{% mermaid %}

		@@ -0,0 +1,191 @@
		---
		title: Proxying with {{site.base_gateway}}

		Now you can create a Route with your new path, `/new-path`, that points to the new Upstream.


		Routing a request based on its Host header is the most straightforward way to proxy traffic through Kong Gateway, especially since this is the intended usage of the HTTP Host header. `hosts` accepts multiple values, which must be comma-separated when specifying them via the Admin API, and is represented in a JSON payload. You can also use wildcards in hostnames. Wildcard hostnames must contain only one asterisk at the leftmost or rightmost label of the domain.

		When proxying, Kong Gateway’s default behavior is to set the Upstream request’s Host header to the hostname specified in the Service’s `host`. The `preserve_host` field accepts a boolean flag instructing Kong Gateway not to do so.

	When proxying, Kong Gateway’s default behavior is to set the Upstream request’s Host header to the hostname specified in the Service’s `host`. The `preserve_host` field accepts a boolean flag instructing Kong Gateway not to do so.
	When proxying, {{site.base_gateway}}’s default behavior is to set the Upstream request’s Host header to the hostname specified in the Service’s `host`. The `preserve_host` field accepts a boolean flag instructing Kong Gateway not to do so.


		## Allowed type and operator combinations

		Here are the allowed combination of field types and constant types with each operator.

	Here are the allowed combination of field types and constant types with each operator.
	Here are the allowed combinations of field types and constant types with each operator.

Routes entity page, router expressions, proxying #168

Are you sure you want to change the base?

Routes entity page, router expressions, proxying #168

Conversation

cloudjumpercat commented Dec 10, 2024 • edited Loading

TODO

Preview Links

Checklist

netlify bot commented Dec 10, 2024 • edited Loading

✅ Deploy Preview for kongdeveloper ready!

lena-larionova left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lena-larionova left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lena-larionova commented Dec 18, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cloudjumpercat commented Dec 19, 2024

Choose a reason for hiding this comment

cloudjumpercat commented Dec 10, 2024 •

edited

Loading

netlify bot commented Dec 10, 2024 •

edited

Loading