From d004e9d74850d82cb52e8149cdef0a9aed1dcc16 Mon Sep 17 00:00:00 2001 From: Angel Date: Thu, 12 Dec 2024 16:40:23 -0500 Subject: [PATCH 01/21] Cors, mocking, dns config reference --- .../sections/cors-and-kong-gateway.md | 45 +++++++++ app/_kong_plugins/cors/index.md | 41 +++++++++ app/_kong_plugins/cors/reference.yaml | 1 + app/_kong_plugins/mocking/index.md | 84 +++++++++++++++++ app/_kong_plugins/mocking/reference.yaml | 1 + .../networking/dns-config-reference.md | 91 +++++++++++++++++++ tools/track-docs-changes/config/sources.yml | 13 +++ 7 files changed, 276 insertions(+) create mode 100644 app/_includes/sections/cors-and-kong-gateway.md create mode 100644 app/_kong_plugins/cors/index.md create mode 100644 app/_kong_plugins/cors/reference.yaml create mode 100644 app/_kong_plugins/mocking/index.md create mode 100644 app/_kong_plugins/mocking/reference.yaml create mode 100644 app/gateway/networking/dns-config-reference.md diff --git a/app/_includes/sections/cors-and-kong-gateway.md b/app/_includes/sections/cors-and-kong-gateway.md new file mode 100644 index 000000000..07c2cd790 --- /dev/null +++ b/app/_includes/sections/cors-and-kong-gateway.md @@ -0,0 +1,45 @@ + +## Understanding CORS + +Cross-Origin Resource Sharing, or CORS, is a set of rules for web applications that make requests across origins, i.e. to URLs that do not share the same scheme, hostname, and port as the page making the request. When making a cross-origin request, browsers send an `origin` request header, and servers must respond with a matching `Access-Control-Allow-Origin` (ACAO) header. If the two headers do not match, the browser will discard the response, and any application components that require that response’s data will not function properly. + +For example,the following request/response pairs have matching CORS headers, and will succeed: + +```sh +GET / HTTP/1.1 +Host: example.com +Origin: http://example.net + +HTTP/1.1 200 OK +Access-Control-Allow-Origin: http://example.net +``` + +```sh +GET / HTTP/1.1 +Host: example.com +Origin: http://example.net + +HTTP/1.1 200 OK +Access-Control-Allow-Origin: * +``` + +These two requests do not have a matching CORS headers and therefore will fail: + +```sh +GET / HTTP/1.1 +Host: example.com +Origin: http://example.net + +HTTP/1.1 200 OK +Access-Control-Allow-Origin: http://badbadcors.example +``` + +```sh +GET / HTTP/1.1 +Host: example.com +Origin: http://example.net + +HTTP/1.1 200 OK +``` + +Missing CORS headers when CORS headers are expected results in failure. diff --git a/app/_kong_plugins/cors/index.md b/app/_kong_plugins/cors/index.md new file mode 100644 index 000000000..d56cc29ae --- /dev/null +++ b/app/_kong_plugins/cors/index.md @@ -0,0 +1,41 @@ +--- +title: The Cross-Origin Resource Sharing (CORS) Plugin + +name: CORS +publisher: kong-inc +content_type: plugin +tier: enterprise +description: The CORS plugin lets you add cross-origin resource sharing (CORS) to a service or a route. +tags: + - security + +works_on: + - on-prem + - konnect + +related_resources: + - text: DNS configuration reference + url: /gateway/networking/dns-config-reference + +--- + +## Overview + + +The CORS plugin lets you add cross-origin resource sharing (CORS) to a service or a route. Allowing you to automate the s the configuration of CORS rules, ensuring that your APIs only accept requests from approved sources. + + +{% include sections/cors-and-kong-gateway.md %} + + +## CORS limitations + +If the client is a browser, there is a known issue with this plugin caused by a +limitation of the [CORS specification](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) that prevents specifying a custom +`Host` header in a preflight `OPTIONS` request. + +Because of this limitation, this plugin only works for routes that have been +configured with a `paths` setting. The CORS plugin does not work for routes that +are being resolved using a custom DNS (the `hosts` property). + +To learn how to configure `paths` for a route, read the [Proxy Reference](/gateway/latest/reference/proxy). diff --git a/app/_kong_plugins/cors/reference.yaml b/app/_kong_plugins/cors/reference.yaml new file mode 100644 index 000000000..ba1e8f86d --- /dev/null +++ b/app/_kong_plugins/cors/reference.yaml @@ -0,0 +1 @@ +content_type: plugin_reference diff --git a/app/_kong_plugins/mocking/index.md b/app/_kong_plugins/mocking/index.md new file mode 100644 index 000000000..0e04a3df0 --- /dev/null +++ b/app/_kong_plugins/mocking/index.md @@ -0,0 +1,84 @@ +--- +title: The Mocking Plugin + +name: Mocking +publisher: kong-inc +content_type: plugin +tier: enterprise +description: rovide mock endpoints to test your APIs in development against your services. +tags: + - traffic-control + +works_on: + - on-prem + - konnect + +related_resources: + - text: DNS configuration reference + url: /gateway/networking/dns-config-reference +--- + + +## Overview + +The Mocking plugin allows you to provide mock endpoints to test APIs in development against your existing services. The Mocking plugin leverages standards based on the Open API Specification (OAS) for sending out mock responses to APIs. Mocking supports both Swagger 2.0 and OpenAPI 3.0. + +The Mocking plugin requires an API spec to work correctly. Depending on the Kong Gateway deployment mode, set either the api_specification_filename or the api_specification parameter in `kong.conf`. + +## Mocked responses + +The Mocking plugin can mock the following responses: + +* **`200`** +* **`201`** +* **`204`** + +## Behavioral Headers + + +Behavioral headers allow you to change the behavior of the Mocking plugin for the individual request without changing the configuration. + +### X-Kong-Mocking-Delay + +The` X-Kong-Mocking-Delay` header tells the plugin how many milliseconds to delay before responding. The delay value must be between `0`(inclusive) and `10000`(inclusive), otherwise it returns a `400` error like this: + +```json +HTTP/1.1 400 Bad Request + +{ + "message": "Invalid value for X-Kong-Mocking-Delay. The delay value should between 0 and 10000ms" +} +``` +### X-Kong-Mocking-Example-Id + +The `X-Kong-Mocking-Example-Id` header tells the plugin which response example is used when the endpoint has multiple examples for a single status code. + +OpenAPI 3.0 allows you to define multiple examples in a single MIME type. The following example has two candidate examples: User1 and User2. + +```yaml +paths: + /query_user: + get: + responses: + '200': + description: A user object. + content: + application/json: + examples: + User1: + value: + id: 10 + name: User1 + User2: + value: + id: 20 + name: User2 + + +``` + +### X-Kong-Mocking-Status-Code + +By default, the plugin chooses the minimum status code that is defined in the corresponding method. + +The `X-Kong-Mocking-Status-Code` header allows requests to change the default status code selection behavior by specifying a status code that is defined in the corresponding method. \ No newline at end of file diff --git a/app/_kong_plugins/mocking/reference.yaml b/app/_kong_plugins/mocking/reference.yaml new file mode 100644 index 000000000..ba1e8f86d --- /dev/null +++ b/app/_kong_plugins/mocking/reference.yaml @@ -0,0 +1 @@ +content_type: plugin_reference diff --git a/app/gateway/networking/dns-config-reference.md b/app/gateway/networking/dns-config-reference.md new file mode 100644 index 000000000..dea4610ce --- /dev/null +++ b/app/gateway/networking/dns-config-reference.md @@ -0,0 +1,91 @@ +--- +title: DNS Config Reference + +description: This reference explains DNS clients, CORS, and Cookie management in Kong Gateway +content_type: reference +layout: reference +tier: enterprise +products: + - gateway + + +plugins: + - cors + - mocking + - sessions + - oidc + + +breadcrumbs: + - /gateway/networking/dns-config-reference +--- + +## Overview + +Kong Gateway provides the Kong Manager, which must be able to interact with the Admin API. This application is subject to security restrictions enforced by browsers, and Kong must send appropriate information to browsers in order for it to function properly. + +These security restrictions use the applications’ DNS hostnames to evaluate whether the applications’ metadata satisfies the security constraints. As such, you must design your DNS structure to meet the requirements. + + +## DNS structure requirements + + +* Kong Manager and the Admin API are served from the same hostname, typically by placing the Admin API under an otherwise unused path, such as `/_adminapi/`. + +* Kong Manager and the Admin API are served from different hostnames with a shared suffix (e.g. `kong.example` for `api.admin.kong.example` and `manager.admin.kong.example`). Admin session configuration sets `cookie_domain` to the shared suffix. + +The first option simplifies configuration in kong.conf, but requires an HTTP proxy in front of the applications (because it uses HTTP path-based routing). The Kong proxy can be used for this. The second option requires more configuration in kong.conf, but can be used without proxying the applications. + + +{% include sections/cors-and-kong-gateway.md %} + +### CORS and Kong Manager + + +Kong Manager operate by issuing requests to the Admin API using JavaScript. These requests may be cross-origin depending on your environment. The Admin API obtains its `ACAO header` value from the `admin_gui_url` in kong.conf. + +You can configure your environment such that these requests are not cross-origin by accessing both the Kong Manager and its associated API via the same hostname, like: https://admin.kong.example/ and the Admin API at https://admin.kong.example/_api/. This option requires placing a proxy in front of both Kong Manager and the Admin API to handle path-based routing. You can use Kong’s proxy for this purpose. Kong Manager must be served at the root of the domains and you cannot place the APIs at the root and Kong Manager under a path. + + +### Troubleshooting CORS + +CORS errors are shown in the browser developer console with +explanations of the specific issue. ACAO/Origin mismatches are most common, but +other error conditions can appear as well. + +For example, if you mistyped your `admin_api_uri`, you will see something +like the following: + +``` +Access to XMLHttpRequest at 'https://admin.kong.example' from origin 'https://manager.kong.example' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: The 'Access-Control-Allow-Origin' header has a value 'https://typo.kong.example' that is not equal to the supplied origin. +``` + +These errors are generally self-explanatory, but if the issue is not clear, +check the Network developer tool, find the requests for the path in the error, +and compare its `Origin` request header and `Access-Control-Allow-Origin` +response header. + +## {{site.base_gateway}} Cookies + + +After you log in to Kong Manager, Kong stores session information in a cookie +to recognize your browser during future requests. These cookies are created +using the [Sessions Plugin](/plugins/sessions) or [OpenID Connect](/plugins/oidc). + +- Cookie scope, defined by the cookie's `Domain` and `Path` directives. Absent + these, cookies are sent only to the hostname that created them: a cookie + created by `example.com` will not be sent with a request to + `www.example.com`. When `Domain` is specified, cookies are sent to that + hostname and its subdomains, so a cookie from `example.com` with + `Domain=example.com` *will* be sent with requests to `www.example.com`. +- The `Secure` directive, which determines whether a cookie can be sent over an + unencrypted (HTTP rather than HTTPS) connection. A cookie with `Secure` + cannot be sent over HTTP, and must be set using HTTPS. +- The `SameSite` directive, which controls when a cookie can be sent with + cross-origin requests. Note that cookies have a different notion of + cross-origin than CORS and check against the domain suffix: while + `example.com` sending a request to `api.example.com` is cross-origin for the + purposes of CORS, a cookie with `Domain=example.com` is considered same-site + for requests to `api.example.com`. `SameSite=Strict` cookies are only sent + with same-site requests, `Lax` are sent when navigating to a link from + another site, and `None` are sent with all cross-origin requests. \ No newline at end of file diff --git a/tools/track-docs-changes/config/sources.yml b/tools/track-docs-changes/config/sources.yml index b2ce7e9b2..046d1e377 100644 --- a/tools/track-docs-changes/config/sources.yml +++ b/tools/track-docs-changes/config/sources.yml @@ -111,3 +111,16 @@ app/plugins/protocols.md: - app/hub/plugins/compatibility/index.md app/plugins/scopes.md: - app/hub/plugins/compatibility/index.md + +# Plugins + +app/_kong_plugins/cors/index.md: + - app/_hub/kong-inc/cors/overview/_index.md +app/_kong_plugins/mocking/index.md: + - /app/_hub/kong-inc/mocking/overview/_index.md + + +# References + +app/gateway/networking/dns-config-reference.md: + - app/_src/gateway/production/networking/dns-considerations.md \ No newline at end of file From d52fb7bf58df9c830ebe97350fdbfe718219f99d Mon Sep 17 00:00:00 2001 From: Angel Date: Mon, 16 Dec 2024 16:39:54 -0500 Subject: [PATCH 02/21] fix urls, remove cookies --- app/_kong_plugins/cors/index.md | 16 +++++------ app/_kong_plugins/mocking/index.md | 18 +++++-------- .../networking/dns-config-reference.md | 27 +------------------ 3 files changed, 15 insertions(+), 46 deletions(-) diff --git a/app/_kong_plugins/cors/index.md b/app/_kong_plugins/cors/index.md index 6a68ac154..96c1edc13 100644 --- a/app/_kong_plugins/cors/index.md +++ b/app/_kong_plugins/cors/index.md @@ -15,6 +15,12 @@ products: works_on: - on-prem - konnect +# topologies: +# - hybrid +# - db-less +# - traditional + +icon: cors.png related_resources: @@ -42,13 +48,5 @@ Because of this limitation, this plugin only works for routes that have been configured with a `paths` setting. The CORS plugin does not work for routes that are being resolved using a custom DNS (the `hosts` property). -To learn how to configure `paths` for a route, read the [Proxy Reference](/gateway/latest/reference/proxy). -======= +To learn how to configure `paths` for a route, read the [Proxy Reference](/gateway/traffic-control/proxy/). -# topologies: -# - hybrid -# - db-less -# - traditional - -icon: cors.png ---- diff --git a/app/_kong_plugins/mocking/index.md b/app/_kong_plugins/mocking/index.md index 204c7f15a..0da6a92e7 100644 --- a/app/_kong_plugins/mocking/index.md +++ b/app/_kong_plugins/mocking/index.md @@ -17,6 +17,13 @@ works_on: - on-prem - konnect +# topologies: +# - hybrid +# - db-less +# - traditional + +icon: mocking.png + related_resources: - text: DNS configuration reference url: /gateway/networking/dns-config-reference @@ -86,14 +93,3 @@ paths: By default, the plugin chooses the minimum status code that is defined in the corresponding method. The `X-Kong-Mocking-Status-Code` header allows requests to change the default status code selection behavior by specifying a status code that is defined in the corresponding method. -======= -# topologies: -# - hybrid -# - db-less -# - traditional - -icon: mocking.png ---- - -## Overview - diff --git a/app/gateway/networking/dns-config-reference.md b/app/gateway/networking/dns-config-reference.md index dea4610ce..faa2f75ad 100644 --- a/app/gateway/networking/dns-config-reference.md +++ b/app/gateway/networking/dns-config-reference.md @@ -63,29 +63,4 @@ Access to XMLHttpRequest at 'https://admin.kong.example' from origin 'https://ma These errors are generally self-explanatory, but if the issue is not clear, check the Network developer tool, find the requests for the path in the error, and compare its `Origin` request header and `Access-Control-Allow-Origin` -response header. - -## {{site.base_gateway}} Cookies - - -After you log in to Kong Manager, Kong stores session information in a cookie -to recognize your browser during future requests. These cookies are created -using the [Sessions Plugin](/plugins/sessions) or [OpenID Connect](/plugins/oidc). - -- Cookie scope, defined by the cookie's `Domain` and `Path` directives. Absent - these, cookies are sent only to the hostname that created them: a cookie - created by `example.com` will not be sent with a request to - `www.example.com`. When `Domain` is specified, cookies are sent to that - hostname and its subdomains, so a cookie from `example.com` with - `Domain=example.com` *will* be sent with requests to `www.example.com`. -- The `Secure` directive, which determines whether a cookie can be sent over an - unencrypted (HTTP rather than HTTPS) connection. A cookie with `Secure` - cannot be sent over HTTP, and must be set using HTTPS. -- The `SameSite` directive, which controls when a cookie can be sent with - cross-origin requests. Note that cookies have a different notion of - cross-origin than CORS and check against the domain suffix: while - `example.com` sending a request to `api.example.com` is cross-origin for the - purposes of CORS, a cookie with `Domain=example.com` is considered same-site - for requests to `api.example.com`. `SameSite=Strict` cookies are only sent - with same-site requests, `Lax` are sent when navigating to a link from - another site, and `None` are sent with all cross-origin requests. \ No newline at end of file +response header. \ No newline at end of file From 5aea9dd4d138d36a02b4e1ff41e173e3fb8356ed Mon Sep 17 00:00:00 2001 From: Angel Date: Mon, 16 Dec 2024 16:44:20 -0500 Subject: [PATCH 03/21] vale --- app/_kong_plugins/mocking/index.md | 2 +- app/gateway/networking/dns-config-reference.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/app/_kong_plugins/mocking/index.md b/app/_kong_plugins/mocking/index.md index 0da6a92e7..c14a6b2b9 100644 --- a/app/_kong_plugins/mocking/index.md +++ b/app/_kong_plugins/mocking/index.md @@ -34,7 +34,7 @@ related_resources: The Mocking plugin allows you to provide mock endpoints to test APIs in development against your existing services. The Mocking plugin leverages standards based on the Open API Specification (OAS) for sending out mock responses to APIs. Mocking supports both Swagger 2.0 and OpenAPI 3.0. -The Mocking plugin requires an API spec to work correctly. Depending on the Kong Gateway deployment mode, set either the api_specification_filename or the api_specification parameter in `kong.conf`. +The Mocking plugin requires an API spec to work correctly. Depending on the {{site.base_gateway}} deployment mode, set either the `api_specification_filename` or the `api_specification` parameter in `kong.conf`. ## Mocked responses diff --git a/app/gateway/networking/dns-config-reference.md b/app/gateway/networking/dns-config-reference.md index faa2f75ad..ebe93344f 100644 --- a/app/gateway/networking/dns-config-reference.md +++ b/app/gateway/networking/dns-config-reference.md @@ -22,7 +22,7 @@ breadcrumbs: ## Overview -Kong Gateway provides the Kong Manager, which must be able to interact with the Admin API. This application is subject to security restrictions enforced by browsers, and Kong must send appropriate information to browsers in order for it to function properly. +{{site.base_gateway}} provides the Kong Manager, which must be able to interact with the Admin API. This application is subject to security restrictions enforced by browsers, and Kong must send appropriate information to browsers in order for it to function properly. These security restrictions use the applications’ DNS hostnames to evaluate whether the applications’ metadata satisfies the security constraints. As such, you must design your DNS structure to meet the requirements. From aba5dc18ffa8f3198c7b8c85cdb96094f03d7b73 Mon Sep 17 00:00:00 2001 From: Angel Date: Mon, 16 Dec 2024 16:47:45 -0500 Subject: [PATCH 04/21] vale twice --- app/gateway/networking/dns-config-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/gateway/networking/dns-config-reference.md b/app/gateway/networking/dns-config-reference.md index ebe93344f..dc47ede17 100644 --- a/app/gateway/networking/dns-config-reference.md +++ b/app/gateway/networking/dns-config-reference.md @@ -1,7 +1,7 @@ --- title: DNS Config Reference -description: This reference explains DNS clients, CORS, and Cookie management in Kong Gateway +description: This reference explains DNS clients, CORS, and Cookie management in {{site.base_gateway}} content_type: reference layout: reference tier: enterprise From 0fbde586cec02e02b9e23969380d1f9ac01c0346 Mon Sep 17 00:00:00 2001 From: Angel Date: Tue, 17 Dec 2024 15:33:24 -0500 Subject: [PATCH 05/21] Apply suggestions from code review Co-authored-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_includes/sections/cors-and-kong-gateway.md | 2 +- app/_kong_plugins/cors/index.md | 4 ++-- app/_kong_plugins/mocking/index.md | 7 ------- app/gateway/networking/dns-config-reference.md | 4 ++-- 4 files changed, 5 insertions(+), 12 deletions(-) diff --git a/app/_includes/sections/cors-and-kong-gateway.md b/app/_includes/sections/cors-and-kong-gateway.md index 07c2cd790..c2e5ff452 100644 --- a/app/_includes/sections/cors-and-kong-gateway.md +++ b/app/_includes/sections/cors-and-kong-gateway.md @@ -23,7 +23,7 @@ HTTP/1.1 200 OK Access-Control-Allow-Origin: * ``` -These two requests do not have a matching CORS headers and therefore will fail: +These two request/response pairs do not have a matching CORS headers and therefore will fail: ```sh GET / HTTP/1.1 diff --git a/app/_kong_plugins/cors/index.md b/app/_kong_plugins/cors/index.md index 96c1edc13..a81d01ea0 100644 --- a/app/_kong_plugins/cors/index.md +++ b/app/_kong_plugins/cors/index.md @@ -5,7 +5,7 @@ name: 'CORS' content_type: plugin publisher: kong-inc -description: 'The CORS plugin lets you add cross-origin resource sharing (CORS) to a service or a route.' +description: 'The CORS plugin lets you add Cross-Origin Resource Sharing (CORS) to a service or a route.' products: @@ -32,7 +32,7 @@ related_resources: ## Overview -The CORS plugin lets you add cross-origin resource sharing (CORS) to a service or a route. Allowing you to automate the s the configuration of CORS rules, ensuring that your APIs only accept requests from approved sources. +The CORS plugin lets you add Cross-Origin Resource Sharing (CORS) to a Service or a Route. This allows you to automate the configuration of CORS rules, ensuring that your APIs only accept requests from approved sources. {% include sections/cors-and-kong-gateway.md %} diff --git a/app/_kong_plugins/mocking/index.md b/app/_kong_plugins/mocking/index.md index c14a6b2b9..b07c841df 100644 --- a/app/_kong_plugins/mocking/index.md +++ b/app/_kong_plugins/mocking/index.md @@ -53,13 +53,6 @@ Behavioral headers allow you to change the behavior of the Mocking plugin for th The` X-Kong-Mocking-Delay` header tells the plugin how many milliseconds to delay before responding. The delay value must be between `0`(inclusive) and `10000`(inclusive), otherwise it returns a `400` error like this: -```json -HTTP/1.1 400 Bad Request - -{ - "message": "Invalid value for X-Kong-Mocking-Delay. The delay value should between 0 and 10000ms" -} -``` ### X-Kong-Mocking-Example-Id The `X-Kong-Mocking-Example-Id` header tells the plugin which response example is used when the endpoint has multiple examples for a single status code. diff --git a/app/gateway/networking/dns-config-reference.md b/app/gateway/networking/dns-config-reference.md index dc47ede17..4317d250a 100644 --- a/app/gateway/networking/dns-config-reference.md +++ b/app/gateway/networking/dns-config-reference.md @@ -1,7 +1,7 @@ --- title: DNS Config Reference -description: This reference explains DNS clients, CORS, and Cookie management in {{site.base_gateway}} +description: This reference explains DNS clients, CORS, and cookie management in {{site.base_gateway}} content_type: reference layout: reference tier: enterprise @@ -22,7 +22,7 @@ breadcrumbs: ## Overview -{{site.base_gateway}} provides the Kong Manager, which must be able to interact with the Admin API. This application is subject to security restrictions enforced by browsers, and Kong must send appropriate information to browsers in order for it to function properly. +{{page.description}} {{site.base_gateway}} provides the Kong Manager, which must be able to interact with the Admin API. This application is subject to security restrictions enforced by browsers, and Kong must send appropriate information to browsers in order for it to function properly. These security restrictions use the applications’ DNS hostnames to evaluate whether the applications’ metadata satisfies the security constraints. As such, you must design your DNS structure to meet the requirements. From 2ad47f28a6ed3ace2fac7780815bf7ed93e11607 Mon Sep 17 00:00:00 2001 From: Angel Date: Wed, 18 Dec 2024 14:40:48 -0500 Subject: [PATCH 06/21] diana feedback --- app/_includes/sections/cors-and-kong-gateway.md | 8 +++++--- app/_kong_plugins/cors/index.md | 2 +- app/gateway/networking/dns-config-reference.md | 10 ++++++---- 3 files changed, 12 insertions(+), 8 deletions(-) diff --git a/app/_includes/sections/cors-and-kong-gateway.md b/app/_includes/sections/cors-and-kong-gateway.md index c2e5ff452..8926ee726 100644 --- a/app/_includes/sections/cors-and-kong-gateway.md +++ b/app/_includes/sections/cors-and-kong-gateway.md @@ -1,9 +1,11 @@ ## Understanding CORS -Cross-Origin Resource Sharing, or CORS, is a set of rules for web applications that make requests across origins, i.e. to URLs that do not share the same scheme, hostname, and port as the page making the request. When making a cross-origin request, browsers send an `origin` request header, and servers must respond with a matching `Access-Control-Allow-Origin` (ACAO) header. If the two headers do not match, the browser will discard the response, and any application components that require that response’s data will not function properly. +For security purposes a browser will stop requests from accessing URLs on different domains. This is done using CORS, a set of rules for web applications that make requests across origin. CORS works by looking at the HTTP `origin` header of a URL and checking it against a list of allowed headers. An `origin` header can contain the `scheme`, `hostname`, or `port` of the requesting URL. Operations that are restricted to same-origin content can be managed using CORS. -For example,the following request/response pairs have matching CORS headers, and will succeed: +When making a cross-origin request, browsers issue an `origin` request header, and servers must respond with a matching `Access-Control-Allow-Origin` (ACAO) header. If the two headers do not match, the browser will discard the response, and any application components that require that response’s data will not function properly. + +For example, the following request and response pairs have matching CORS headers, and will succeed: ```sh GET / HTTP/1.1 @@ -23,7 +25,7 @@ HTTP/1.1 200 OK Access-Control-Allow-Origin: * ``` -These two request/response pairs do not have a matching CORS headers and therefore will fail: +The requests do not have a matching CORS headers and therefore will fail: ```sh GET / HTTP/1.1 diff --git a/app/_kong_plugins/cors/index.md b/app/_kong_plugins/cors/index.md index a81d01ea0..4267b57c5 100644 --- a/app/_kong_plugins/cors/index.md +++ b/app/_kong_plugins/cors/index.md @@ -32,7 +32,7 @@ related_resources: ## Overview -The CORS plugin lets you add Cross-Origin Resource Sharing (CORS) to a Service or a Route. This allows you to automate the configuration of CORS rules, ensuring that your APIs only accept requests from approved sources. +The CORS plugin lets you add Cross-Origin Resource Sharing (CORS) to a Service or a Route. This allows you to automate the configuration of CORS rules, ensuring that your upstreams only accept and share resources with approved sources. {% include sections/cors-and-kong-gateway.md %} diff --git a/app/gateway/networking/dns-config-reference.md b/app/gateway/networking/dns-config-reference.md index 4317d250a..f89579fde 100644 --- a/app/gateway/networking/dns-config-reference.md +++ b/app/gateway/networking/dns-config-reference.md @@ -15,6 +15,9 @@ plugins: - sessions - oidc +related_resources: + - text: Kong Plugins + url: /plugins/cors breadcrumbs: - /gateway/networking/dns-config-reference @@ -22,13 +25,14 @@ breadcrumbs: ## Overview -{{page.description}} {{site.base_gateway}} provides the Kong Manager, which must be able to interact with the Admin API. This application is subject to security restrictions enforced by browsers, and Kong must send appropriate information to browsers in order for it to function properly. +{{page.description}}. {{site.base_gateway}} provides Kong Manager, which must be able to interact with the Admin API. This application is subject to security restrictions enforced by browsers, and Kong must send appropriate information to browsers in order for it to function properly. These security restrictions use the applications’ DNS hostnames to evaluate whether the applications’ metadata satisfies the security constraints. As such, you must design your DNS structure to meet the requirements. ## DNS structure requirements +The two types of requirements are: * Kong Manager and the Admin API are served from the same hostname, typically by placing the Admin API under an otherwise unused path, such as `/_adminapi/`. @@ -37,14 +41,12 @@ These security restrictions use the applications’ DNS hostnames to evaluate wh The first option simplifies configuration in kong.conf, but requires an HTTP proxy in front of the applications (because it uses HTTP path-based routing). The Kong proxy can be used for this. The second option requires more configuration in kong.conf, but can be used without proxying the applications. -{% include sections/cors-and-kong-gateway.md %} - ### CORS and Kong Manager Kong Manager operate by issuing requests to the Admin API using JavaScript. These requests may be cross-origin depending on your environment. The Admin API obtains its `ACAO header` value from the `admin_gui_url` in kong.conf. -You can configure your environment such that these requests are not cross-origin by accessing both the Kong Manager and its associated API via the same hostname, like: https://admin.kong.example/ and the Admin API at https://admin.kong.example/_api/. This option requires placing a proxy in front of both Kong Manager and the Admin API to handle path-based routing. You can use Kong’s proxy for this purpose. Kong Manager must be served at the root of the domains and you cannot place the APIs at the root and Kong Manager under a path. +You can configure your environment such that these requests are not cross-origin by accessing both the Kong Manager and its associated API via the same hostname, like: https://admin.kong.example/ and the Admin API at https://admin.kong.example/_api/. This option requires placing a proxy in front of both Kong Manager and the Admin API to handle path-based routing. You can use Kong’s proxy for this purpose. Kong Manager must be served at the root of the domains and you cannot place the APIs at the root and Kong Manager under a path. You can manage CORS in {{site.base_gateway}} using the [CORS plugin](/plugins/cors) ### Troubleshooting CORS From fc0daf173f3dc0f3aa8c60f6014bca4313c6478a Mon Sep 17 00:00:00 2001 From: Angel Date: Wed, 18 Dec 2024 14:43:51 -0500 Subject: [PATCH 07/21] diana feedback --- app/_kong_plugins/mocking/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_kong_plugins/mocking/index.md b/app/_kong_plugins/mocking/index.md index b07c841df..dd1ddb154 100644 --- a/app/_kong_plugins/mocking/index.md +++ b/app/_kong_plugins/mocking/index.md @@ -34,7 +34,7 @@ related_resources: The Mocking plugin allows you to provide mock endpoints to test APIs in development against your existing services. The Mocking plugin leverages standards based on the Open API Specification (OAS) for sending out mock responses to APIs. Mocking supports both Swagger 2.0 and OpenAPI 3.0. -The Mocking plugin requires an API spec to work correctly. Depending on the {{site.base_gateway}} deployment mode, set either the `api_specification_filename` or the `api_specification` parameter in `kong.conf`. +You need an API spec you want to mock the endpoints of for the Mocking plugin to work correctly. Depending on the {{site.base_gateway}} deployment mode, set either the `api_specification_filename` or the `api_specification` parameter in `kong.conf`. ## Mocked responses From 46a84dd0967cb16e5b6d451663dc3fa4239d2a5a Mon Sep 17 00:00:00 2001 From: Angel Date: Wed, 18 Dec 2024 19:43:02 -0500 Subject: [PATCH 08/21] cors plugin --- .../cors/examples/basic-configuration.yaml | 28 ++++ app/_kong_plugins/cors/examples/example.yaml | 15 --- app/_kong_plugins/cors/index.md | 8 +- .../mocking/examples/basic-configuration.yaml | 125 ++++++++++++++++++ .../mocking/examples/example.yaml | 15 --- 5 files changed, 157 insertions(+), 34 deletions(-) create mode 100644 app/_kong_plugins/cors/examples/basic-configuration.yaml delete mode 100644 app/_kong_plugins/cors/examples/example.yaml create mode 100644 app/_kong_plugins/mocking/examples/basic-configuration.yaml delete mode 100644 app/_kong_plugins/mocking/examples/example.yaml diff --git a/app/_kong_plugins/cors/examples/basic-configuration.yaml b/app/_kong_plugins/cors/examples/basic-configuration.yaml new file mode 100644 index 000000000..c76562c9d --- /dev/null +++ b/app/_kong_plugins/cors/examples/basic-configuration.yaml @@ -0,0 +1,28 @@ +title: Configure the plugin on a Service +description: | + Configures the CORS plugin on a specific Service to accept common methods and headers from a specified Service. + +weight: 400 + +config: + plugins: + - name: cors + service: SERVICE_NAME|ID + config: + origins: + - http://mockbin.com + methods: + - GET + - POST + headers: + - Accept + - Accept-Version + - Content-Length + - Content-MD5 + - Content-Type + - Date + - X-Auth-Token + exposed_headers: + - X-Auth-Token + credentials: true + max_age: 3600 \ No newline at end of file diff --git a/app/_kong_plugins/cors/examples/example.yaml b/app/_kong_plugins/cors/examples/example.yaml deleted file mode 100644 index 714b33873..000000000 --- a/app/_kong_plugins/cors/examples/example.yaml +++ /dev/null @@ -1,15 +0,0 @@ -description: '' - -title: '' - -weight: 900 - -# requirements: <- not required -# - "some req" - -# variables: <- not required -# my-region: -# description: '' -# value: us - -config: # plugin config in yaml format goes here \ No newline at end of file diff --git a/app/_kong_plugins/cors/index.md b/app/_kong_plugins/cors/index.md index 4267b57c5..a08429ccd 100644 --- a/app/_kong_plugins/cors/index.md +++ b/app/_kong_plugins/cors/index.md @@ -15,10 +15,10 @@ products: works_on: - on-prem - konnect -# topologies: -# - hybrid -# - db-less -# - traditional +topologies: + - hybrid + - db-less + - traditional icon: cors.png diff --git a/app/_kong_plugins/mocking/examples/basic-configuration.yaml b/app/_kong_plugins/mocking/examples/basic-configuration.yaml new file mode 100644 index 000000000..d7a82edf7 --- /dev/null +++ b/app/_kong_plugins/mocking/examples/basic-configuration.yaml @@ -0,0 +1,125 @@ +title: Pass an OpenAPI spec to the plugin through decK +description: | + Configures the mocking plugin and passes an API spec. + +weight: 400 +config: + plugins: + - name: mocking + service: SERVICE_NAME|ID + config: + random_delay: true + max_delay_time: 1 + min_delay_time: 0.001 + random_examples: true + api_specification: | + openapi: 3.0.2 + servers: + - url: /v3 + info: + description: |- + This is a sample Pet Store Server based on the OpenAPI 3.0 specification. You can find out more about + Swagger at [http://swagger.io](http://swagger.io). In the third iteration of the pet store, we've switched to the design first approach! + You can now help us improve the API whether it's by making changes to the definition itself or to the code. + That way, with time, we can improve the API in general, and expose some of the new features in OAS3. + + Some useful links: + - [The Pet Store repository](https://github.com/swagger-api/swagger-petstore) + - [The source API definition for the Pet Store](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml) + version: 1.0.20-SNAPSHOT + title: Swagger Petstore - OpenAPI 3.0 + termsOfService: 'http://swagger.io/terms/' + contact: + email: apiteam@swagger.io + license: + name: Apache 2.0 + url: 'http://www.apache.org/licenses/LICENSE-2.0.html' + tags: + - name: pet + description: Everything about your Pets + externalDocs: + description: Find out more + url: 'http://swagger.io' + - name: store + description: Access to Petstore orders + externalDocs: + description: Find out more about our store + url: 'http://swagger.io' + - name: user + description: Operations about user + paths: + /pet: + post: + tags: + - pet + summary: Add a new pet to the store + description: Add a new pet to the store + operationId: addPet + responses: + '200': + description: Successful operation + content: + application/xml: + schema: + $ref: '#/components/schemas/Pet' + application/json: + schema: + $ref: '#/components/schemas/Pet' + '405': + description: Invalid input + security: + - petstore_auth: + - 'write:pets' + - 'read:pets' + requestBody: + description: Create a new pet in the store + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Pet' + application/xml: + schema: + $ref: '#/components/schemas/Pet' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/Pet' + put: + tags: + - pet + summary: Update an existing pet + description: Update an existing pet by Id + operationId: updatePet + responses: + '200': + description: Successful operation + content: + application/xml: + schema: + $ref: '#/components/schemas/Pet' + application/json: + schema: + $ref: '#/components/schemas/Pet' + '400': + description: Invalid ID supplied + '404': + description: Pet not found + '405': + description: Validation exception + security: + - petstore_auth: + - 'write:pets' + - 'read:pets' + requestBody: + description: Update an existent pet in the store + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Pet' + application/xml: + schema: + $ref: '#/components/schemas/Pet' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/Pet' \ No newline at end of file diff --git a/app/_kong_plugins/mocking/examples/example.yaml b/app/_kong_plugins/mocking/examples/example.yaml deleted file mode 100644 index 714b33873..000000000 --- a/app/_kong_plugins/mocking/examples/example.yaml +++ /dev/null @@ -1,15 +0,0 @@ -description: '' - -title: '' - -weight: 900 - -# requirements: <- not required -# - "some req" - -# variables: <- not required -# my-region: -# description: '' -# value: us - -config: # plugin config in yaml format goes here \ No newline at end of file From e16aad68bdcaca4127d280df2c596b5a9368d9eb Mon Sep 17 00:00:00 2001 From: Angel Date: Thu, 19 Dec 2024 12:10:39 -0500 Subject: [PATCH 09/21] Apply suggestions from code review Co-authored-by: Fabian Rodriguez --- .../cors/examples/basic-configuration.yaml | 38 ++- .../mocking/examples/basic-configuration.yaml | 237 +++++++++--------- 2 files changed, 133 insertions(+), 142 deletions(-) diff --git a/app/_kong_plugins/cors/examples/basic-configuration.yaml b/app/_kong_plugins/cors/examples/basic-configuration.yaml index c76562c9d..50d594bdd 100644 --- a/app/_kong_plugins/cors/examples/basic-configuration.yaml +++ b/app/_kong_plugins/cors/examples/basic-configuration.yaml @@ -5,24 +5,20 @@ description: | weight: 400 config: - plugins: - - name: cors - service: SERVICE_NAME|ID - config: - origins: - - http://mockbin.com - methods: - - GET - - POST - headers: - - Accept - - Accept-Version - - Content-Length - - Content-MD5 - - Content-Type - - Date - - X-Auth-Token - exposed_headers: - - X-Auth-Token - credentials: true - max_age: 3600 \ No newline at end of file + origins: + - http://mockbin.com + methods: + - GET + - POST + headers: + - Accept + - Accept-Version + - Content-Length + - Content-MD5 + - Content-Type + - Date + - X-Auth-Token + exposed_headers: + - X-Auth-Token + credentials: true + max_age: 3600 \ No newline at end of file diff --git a/app/_kong_plugins/mocking/examples/basic-configuration.yaml b/app/_kong_plugins/mocking/examples/basic-configuration.yaml index d7a82edf7..f5b59b8bf 100644 --- a/app/_kong_plugins/mocking/examples/basic-configuration.yaml +++ b/app/_kong_plugins/mocking/examples/basic-configuration.yaml @@ -1,125 +1,120 @@ title: Pass an OpenAPI spec to the plugin through decK description: | - Configures the mocking plugin and passes an API spec. + Configures the Mocking plugin and passes an API spec. weight: 400 -config: - plugins: - - name: mocking - service: SERVICE_NAME|ID - config: - random_delay: true - max_delay_time: 1 - min_delay_time: 0.001 - random_examples: true - api_specification: | - openapi: 3.0.2 - servers: - - url: /v3 - info: - description: |- - This is a sample Pet Store Server based on the OpenAPI 3.0 specification. You can find out more about - Swagger at [http://swagger.io](http://swagger.io). In the third iteration of the pet store, we've switched to the design first approach! - You can now help us improve the API whether it's by making changes to the definition itself or to the code. - That way, with time, we can improve the API in general, and expose some of the new features in OAS3. - - Some useful links: - - [The Pet Store repository](https://github.com/swagger-api/swagger-petstore) - - [The source API definition for the Pet Store](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml) - version: 1.0.20-SNAPSHOT - title: Swagger Petstore - OpenAPI 3.0 - termsOfService: 'http://swagger.io/terms/' - contact: - email: apiteam@swagger.io - license: - name: Apache 2.0 - url: 'http://www.apache.org/licenses/LICENSE-2.0.html' - tags: - - name: pet - description: Everything about your Pets - externalDocs: - description: Find out more - url: 'http://swagger.io' - - name: store - description: Access to Petstore orders - externalDocs: - description: Find out more about our store - url: 'http://swagger.io' - - name: user - description: Operations about user - paths: - /pet: - post: - tags: - - pet - summary: Add a new pet to the store - description: Add a new pet to the store - operationId: addPet - responses: - '200': - description: Successful operation - content: - application/xml: - schema: - $ref: '#/components/schemas/Pet' - application/json: - schema: - $ref: '#/components/schemas/Pet' - '405': - description: Invalid input - security: - - petstore_auth: - - 'write:pets' - - 'read:pets' - requestBody: - description: Create a new pet in the store - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/Pet' - application/xml: - schema: - $ref: '#/components/schemas/Pet' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/Pet' - put: - tags: - - pet - summary: Update an existing pet - description: Update an existing pet by Id - operationId: updatePet - responses: - '200': - description: Successful operation - content: - application/xml: - schema: - $ref: '#/components/schemas/Pet' - application/json: - schema: - $ref: '#/components/schemas/Pet' - '400': - description: Invalid ID supplied - '404': - description: Pet not found - '405': - description: Validation exception - security: - - petstore_auth: - - 'write:pets' - - 'read:pets' - requestBody: - description: Update an existent pet in the store - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/Pet' - application/xml: - schema: - $ref: '#/components/schemas/Pet' - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/Pet' \ No newline at end of file +config: + random_delay: true + max_delay_time: 1 + min_delay_time: 0.001 + random_examples: true + api_specification: | + openapi: 3.0.2 + servers: + - url: /v3 + info: + description: |- + This is a sample Pet Store Server based on the OpenAPI 3.0 specification. You can find out more about + Swagger at [http://swagger.io](http://swagger.io). In the third iteration of the pet store, we've switched to the design first approach! + You can now help us improve the API whether it's by making changes to the definition itself or to the code. + That way, with time, we can improve the API in general, and expose some of the new features in OAS3. + Some useful links: + - [The Pet Store repository](https://github.com/swagger-api/swagger-petstore) + - [The source API definition for the Pet Store](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml) + version: 1.0.20-SNAPSHOT + title: Swagger Petstore - OpenAPI 3.0 + termsOfService: 'http://swagger.io/terms/' + contact: + email: apiteam@swagger.io + license: + name: Apache 2.0 + url: 'http://www.apache.org/licenses/LICENSE-2.0.html' + tags: + - name: pet + description: Everything about your Pets + externalDocs: + description: Find out more + url: 'http://swagger.io' + - name: store + description: Access to Petstore orders + externalDocs: + description: Find out more about our store + url: 'http://swagger.io' + - name: user + description: Operations about user + paths: + /pet: + post: + tags: + - pet + summary: Add a new pet to the store + description: Add a new pet to the store + operationId: addPet + responses: + '200': + description: Successful operation + content: + application/xml: + schema: + $ref: '#/components/schemas/Pet' + application/json: + schema: + $ref: '#/components/schemas/Pet' + '405': + description: Invalid input + security: + - petstore_auth: + - 'write:pets' + - 'read:pets' + requestBody: + description: Create a new pet in the store + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Pet' + application/xml: + schema: + $ref: '#/components/schemas/Pet' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/Pet' + put: + tags: + - pet + summary: Update an existing pet + description: Update an existing pet by Id + operationId: updatePet + responses: + '200': + description: Successful operation + content: + application/xml: + schema: + $ref: '#/components/schemas/Pet' + application/json: + schema: + $ref: '#/components/schemas/Pet' + '400': + description: Invalid ID supplied + '404': + description: Pet not found + '405': + description: Validation exception + security: + - petstore_auth: + - 'write:pets' + - 'read:pets' + requestBody: + description: Update an existent pet in the store + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Pet' + application/xml: + schema: + $ref: '#/components/schemas/Pet' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/Pet' \ No newline at end of file From 3b1d1172437f67f6b458ea8711667bbd943389fb Mon Sep 17 00:00:00 2001 From: Angel Date: Thu, 19 Dec 2024 12:27:57 -0500 Subject: [PATCH 10/21] fixes --- .../allow-requests-from-specific-domain.yaml | 12 ++++++++++ .../cors/examples/basic-configuration.yaml | 24 ------------------- ... => mock-endpoints-using-an-api-spec.yaml} | 8 ++----- 3 files changed, 14 insertions(+), 30 deletions(-) create mode 100644 app/_kong_plugins/cors/examples/allow-requests-from-specific-domain.yaml delete mode 100644 app/_kong_plugins/cors/examples/basic-configuration.yaml rename app/_kong_plugins/mocking/examples/{basic-configuration.yaml => mock-endpoints-using-an-api-spec.yaml} (95%) diff --git a/app/_kong_plugins/cors/examples/allow-requests-from-specific-domain.yaml b/app/_kong_plugins/cors/examples/allow-requests-from-specific-domain.yaml new file mode 100644 index 000000000..04c846440 --- /dev/null +++ b/app/_kong_plugins/cors/examples/allow-requests-from-specific-domain.yaml @@ -0,0 +1,12 @@ +title: Allow requests from a specific domain +description: | + Configures the CORS plugin to allow `GET` and `POST` requests from a specific domain. + +weight: 400 + +config: + origins: + - http://mockbin.com + methods: + - GET + - POST \ No newline at end of file diff --git a/app/_kong_plugins/cors/examples/basic-configuration.yaml b/app/_kong_plugins/cors/examples/basic-configuration.yaml deleted file mode 100644 index 50d594bdd..000000000 --- a/app/_kong_plugins/cors/examples/basic-configuration.yaml +++ /dev/null @@ -1,24 +0,0 @@ -title: Configure the plugin on a Service -description: | - Configures the CORS plugin on a specific Service to accept common methods and headers from a specified Service. - -weight: 400 - -config: - origins: - - http://mockbin.com - methods: - - GET - - POST - headers: - - Accept - - Accept-Version - - Content-Length - - Content-MD5 - - Content-Type - - Date - - X-Auth-Token - exposed_headers: - - X-Auth-Token - credentials: true - max_age: 3600 \ No newline at end of file diff --git a/app/_kong_plugins/mocking/examples/basic-configuration.yaml b/app/_kong_plugins/mocking/examples/mock-endpoints-using-an-api-spec.yaml similarity index 95% rename from app/_kong_plugins/mocking/examples/basic-configuration.yaml rename to app/_kong_plugins/mocking/examples/mock-endpoints-using-an-api-spec.yaml index f5b59b8bf..d5598a7fa 100644 --- a/app/_kong_plugins/mocking/examples/basic-configuration.yaml +++ b/app/_kong_plugins/mocking/examples/mock-endpoints-using-an-api-spec.yaml @@ -1,13 +1,9 @@ -title: Pass an OpenAPI spec to the plugin through decK +title: Mock endpoints using an API spec description: | - Configures the Mocking plugin and passes an API spec. + Configures the Mocking plugin and passes a the [PetStore](https://petstore3.swagger.io/) API specification. weight: 400 config: - random_delay: true - max_delay_time: 1 - min_delay_time: 0.001 - random_examples: true api_specification: | openapi: 3.0.2 servers: From 5ce330d0ca38b3ebebb25915b2fa84ed4ad78b55 Mon Sep 17 00:00:00 2001 From: Fabian Rodriguez Date: Thu, 19 Dec 2024 15:49:17 -0300 Subject: [PATCH 11/21] Point /plugins/precedence/ to the docs site --- app/_includes/components/plugin_config_example/global.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_includes/components/plugin_config_example/global.md b/app/_includes/components/plugin_config_example/global.md index 2460f0183..3ef3af6de 100644 --- a/app/_includes/components/plugin_config_example/global.md +++ b/app/_includes/components/plugin_config_example/global.md @@ -4,5 +4,5 @@ A plugin which is not associated to any service, route, consumer, or consumer gr * In self-managed {{site.base_gateway}} (OSS), the plugin applies to your entire environment. * In Konnect, the plugin applies to every entity in a given control plane. -Read the [Plugin Reference](/api/gateway/admin-ee/#/operations/list-plugins-with-consumer) and the [Plugin Precedence](/plugins/precedence/) +Read the [Plugin Reference](/api/gateway/admin-ee/#/operations/list-plugins-with-consumer) and the [Plugin Precedence](https://docs.konghq.com/gateway/latest/key-concepts/plugins/#precedence) sections for more information. From 7545da60a49f41c77e2726fc7ed70fbbe0ebfd93 Mon Sep 17 00:00:00 2001 From: Fabian Rodriguez Date: Thu, 19 Dec 2024 15:58:46 -0300 Subject: [PATCH 12/21] Remove ai-proxy links from the plugin pages --- app/_includes/plugins/ai-plugins.md | 13 ------------- app/_includes/plugins/ai-proxy/links.md | 8 -------- app/_kong_plugins/ai-proxy-advanced/index.md | 1 - app/_kong_plugins/ai-proxy/index.md | 2 -- 4 files changed, 24 deletions(-) delete mode 100644 app/_includes/plugins/ai-plugins.md delete mode 100644 app/_includes/plugins/ai-proxy/links.md diff --git a/app/_includes/plugins/ai-plugins.md b/app/_includes/plugins/ai-plugins.md deleted file mode 100644 index 5837de78d..000000000 --- a/app/_includes/plugins/ai-plugins.md +++ /dev/null @@ -1,13 +0,0 @@ -### All AI Gateway plugins - -* [AI Proxy](/plugins/ai-proxy) -* [AI Proxy Advanced](/plugins/ai-proxy-advanced) -* [AI Request Transformer](/plugins/ai-request-transformer) -* [AI Response Transformer](/plugins/ai-response-transformer) -* [AI Semantic Cache](/plugins/ai-semantic-cache) -* [AI Semantic Prompt Guard](/plugins/ai-semantic-prompt-guard) -* [AI Rate Limiting Advanced](/plugins/ai-rate-limiting-advanced) -* [AI Azure Content Safety](/plugins/ai-azure-content-safety) -* [AI Prompt Template](/plugins/ai-prompt-template) -* [AI Prompt Guard](/plugins/ai-prompt-guard) -* [AI Prompt Decorator](/plugins/ai-prompt-decorator) \ No newline at end of file diff --git a/app/_includes/plugins/ai-proxy/links.md b/app/_includes/plugins/ai-proxy/links.md deleted file mode 100644 index 128becc80..000000000 --- a/app/_includes/plugins/ai-proxy/links.md +++ /dev/null @@ -1,8 +0,0 @@ -{% assign plugin = include.plugin %} -{% assign id = plugin | slugify %} - -## Get started -* [Configuration reference](/plugins/{{ id }}/reference/) -* [Configuration examples](/plugins/{{ id }}/examples/) - -{% include plugins/ai-plugins.md %} \ No newline at end of file diff --git a/app/_kong_plugins/ai-proxy-advanced/index.md b/app/_kong_plugins/ai-proxy-advanced/index.md index dcc5b0203..8475d158b 100644 --- a/app/_kong_plugins/ai-proxy-advanced/index.md +++ b/app/_kong_plugins/ai-proxy-advanced/index.md @@ -55,4 +55,3 @@ This plugin does not support fallback over targets with different formats. You c > Some errors, such as client errors, result in a failure and don't failover to another target. {% include plugins/ai-proxy/formats.md plugin=page.name params=site.data.plugins.ai-proxy-advanced.parameters %} -{% include plugins/ai-proxy/links.md plugin=page.name %} diff --git a/app/_kong_plugins/ai-proxy/index.md b/app/_kong_plugins/ai-proxy/index.md index e2c66f11b..413c9ff70 100644 --- a/app/_kong_plugins/ai-proxy/index.md +++ b/app/_kong_plugins/ai-proxy/index.md @@ -36,5 +36,3 @@ categories: -{% include plugins/ai-proxy/links.md plugin=page.name %} - From f90cdd3e8ef9c85c62edeceda99df919f17e7231 Mon Sep 17 00:00:00 2001 From: Angel Date: Wed, 18 Dec 2024 17:14:44 -0500 Subject: [PATCH 13/21] pull out upstreams --- app/_gateway_entities/upstream.md | 77 ++++++++++++++++++++++++++++--- 1 file changed, 70 insertions(+), 7 deletions(-) diff --git a/app/_gateway_entities/upstream.md b/app/_gateway_entities/upstream.md index 1967e6659..9980ee653 100644 --- a/app/_gateway_entities/upstream.md +++ b/app/_gateway_entities/upstream.md @@ -1,9 +1,12 @@ --- -title: Upstreams +title: Upstreams content_type: reference entities: - upstream +products: + - gateway + tools: - admin-api - kic @@ -12,19 +15,79 @@ tools: description: An upstream refers to the service applications sitting behind {{site.base_gateway}}, to which client requests are forwarded. +related_resources: + - text: Gateway Service entity + url: /gateway/entities/service/ + - text: Route entity + url: /gateway/entities/route/ + - text: Target entity + url: /gateway/entities/target/ + - text: Routing in {{site.base_gateway}} + url: /gateway/routing/ + - text: Expressions router + url: /gateway/routing/expressions/ + - text: Proxying with {{site.base_gateway}} + url: /gateway/traffic-control/proxy/ + schema: api: gateway/admin-ee path: /schemas/Upstream - --- -## What is an upstream? +## What is an Upstream? + +{{page.description}} In {{site.base_gateway}}, an Upstream represents a virtual hostname and can be used to [health check, circuit break], and [load balance] incoming requests over multiple [Gateway Services](/gateway/entities/service/). In addition, the Upstream entity has more advanced functionality algorithms like least-connections, consistent-hashing, and lowest-latency. + +If you don't need to load balance, we recommend using the `host` header on a [Route](/gateway/entities/route/) as the preferred method for routing a request and proxying traffic. + +## Upstream and Service interaction + +You can configure a Service to point to an Upstream instead of a host. +For example, if you have a Service called `example_service` and an Upstream called `example_upstream`, you can point `example_service` to `example_upstream` instead of specifying a host. +The `example_upstream` Upstream can then point to two different [Targets](/gateway/entities/target/): `httpbin.konghq.com` and `httpbun.com`. +In a real environment, the Upstream points to the same Service running on multiple systems. + +This setup allows you to load balance between upstream targets. +For example, if an application is deployed across two different servers or upstream targets, {{site.base_gateway}} needs to load balance across both servers. +If one of the servers (like `httpbin.konghq.com` in the previous example) is unavailable, it automatically detects the problem and routes all traffic to the working server (`httpbun.com`). + +The following diagram shows how Upstreams interact with other {{site.base_gateway}} entities: + + + +{% mermaid %} +flowchart LR + A("`Route + (/mock)`") + B("`Service + (example_service)`") + C(Upstream load balancer) + D(httpbin.konghq.com) + E(httpbun.com) + + subgraph id1 ["`**KONG GATEWAY**`"] + A --> B --> C + end + + subgraph id2 ["`Targets (example_upstream)`"] + C --> D & E + end + + style id1 rx:10,ry:10 + style id2 stroke:none +{% endmermaid %} + + -{{page.description}} In {{site.base_gateway}}, an upstream represents a virtual hostname and can be used to health check, circuit break, and load balance incoming requests over multiple [target](/gateway/entities/target/) backend services. +## Use cases for Upstreams -## Use cases for upstreams +The following are examples of common use cases for Upstreams: -The following are examples of common use cases for upstreams: +| Use case | Description | +|----------|-------------| +| Load balance | When an Upstream points to multiple upstream targets, you can configure the Upstream entity to load balance traffic between the targets. | +| Health check | Configure Upstreams to dynamically mark a target as healthy or unhealthy. This is an active check where a specific HTTP or HTTPS endpoint in the target is periodically requested and the health of the target is determined based on its response. | +| Circuit break | Configure Upstreams to allow {{site.base_gateway}} to passively analyze the ongoing traffic being proxied and determine the health of targets based on their behavior responding to requests. **Note:** This feature is not supported in hybrid mode. | ## Schema @@ -40,4 +103,4 @@ data: - user-level - low-priority algorithm: round-robin -{% endentity_example %} +{% endentity_example %} \ No newline at end of file From 8580148c2c12718547629ee385f213d9c23d4209 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Thu, 19 Dec 2024 08:47:24 -0600 Subject: [PATCH 14/21] Apply Fabian's feedback Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_gateway_entities/upstream.md | 9 ++++----- app/_includes/components/entity_example/format/ui.md | 8 ++++++++ 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/app/_gateway_entities/upstream.md b/app/_gateway_entities/upstream.md index 9980ee653..73f2e82ca 100644 --- a/app/_gateway_entities/upstream.md +++ b/app/_gateway_entities/upstream.md @@ -13,7 +13,7 @@ tools: - deck - terraform -description: An upstream refers to the service applications sitting behind {{site.base_gateway}}, to which client requests are forwarded. +description: An Upstream refers to the service applications sitting behind {{site.base_gateway}}, to which client requests are forwarded. related_resources: - text: Gateway Service entity @@ -36,11 +36,11 @@ schema: ## What is an Upstream? -{{page.description}} In {{site.base_gateway}}, an Upstream represents a virtual hostname and can be used to [health check, circuit break], and [load balance] incoming requests over multiple [Gateway Services](/gateway/entities/service/). In addition, the Upstream entity has more advanced functionality algorithms like least-connections, consistent-hashing, and lowest-latency. +An Upstream refers to the service applications sitting behind {{site.base_gateway}}, to which client requests are forwarded. In {{site.base_gateway}}, an Upstream represents a virtual hostname and can be used to [health check, circuit break](https://docs.konghq.com/gateway/latest/how-kong-works/health-checks/), and [load balance](https://docs.konghq.com/gateway/latest/how-kong-works/load-balancing/) incoming requests over multiple [Gateway Services](/gateway/entities/service/). In addition, the Upstream entity has more advanced functionality algorithms like least-connections, consistent-hashing, and lowest-latency. If you don't need to load balance, we recommend using the `host` header on a [Route](/gateway/entities/route/) as the preferred method for routing a request and proxying traffic. -## Upstream and Service interaction +## Upstream and Gateway Service interaction You can configure a Service to point to an Upstream instead of a host. For example, if you have a Service called `example_service` and an Upstream called `example_upstream`, you can point `example_service` to `example_upstream` instead of specifying a host. @@ -69,11 +69,10 @@ flowchart LR A --> B --> C end - subgraph id2 ["`Targets (example_upstream)`"] + subgraph id2 ["`Targets`"] C --> D & E end - style id1 rx:10,ry:10 style id2 stroke:none {% endmermaid %} diff --git a/app/_includes/components/entity_example/format/ui.md b/app/_includes/components/entity_example/format/ui.md index 5ba92bdda..a8439b735 100644 --- a/app/_includes/components/entity_example/format/ui.md +++ b/app/_includes/components/entity_example/format/ui.md @@ -43,6 +43,14 @@ The following creates a new service called **{{ include.presenter.data['name'] } 5. Click **Save**. {% when 'target' %} {% when 'upstream' %} +The following creates a new Upstream with basic configuration: + +1. In Kong Manager or Gateway Manager, click the Workspace you want to add the Upstream to. +1. Click **Upstreams** in the sidebar. +1. Click **New Upstream**. +1. Enter or select a host in the **Name** field. +1. Configure load balancing and health check settings as needed. +1. Click **Save**. {% when workspace %} {% else %} {% endcase %} From 9d4a00ffa2960643607e4171193f328667eb1382 Mon Sep 17 00:00:00 2001 From: Lucie Milan Date: Thu, 19 Dec 2024 17:25:51 +0100 Subject: [PATCH 15/21] Create upstreams-targets-diagram.md --- .../entities/upstreams-targets-diagram.md | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 app/_includes/entities/upstreams-targets-diagram.md diff --git a/app/_includes/entities/upstreams-targets-diagram.md b/app/_includes/entities/upstreams-targets-diagram.md new file mode 100644 index 000000000..998553e2d --- /dev/null +++ b/app/_includes/entities/upstreams-targets-diagram.md @@ -0,0 +1,36 @@ + + +{% mermaid %} +flowchart LR + + A("Request") + B("`Route + (/mock)`") + C("`Service + (example_service)`") + D("Target + (httpbin.konghq.com)") + E("Target + (httpbun.com)") + F(httpbin.konghq.com) + G(httpbun.com) + + A --> B + subgraph id1 ["`**KONG GATEWAY**`"] + B --> C --> D & E + subgraph id3 ["`**Upstream**`"] + D & E + end + + end + + subgraph id2 ["`**Upstream targets**`"] + D --> F + E --> G + + end + + style id2 stroke:none +{% endmermaid %} + + \ No newline at end of file From 91011f1edf4a69c903172c874fbaae68d67347c7 Mon Sep 17 00:00:00 2001 From: Lucie Milan Date: Thu, 19 Dec 2024 17:36:53 +0100 Subject: [PATCH 16/21] Update upstreams-targets-diagram.md --- app/_includes/entities/upstreams-targets-diagram.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/app/_includes/entities/upstreams-targets-diagram.md b/app/_includes/entities/upstreams-targets-diagram.md index 998553e2d..f759b3f98 100644 --- a/app/_includes/entities/upstreams-targets-diagram.md +++ b/app/_includes/entities/upstreams-targets-diagram.md @@ -18,7 +18,8 @@ flowchart LR A --> B subgraph id1 ["`**KONG GATEWAY**`"] B --> C --> D & E - subgraph id3 ["`**Upstream**`"] + subgraph id3 ["`**Upstream** (load balancer)`"] + D & E end From 6839c3cae81ccfdd92125992c4c113d168f56631 Mon Sep 17 00:00:00 2001 From: Lucie Milan Date: Thu, 19 Dec 2024 17:40:52 +0100 Subject: [PATCH 17/21] Update upstream.md --- app/_gateway_entities/upstream.md | 31 +++---------------------------- 1 file changed, 3 insertions(+), 28 deletions(-) diff --git a/app/_gateway_entities/upstream.md b/app/_gateway_entities/upstream.md index 73f2e82ca..0eddcc26d 100644 --- a/app/_gateway_entities/upstream.md +++ b/app/_gateway_entities/upstream.md @@ -36,9 +36,7 @@ schema: ## What is an Upstream? -An Upstream refers to the service applications sitting behind {{site.base_gateway}}, to which client requests are forwarded. In {{site.base_gateway}}, an Upstream represents a virtual hostname and can be used to [health check, circuit break](https://docs.konghq.com/gateway/latest/how-kong-works/health-checks/), and [load balance](https://docs.konghq.com/gateway/latest/how-kong-works/load-balancing/) incoming requests over multiple [Gateway Services](/gateway/entities/service/). In addition, the Upstream entity has more advanced functionality algorithms like least-connections, consistent-hashing, and lowest-latency. - -If you don't need to load balance, we recommend using the `host` header on a [Route](/gateway/entities/route/) as the preferred method for routing a request and proxying traffic. +An Upstream refers to the service applications sitting behind {{site.base_gateway}}, to which client requests are forwarded. In {{site.base_gateway}}, an Upstream represents a virtual hostname and can be used to [health check](https://docs.konghq.com/gateway/latest/how-kong-works/health-checks/#active-health-checks), [circuit break](https://docs.konghq.com/gateway/latest/how-kong-works/health-checks/#passive-health-checks-circuit-breakers), and [load balance](https://docs.konghq.com/gateway/latest/how-kong-works/load-balancing/) incoming requests over multiple [Gateway Services](/gateway/entities/service/). In addition, the Upstream entity has more advanced functionality algorithms like least-connections, consistent-hashing, and lowest-latency. ## Upstream and Gateway Service interaction @@ -53,30 +51,7 @@ If one of the servers (like `httpbin.konghq.com` in the previous example) is una The following diagram shows how Upstreams interact with other {{site.base_gateway}} entities: - - -{% mermaid %} -flowchart LR - A("`Route - (/mock)`") - B("`Service - (example_service)`") - C(Upstream load balancer) - D(httpbin.konghq.com) - E(httpbun.com) - - subgraph id1 ["`**KONG GATEWAY**`"] - A --> B --> C - end - - subgraph id2 ["`Targets`"] - C --> D & E - end - - style id2 stroke:none -{% endmermaid %} - - +{% include entities/upstreams-targets-diagram.md %} ## Use cases for Upstreams @@ -84,7 +59,7 @@ The following are examples of common use cases for Upstreams: | Use case | Description | |----------|-------------| -| Load balance | When an Upstream points to multiple upstream targets, you can configure the Upstream entity to load balance traffic between the targets. | +| Load balance | When an Upstream points to multiple upstream targets, you can configure the Upstream entity to load balance traffic between the targets. If you don't need to load balance, we recommend using the `host` header on a [Route](/gateway/entities/route/) as the preferred method for routing a request and proxying traffic.| | Health check | Configure Upstreams to dynamically mark a target as healthy or unhealthy. This is an active check where a specific HTTP or HTTPS endpoint in the target is periodically requested and the health of the target is determined based on its response. | | Circuit break | Configure Upstreams to allow {{site.base_gateway}} to passively analyze the ongoing traffic being proxied and determine the health of targets based on their behavior responding to requests. **Note:** This feature is not supported in hybrid mode. | From 44db2b0c35741f6239c28a3db62948f2436f2267 Mon Sep 17 00:00:00 2001 From: Angel Date: Thu, 19 Dec 2024 13:35:52 -0500 Subject: [PATCH 18/21] upstream --- app/_gateway_entities/upstream.md | 9 ++------- app/_includes/components/entity_example/format/ui.md | 6 ++---- 2 files changed, 4 insertions(+), 11 deletions(-) diff --git a/app/_gateway_entities/upstream.md b/app/_gateway_entities/upstream.md index 0eddcc26d..0e225a2a9 100644 --- a/app/_gateway_entities/upstream.md +++ b/app/_gateway_entities/upstream.md @@ -1,5 +1,5 @@ --- -title: Upstreams +title: Upstreams content_type: reference entities: - upstream @@ -26,8 +26,6 @@ related_resources: url: /gateway/routing/ - text: Expressions router url: /gateway/routing/expressions/ - - text: Proxying with {{site.base_gateway}} - url: /gateway/traffic-control/proxy/ schema: api: gateway/admin-ee @@ -72,9 +70,6 @@ The following are examples of common use cases for Upstreams: {% entity_example %} type: upstream data: - name: api.example.internal - tags: - - user-level - - low-priority + name: example-upstream algorithm: round-robin {% endentity_example %} \ No newline at end of file diff --git a/app/_includes/components/entity_example/format/ui.md b/app/_includes/components/entity_example/format/ui.md index a8439b735..4d9c97ae1 100644 --- a/app/_includes/components/entity_example/format/ui.md +++ b/app/_includes/components/entity_example/format/ui.md @@ -45,11 +45,9 @@ The following creates a new service called **{{ include.presenter.data['name'] } {% when 'upstream' %} The following creates a new Upstream with basic configuration: -1. In Kong Manager or Gateway Manager, click the Workspace you want to add the Upstream to. -1. Click **Upstreams** in the sidebar. +1. In Kong Manager or Gateway Manager, Navigate to **Workspaces** > **Upstreams**. 1. Click **New Upstream**. -1. Enter or select a host in the **Name** field. -1. Configure load balancing and health check settings as needed. +1. Enter a unique name for the Upstream. For example: `{{ include.presenter.data['name'] }}`. 1. Click **Save**. {% when workspace %} {% else %} From 79c5ea945c66c54229fca71a97b7d22f4df95a83 Mon Sep 17 00:00:00 2001 From: Angel Date: Thu, 19 Dec 2024 14:15:36 -0500 Subject: [PATCH 19/21] Update app/_kong_plugins/mocking/examples/mock-endpoints-using-an-api-spec.yaml --- .../mocking/examples/mock-endpoints-using-an-api-spec.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_kong_plugins/mocking/examples/mock-endpoints-using-an-api-spec.yaml b/app/_kong_plugins/mocking/examples/mock-endpoints-using-an-api-spec.yaml index d5598a7fa..782477b4f 100644 --- a/app/_kong_plugins/mocking/examples/mock-endpoints-using-an-api-spec.yaml +++ b/app/_kong_plugins/mocking/examples/mock-endpoints-using-an-api-spec.yaml @@ -1,6 +1,6 @@ title: Mock endpoints using an API spec description: | - Configures the Mocking plugin and passes a the [PetStore](https://petstore3.swagger.io/) API specification. + Configures the Mocking plugin and passes the [PetStore](https://petstore3.swagger.io/) API specification. weight: 400 config: From 16c04e560c225d1275e7f36aa42de5fe70d3b8bc Mon Sep 17 00:00:00 2001 From: Angel Date: Thu, 19 Dec 2024 14:24:13 -0500 Subject: [PATCH 20/21] things --- app/_includes/info_box/reference.html | 4 ++++ app/_kong_plugins/cors/index.md | 2 +- app/_kong_plugins/mocking/index.md | 10 +++++----- app/gateway/networking/dns-config-reference.md | 12 ++++-------- 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/app/_includes/info_box/reference.html b/app/_includes/info_box/reference.html index 825579295..5f1681ad8 100644 --- a/app/_includes/info_box/reference.html +++ b/app/_includes/info_box/reference.html @@ -15,6 +15,10 @@ {% endif %} +{% if page.plugins %} +{% include info_box/sections/plugins.html plugins=page.plugins %} +{% endif %} + {% if page.related_resources %} {% include info_box/sections/related_resources.html %} {% endif %} \ No newline at end of file diff --git a/app/_kong_plugins/cors/index.md b/app/_kong_plugins/cors/index.md index 53a0d47ba..09a4d62e6 100644 --- a/app/_kong_plugins/cors/index.md +++ b/app/_kong_plugins/cors/index.md @@ -24,7 +24,7 @@ topologies: related_resources: - text: DNS configuration reference - url: /gateway/networking/dns-config-reference + url: /gateway/networking/dns-config-reference/ icon: cors.png diff --git a/app/_kong_plugins/mocking/index.md b/app/_kong_plugins/mocking/index.md index a2713741d..ce2a70f6b 100644 --- a/app/_kong_plugins/mocking/index.md +++ b/app/_kong_plugins/mocking/index.md @@ -17,16 +17,16 @@ works_on: - on-prem - konnect -# topologies: -# - hybrid -# - db-less -# - traditional +topologies: + - hybrid + - db-less + - traditional icon: mocking.png related_resources: - text: DNS configuration reference - url: /gateway/networking/dns-config-reference + url: /gateway/networking/dns-config-reference/ categories: - traffic-control diff --git a/app/gateway/networking/dns-config-reference.md b/app/gateway/networking/dns-config-reference.md index f89579fde..9b234d635 100644 --- a/app/gateway/networking/dns-config-reference.md +++ b/app/gateway/networking/dns-config-reference.md @@ -12,20 +12,16 @@ products: plugins: - cors - mocking - - sessions - - oidc - -related_resources: - - text: Kong Plugins - url: /plugins/cors + - session + - openid-connect breadcrumbs: - - /gateway/networking/dns-config-reference + - /gateway/networking/dns-config-reference/ --- ## Overview -{{page.description}}. {{site.base_gateway}} provides Kong Manager, which must be able to interact with the Admin API. This application is subject to security restrictions enforced by browsers, and Kong must send appropriate information to browsers in order for it to function properly. +{{site.base_gateway}} provides Kong Manager, which must be able to interact with the Admin API. This application is subject to security restrictions enforced by browsers, and Kong must send appropriate information to browsers in order for it to function properly. These security restrictions use the applications’ DNS hostnames to evaluate whether the applications’ metadata satisfies the security constraints. As such, you must design your DNS structure to meet the requirements. From 90ec8cff79210a278b4c912ae4a50608e8ec10cf Mon Sep 17 00:00:00 2001 From: Fabian Rodriguez Date: Thu, 19 Dec 2024 20:28:38 +0100 Subject: [PATCH 21/21] Remove reference to /traffic-control/proxy --- app/_kong_plugins/cors/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/app/_kong_plugins/cors/index.md b/app/_kong_plugins/cors/index.md index 09a4d62e6..3e643bd0d 100644 --- a/app/_kong_plugins/cors/index.md +++ b/app/_kong_plugins/cors/index.md @@ -52,5 +52,4 @@ Because of this limitation, this plugin only works for routes that have been configured with a `paths` setting. The CORS plugin does not work for routes that are being resolved using a custom DNS (the `hosts` property). -To learn how to configure `paths` for a route, read the [Proxy Reference](/gateway/traffic-control/proxy/).