diff --git a/nav.yml b/nav.yml index 8ab7c9730b..4ce3877100 100644 --- a/nav.yml +++ b/nav.yml @@ -32,6 +32,10 @@ nav: - HTTP header modifier: guides/http-header-modifier.md - HTTP traffic splitting: guides/traffic-splitting.md - HTTP request mirroring: guides/http-request-mirroring.md + - HTTP query parameter matching: guides/http-query-param-matching.md + - HTTP method matching: guides/http-method-matching.md + - HTTP timeouts: guides/http-timeouts.md + - HTTP CORS: guides/http-cors.md - Cross-Namespace routing: guides/multiple-ns.md - TLS: guides/tls.md - TCP routing: guides/tcp.md diff --git a/site-src/guides/http-cors.md b/site-src/guides/http-cors.md new file mode 100644 index 0000000000..3ca7078310 --- /dev/null +++ b/site-src/guides/http-cors.md @@ -0,0 +1,74 @@ +# Cross-Origin Resource Sharing (CORS) + +???+ info "Experimental Channel Feature: HTTPRouteCORS" + This feature is in the `experimental` channel. For more information on release channels, refer to our [versioning guide](../concepts/versioning.md). + +The [HTTPRoute resource](../api-types/httproute.md) can be used to configure +Cross-Origin Resource Sharing (CORS). CORS is a security feature that allows +or denies web applications running at one domain to make requests for resources +from a different domain. + +The `CORS` filter in an `HTTPRouteRule` can be used to specify the CORS policy. + +## Allowing requests from a specific origin + +The following `HTTPRoute` allows requests from `https://app.example`: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: cors-allow-credentials + namespace: gateway-conformance-infra +spec: + parentRefs: + - name: same-namespace + rules: + - matches: + - path: + type: PathPrefix + value: /cors-behavior-creds-false + backendRefs: + - name: infra-backend-v1 + port: 8080 + filters: + - cors: + allowOrigins: + - https://app.example + allowCredentials: false + type: CORS +``` + +## Allowing credentials + +The `allowCredentials` field specifies whether the browser should include +credentials (such as cookies and HTTP authentication) in the CORS request. + +The following rule allows requests from `https://app.example` with +credentials: + +```yaml + - matches: + - path: + type: PathPrefix + value: /cors-behavior-creds-true + backendRefs: + - name: infra-backend-v1 + port: 8080 + filters: + - cors: + allowOrigins: + - https://app.example + allowCredentials: true + type: CORS +``` + +## Other CORS options + +The `CORS` filter also allows you to specify other CORS options, such as: + +- `allowMethods`: The HTTP methods that are allowed for CORS requests. +- `allowHeaders`: The HTTP headers that are allowed for CORS requests. +- `exposeHeaders`: The HTTP headers that are exposed to the client. +- `maxAge`: The maximum time that the browser should cache the preflight + response. diff --git a/site-src/guides/http-method-matching.md b/site-src/guides/http-method-matching.md new file mode 100644 index 0000000000..17391c7ec4 --- /dev/null +++ b/site-src/guides/http-method-matching.md @@ -0,0 +1,101 @@ +# HTTP method matching + +???+ info "Extended Support Feature: HTTPRouteMethodMatching" + This feature is part of extended support. For more information on release channels, refer to our [versioning guide](../concepts/versioning.md). + +The [HTTPRoute resource](../api-types/httproute.md) can be used to match +requests based on the HTTP method. This guide shows how to use this +functionality. + +## Matching requests based on the HTTP method + +The following `HTTPRoute` splits traffic between two backends based on the +HTTP method of the request: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: method-matching + namespace: gateway-conformance-infra +spec: + parentRefs: + - name: same-namespace + rules: + - matches: + - method: POST + backendRefs: + - name: infra-backend-v1 + port: 8080 + - matches: + - method: GET + backendRefs: + - name: infra-backend-v2 + port: 8080 +``` + +- A `POST` request to `/` will be routed to `infra-backend-v1`. +- A `GET` request to `/` will be routed to `infra-backend-v2`. + +## Combining with other match types + +Method matching can be combined with other match types like path and header +matching. The following rules demonstrate this: + +```yaml + # Combinations with core match types. + - matches: + - path: + type: PathPrefix + value: /path1 + method: GET + backendRefs: + - name: infra-backend-v1 + port: 8080 + - matches: + - headers: + - name: version + value: one + method: PUT + backendRefs: + - name: infra-backend-v2 + port: 8080 + - matches: + - path: + type: PathPrefix + value: /path2 + headers: + - name: version + value: two + method: POST + backendRefs: + - name: infra-backend-v3 + port: 8080 +``` + +## ORing matches + +If a rule has multiple `matches`, a request will be routed if it satisfies any +of them. The following rule routes traffic to `infra-backend-v1` if: + +- The request is a `PATCH` to `/path3`. +- OR the request is a `DELETE` to `/path4` with the `version: three` header. + +```yaml + # Match of the form (cond1 AND cond2) OR (cond3 AND cond4 AND cond5) + - matches: + - path: + type: PathPrefix + value: /path3 + method: PATCH + - path: + type: PathPrefix + value: /path4 + headers: + - name: version + value: three + method: DELETE + backendRefs: + - name: infra-backend-v1 + port: 8080 +``` diff --git a/site-src/guides/http-query-param-matching.md b/site-src/guides/http-query-param-matching.md new file mode 100644 index 0000000000..faa3cef6aa --- /dev/null +++ b/site-src/guides/http-query-param-matching.md @@ -0,0 +1,124 @@ +# HTTP query parameter matching + +???+ info "Extended Support Feature: HTTPRouteQueryParamMatching" + This feature is part of extended support. For more information on release channels, refer to our [versioning guide](../concepts/versioning.md). + +The [HTTPRoute resource](../api-types/httproute.md) can be used to match +requests based on query parameters. This guide shows how to use this +functionality. + +## Matching requests based on a single query parameter + +The following `HTTPRoute` splits traffic between two backends based on the +value of the `animal` query parameter: + +```yaml +apiVersion: gateway.networking.k.io/v1 +kind: HTTPRoute +metadata: + name: query-param-matching + namespace: gateway-conformance-infra +spec: + parentRefs: + - name: same-namespace + rules: + - matches: + - queryParams: + - name: animal + value: whale + backendRefs: + - name: infra-backend-v1 + port: 8080 + - matches: + - queryParams: + - name: animal + value: dolphin + backendRefs: + - name: infra-backend-v2 + port: 8080 +``` + +- A request to `/` with the query parameter `animal=whale` will be routed to `infra-backend-v1`. +- A request to `/` with the query parameter `animal=dolphin` will be routed to `infra-backend-v2`. + +## Matching requests based on multiple query parameters + +A rule can also match on multiple query parameters. The following rule routes +traffic to `infra-backend-v3` if the query parameters `animal=dolphin` AND +`color=blue` are present: + +```yaml + - matches: + - queryParams: + - name: animal + value: dolphin + - name: color + value: blue + backendRefs: + - name: infra-backend-v3 + port: 8080 +``` + +## ORing matches + +If a rule has multiple `matches`, a request will be routed if it satisfies any +of them. The following rule routes traffic to `infra-backend-v3` if: + +- The query parameters `animal=dolphin` AND `color=blue` are present. +- OR the query parameter `ANIMAL=Whale` is present. + +```yaml + - matches: + - queryParams: + - name: animal + value: dolphin + - name: color + value: blue + - queryParams: + - name: ANIMAL + value: Whale + backendRefs: + - name: infra-backend-v3 + port: 8080 +``` + +## Combining with other match types + +Query parameter matching can be combined with other match types like path and +header matching. The following rules demonstrate this: + +```yaml + - matches: + - path: + type: PathPrefix + value: /path1 + queryParams: + - name: animal + value: whale + backendRefs: + - name: infra-backend-v1 + port: 8080 + - matches: + - headers: + - name: version + value: one + queryParams: + - name: animal + value: whale + backendRefs: + - name: infra-backend-v2 + port: 8080 + - matches: + - path: + type: PathPrefix + value: /path2 + headers: + - name: version + value: two + queryParams: + - name: animal + value: whale + backendRefs: + - name: infra-backend-v3 + port: 8080 +``` diff --git a/site-src/guides/http-request-mirroring.md b/site-src/guides/http-request-mirroring.md index 61b7e27bb6..53dd39d9dd 100644 --- a/site-src/guides/http-request-mirroring.md +++ b/site-src/guides/http-request-mirroring.md @@ -1,14 +1,11 @@ # HTTP request mirroring -??? example "Extended Support Feature" +???+ info "Extended Support Feature: HTTPRouteRequestMirror" + This feature is part of extended support. For more information on release channels, refer to our [versioning guide](../concepts/versioning.md). - As of v1.0.0, the Request Mirroring feature is an Extended feature, and - requires implementations to support the `HTTPRouteRequestMirror` feature. - -The [HTTPRoute resource](../api-types/httproute.md) allows you to mirror HTTP -requests to another backend using -[filters](../api-types/httproute.md#filters-optional). This guide shows how to use -this feature. +The [HTTPRoute resource](../api-types/httproute.md) can be used to mirror +requests to multiple backends. This is useful for testing new services with +production traffic. Mirrored requests will must only be sent to one single destination endpoint within this backendRef, and responses from this backend MUST be ignored by diff --git a/site-src/guides/http-timeouts.md b/site-src/guides/http-timeouts.md new file mode 100644 index 0000000000..973bf66f3b --- /dev/null +++ b/site-src/guides/http-timeouts.md @@ -0,0 +1,56 @@ +# HTTP timeouts + +???+ info "Extended Support Feature: HTTPRouteRequestTimeout" + This feature is part of extended support. For more information on release channels, refer to our [versioning guide](../concepts/versioning.md). + +The [HTTPRoute resource](../api-types/httproute.md) can be used to configure +timeouts for HTTP requests. This is useful for preventing long-running requests +from consuming resources and for providing a better user experience. + +The `timeouts` field in an `HTTPRouteRule` can be used to specify a request +timeout. + +## Setting a request timeout + +The following `HTTPRoute` sets a request timeout of 500 milliseconds for all +requests with a path prefix of `/request-timeout`: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: request-timeout + namespace: gateway-conformance-infra +spec: + parentRefs: + - name: same-namespace + rules: + - matches: + - path: + type: PathPrefix + value: /request-timeout + backendRefs: + - name: infra-backend-v1 + port: 8080 + timeouts: + request: 500ms +``` + +If a request to this path takes longer than 500 milliseconds, the gateway will +return a timeout error. + +## Disabling the request timeout + +To disable the request timeout, set the `request` field to `"0s"`: + +```yaml + - matches: + - path: + type: PathPrefix + value: /disable-request-timeout + backendRefs: + - name: infra-backend-v1 + port: 8080 + timeouts: + request: "0s" +```