From b5fa1bc402e7dec33731ce23fd9d2686b8b0ea14 Mon Sep 17 00:00:00 2001 From: dfitzmau Date: Wed, 2 Sep 2026 15:32:34 +0100 Subject: [PATCH] OSDOCS-21849: Documented the CORS filter in Gateway API docs --- ...aring-openshift-routes-and-httproutes.adoc | 1 + modules/supported-httproute-filters.adoc | 50 ++++++++++++++++--- .../routing-http-requests-to-services.adoc | 8 ++- 3 files changed, 50 insertions(+), 9 deletions(-) diff --git a/modules/comparing-openshift-routes-and-httproutes.adoc b/modules/comparing-openshift-routes-and-httproutes.adoc index 318c85bc602..a0b25d41212 100644 --- a/modules/comparing-openshift-routes-and-httproutes.adoc +++ b/modules/comparing-openshift-routes-and-httproutes.adoc @@ -17,6 +17,7 @@ The following features are exclusive to `HTTPRoute` CRs: * Request header modification * Request redirection * Request mirroring +* Cross-Origin Resource Sharing (CORS) The following features are exclusive to {product-title} routes: diff --git a/modules/supported-httproute-filters.adoc b/modules/supported-httproute-filters.adoc index 5040e986260..0beaf12f657 100644 --- a/modules/supported-httproute-filters.adoc +++ b/modules/supported-httproute-filters.adoc @@ -7,24 +7,28 @@ = Supported HTTPRoute filters [role="_abstract"] -Filters apply processing directions to the HTTP request, such as header modification or redirect to another URL. You can specify up to 16 filters in a rule. Filters may usually be combined for advanced filtering results, except for the urlRewrite and requestRedirect filters, which may not be combined. +Filters apply processing directions to the HTTP request, such as header modification or redirect to another URL. You can specify up to 16 filters in a rule. Filters may usually be combined for advanced filtering results, except for the urlRewrite and `requestRedirect` filters, which may not be combined. You can apply the following filter types to a rule: `requestRedirect`:: -Responds to an HTTP request with an HTTP 3xx code, instructing the client to retrieve another URL. Optional fields include scheme (http | https), hostname, path (type: replaceFullPath | replacePrefixMatch, string values for replaceFullPath or replacePrefixMatch), port, and statusCode (301 | 302 | 303 | 307 | 308). +Responds to an HTTP request with an HTTP 3xx code, instructing the client to retrieve another URL. Optional fields include scheme (`http | https`), hostname, path (`type: replaceFullPath | replacePrefixMatch`, string values for `replaceFullPath` or `replacePrefixMatch`), `port`, and `statusCode` (`301 | 302 | 303 | 307 | 308`). `requestHeaderModifier`:: -Modifies an HTTP request’s headers. Only one modifier per header may be specified. Multiple values for a header must be comma-separated. Up to 16 header filters may be listed. Fields are one of Set, Add, Remove. Set, Add, and Remove may modify, add, and remove up to 16 header values that match a given name. +Modifies an HTTP request’s headers. Only one modifier per header may be specified. Multiple values for a header must be comma-separated. Up to 16 header filters may be listed. Fields are one of `Set`, `Add`, `Remove`. These fields might modify, add, and remove up to 16 header values that match a given name. `responseHeaderModifier`:: -Available on {SMProductName}, this extended filter modifies an HTTP response’s headers with the same constraints as requestHeaderModifier. +Available on {SMProductName}, this extended filter modifies an HTTP response’s headers with the same constraints as `requestHeaderModifier`. `requestMirror`:: -Available on {SMProductName}, this extended filter mirrors (i.e. sends a duplicate) requests to specified destinations (backendRef). Fields include: backendRef, and the optional percent or fraction to specify the portion of requests that should be mirrored. If neither percent nor fraction are specified, then 100% of requests are mirrored. +Available on {SMProductName}, this extended filter mirrors (sends duplicate) requests to specified destinations (`backendRef`). Fields include: `backendRef`, and the optional percent or fraction to specify the portion of requests that should be mirrored. If neither percent nor fraction are specified, then 100% of requests are mirrored. `urlRewrite`:: -Available on {SMProductName}, this extended filter modifies an HTTP request’s hostname, path, or both. It may not be used in combination with the requestRedirect filter. However, the path semantics for requestRedirect can also be used for urlRewrite, i.e. (type: replaceFullPath | replacePrefixMatch, string values for replaceFullPath or replacePrefixMatch). +Available on {SMProductName}, this extended filter modifies an HTTP request’s hostname, path, or both. The filter cannot be used in combination with the `requestRedirect` filter. However, the path semantics for `requestRedirect` can be used for `urlRewrite`. For example `type: replaceFullPath | replacePrefixMatch`, string values for `replaceFullPath` or `replacePrefixMatch`. + +`cors`:: +Available on {SMProductName} and this extended filter configures Cross-Origin Resource Sharing (CORS). CORS lets a browser permit a web application from one origin to access resources from a different origin. Use a CORS filter when a browser-based application needs to request resources from a different origin. The gateway applies the policy and answers pre-flight requests directly, so your backend services do not have to implement CORS themselves. Fields include `allowOrigins`, `allowMethods`, `allowHeaders`, `exposeHeaders`, `allowCredentials`, and `maxAge`. For information, see "Cross-Origin Resource Sharing". + == Example: requestRedirect filter @@ -50,7 +54,7 @@ spec:         scheme: https         statusCode: 301 ---- -* `hostnames` defines the domain, such as `""`, that this route applies to. +* `hostnames` defines the domain, such as ``, that this route applies to. * `filters` specifies the processing logic. In this example, the `RequestRedirect` type is used. * `scheme: https` instructs the gateway to redirect the client to the secure version of the URL. * `statusCode: 301` indicates a permanent redirect. @@ -77,4 +81,34 @@ spec:     - type: RequestHeaderModifier       requestHeaderModifier:         remove: ["x-request-id"] ----- \ No newline at end of file +---- + +== Example: cors filter + +The following snippet demonstrates how to configure a `cors` filter that allows a browser-based application served from a different origin to call your backend: + +[source,yaml] +---- +spec: + rules: + - filters: + - type: CORS + cors: + allowOrigins: + - "https://" + allowMethods: + - GET + - POST + allowHeaders: + - Content-Type + exposeHeaders: + - X-Custom-Response-Header + allowCredentials: true + maxAge: 3600 +---- +* `allowOrigins` lists the origins the browser is permitted to make cross-origin requests from, such as `\https://`. +* `allowMethods` lists the HTTP methods allowed for cross-origin requests. +* `allowHeaders` lists the request headers a client is allowed to send. +* `exposeHeaders` lists the response headers the browser is allowed to read. +* `allowCredentials` where the value of `true` permits the browser to send credentials, such as cookies, with the request. +* `maxAge` with the value `3600` tells the browser to cache the pre-flight response for `3600` seconds. diff --git a/networking/ingress_load_balancing/configuring_gateway_api/routing-http-requests-to-services.adoc b/networking/ingress_load_balancing/configuring_gateway_api/routing-http-requests-to-services.adoc index 5cc3c7efc77..5d88b7373ea 100644 --- a/networking/ingress_load_balancing/configuring_gateway_api/routing-http-requests-to-services.adoc +++ b/networking/ingress_load_balancing/configuring_gateway_api/routing-http-requests-to-services.adoc @@ -34,4 +34,10 @@ include::modules/setting-timeouts-http-requests.adoc[leveloffset=+1] include::modules/httproute-timeout-configuration.adoc[leveloffset=+2] -include::modules/comparing-openshift-routes-and-httproutes.adoc[leveloffset=+1] \ No newline at end of file +include::modules/comparing-openshift-routes-and-httproutes.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources + +* link:https://gateway-api.sigs.k8s.io/guides/user-guides/http-cors/[Cross-Origin Resource Sharing (Gateway API documentation)]