Merge branch 'main' into event-hooks

app/_gateway_entities/upstream.md

@@ -4,27 +4,62 @@ content_type: reference
 entities:
   - upstream
 
+products:
+  - gateway
+
 tools:
     - admin-api
     - kic
     - 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
+    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/
 
 schema:
     api: gateway/admin-ee
     path: /schemas/Upstream
-
 ---
 
-## What is an upstream?
+## 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](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
+
+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:
+
+{% include entities/upstreams-targets-diagram.md %}
 
-{{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. 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. |
 
 ## Schema
 
@@ -35,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 %}
+{% endentity_example %}

app/_includes/components/entity_example/format/ui.md

@@ -43,6 +43,12 @@ 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, Navigate to **Workspaces** > **Upstreams**.
+1. Click **New Upstream**.
+1. Enter a unique name for the Upstream. For example: `{{ include.presenter.data['name'] }}`.
+1. Click **Save**.
 {% when workspace %}
 {% else %}
 {% endcase %}

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. 

app/_includes/entities/upstreams-targets-diagram.md

@@ -0,0 +1,37 @@
+<!--vale off-->
+
+{% 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** (load balancer)`"]
+
+    D & E
+  end
+
+  end
+
+  subgraph id2 ["`**Upstream targets**`"]
+    D --> F
+    E --> G
+
+  end
+
+  style id2 stroke:none
+{% endmermaid %}
+
+<!--vale on-->

app/_includes/info_box/reference.html

@@ -15,6 +15,10 @@
 </div>
 {% 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 %}

app/_includes/sections/cors-and-kong-gateway.md

@@ -0,0 +1,47 @@
+
+## Understanding CORS
+
+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.
+
+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
+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: *
+```
+
+The 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.

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 %}

app/_kong_plugins/ai-proxy/index.md

@@ -36,5 +36,3 @@ categories:
 <!-- {:.note}
 > Check out the [AI Gateway quickstart](/gateway/latest/get-started/ai-gateway/) to get an AI proxy up and running within minutes! -->
 
-{% include plugins/ai-proxy/links.md plugin=page.name %}
-

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

app/_kong_plugins/cors/index.md

@@ -5,26 +5,51 @@ name: 'CORS'
 content_type: plugin
 
 publisher: kong-inc
-description: 'Allow developers to make requests from the browser'
+
+description: 'The CORS plugin lets you add Cross-Origin Resource Sharing (CORS) to a service or a route.'
 
 
 products:
     - gateway
 
+
 works_on:
     - on-prem
     - konnect
+topologies:
+    - hybrid
+    - db-less
+    - traditional
 
 
-# topologies:
-#    - hybrid
-#    - db-less
-#    - traditional
+related_resources:
+  - text: DNS configuration reference
+    url: /gateway/networking/dns-config-reference/
 
 icon: cors.png
 
 categories:
   - security
+
 ---
 
 ## 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 upstreams only accept and share resources with 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).
+
+

app/_kong_plugins/cors/reference.yaml

@@ -0,0 +1 @@
+content_type: plugin_reference