Merge pull request #1162 from rainest/doc/redirect-rewrite

Add HTTP Rewrite and Redirect Filter guide

apis/v1alpha2/httproute_types.go

@@ -187,6 +187,12 @@ type HTTPRouteRule struct {
 	// Specifying a core filter multiple times has unspecified or custom
 	// conformance.
 	//
+	// All filters are expected to be compatible with each other except for the
+	// URLRewrite and RequestRedirect filters, which may not be combined. If an
+	// implementation can not support other combinations of filters, they must clearly
+	// document that limitation. In all cases where incompatible or unsupported
+	// filters are specified, implementations MUST add a warning condition to status.
+	//
 	// Support: Core
 	//
 	// +optional

examples/experimental/http-redirect-rewrite/httproute-redirect-full.yaml

@@ -0,0 +1,25 @@
+#$ Used in:
+#$ - site-src/v1alpha2/api-types/httproute.md
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: HTTPRoute
+metadata:
+  name: http-filter-redirect
+spec:
+  hostnames:
+    - redirect.example
+  rules:
+    - matches:
+      - path:
+          type: PathPrefix
+          value: /cayenne
+      filters:
+      - type: RequestRedirect
+        requestRedirect:
+          path:
+            type: ReplaceFullPath
+            replaceFullPath: /paprika
+          statusCode: 302
+      backendRefs:
+      - name: example-svc
+        weight: 1
+        port: 80

examples/experimental/http-redirect-rewrite/httproute-redirect-https.yaml

@@ -0,0 +1,19 @@
+#$ Used in:
+#$ - site-src/v1alpha2/api-types/httproute.md
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: HTTPRoute
+metadata:
+  name: http-filter-redirect
+spec:
+  hostnames:
+    - redirect.example
+  rules:
+    - filters:
+      - type: RequestRedirect
+        requestRedirect:
+          scheme: https
+          statusCode: 301
+      backendRefs:
+      - name: example-svc
+        weight: 1
+        port: 80

examples/experimental/http-redirect-rewrite/httproute-redirect-prefix.yaml

@@ -0,0 +1,25 @@
+#$ Used in:
+#$ - site-src/v1alpha2/api-types/httproute.md
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: HTTPRoute
+metadata:
+  name: http-filter-redirect
+spec:
+  hostnames:
+    - redirect.example
+  rules:
+    - matches:
+      - path:
+          type: PathPrefix
+          value: /cayenne
+      filters:
+      - type: RequestRedirect
+        requestRedirect:
+          path:
+            type: ReplacePrefixMatch
+            replacePrefixMatch: /paprika
+          statusCode: 302
+      backendRefs:
+      - name: example-svc
+        weight: 1
+        port: 80

examples/experimental/http-redirect-rewrite/httproute-rewrite-path.yaml

@@ -0,0 +1,25 @@
+#$ Used in:
+#$ - site-src/v1alpha2/api-types/httproute.md
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: HTTPRoute
+metadata:
+  name: http-filter-rewrite
+spec:
+  hostnames:
+    - rewrite.example
+  rules:
+    - matches:
+      - path:
+          type: PathPrefix
+          value: /cardamom
+      filters:
+      - type: URLRewrite
+        urlRewrite:
+          hostname: elsewhere.example
+          path:
+            type: ReplaceFullPath
+            replaceFullPath: /fennel
+      backendRefs:
+      - name: example-svc
+        weight: 1
+        port: 80

examples/experimental/http-redirect-rewrite/httproute-rewrite.yaml

@@ -0,0 +1,18 @@
+#$ Used in:
+#$ - site-src/v1alpha2/api-types/httproute.md
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: HTTPRoute
+metadata:
+  name: http-filter-rewrite
+spec:
+  hostnames:
+    - rewrite.example
+  rules:
+    - filters:
+      - type: URLRewrite
+        urlRewrite:
+          hostname: elsewhere.example
+      backendRefs:
+      - name: example-svc
+        weight: 1
+        port: 80

mkdocs.yml

@@ -47,6 +47,7 @@ nav:
       - Getting started: v1alpha2/guides/getting-started.md
       - Simple Gateway: v1alpha2/guides/simple-gateway.md
       - HTTP routing: v1alpha2/guides/http-routing.md
+      - HTTP redirects and rewrites: v1alpha2/guides/http-redirect-rewrite.md
       - HTTP traffic splitting: v1alpha2/guides/traffic-splitting.md
       - Cross-Namespace routing: v1alpha2/guides/multiple-ns.md
       - TLS: v1alpha2/guides/tls.md

site-src/v1alpha2/api-types/httproute.md

@@ -126,6 +126,12 @@ Conformance levels are defined by the filter type:
 
 Specifying a core filter multiple times has unspecified or custom conformance.
 
+All filters are expected to be compatible with each other except for the
+URLRewrite and RequestRedirect filters, which may not be combined. If an
+implementation can not support other combinations of filters, they must clearly
+document that limitation. In all cases where incompatible or unsupported
+filters are specified, implementations MUST add a warning condition to status.
+
 #### BackendRefs (optional)
 
 BackendRefs defines API objects where matching requests should be sent. If

site-src/v1alpha2/guides/getting-started.md

@@ -9,6 +9,7 @@ _THEN_
 
 - [Simple Gateway](/v1alpha2/guides/simple-gateway) (a good one to start out with)
 - [HTTP routing](/v1alpha2/guides/http-routing)
+- [HTTP redirects and rewrites](/v1alpha2/guides/http-redirect-rewrite)
 - [HTTP traffic splitting](/v1alpha2/guides/traffic-splitting)
 - [Routing across Namespaces](/v1alpha2/guides/multiple-ns)
 - [Configuring TLS](/v1alpha2/guides/tls)

site-src/v1alpha2/guides/http-redirect-rewrite.md

@@ -0,0 +1,95 @@
+# HTTP path redirects and rewrites
+
+[HTTPRoute resources](/v1alpha2/api-types/httproute) can issue redirects to
+clients or rewrite paths sent upstream using
+[filters](/v1alpha2/api-types/httproute#filters-optional). This guide shows how
+to use these features.
+
+Note that redirect and rewrite filters are mutually incompatible. Rules cannot
+use both filter types at once.
+
+## Redirects
+
+Redirects return HTTP 3XX responses to a client, instructing it to retrive a
+different resource. [`RequestRedirect` rule
+filters](v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRequestRedirectFilter)
+instruct Gateways to emit a redirect response to requests matching a filtered
+HTTPRoute rule.
+
+Redirect filters can substitute various URL components independently. For
+example, to issue a permanent redirect (301) from HTTP to HTTPS, configure
+`requestRedirect.statusCode=301` and `requestRedirect.scheme="https"`:
+
+```yaml
+{% include 'experimental/http-redirect-rewrite/httproute-redirect-https.yaml' %}
+```
+
+Redirects change configured URL components to match the redirect configuration
+while preserving other components from the original request URL. In this
+example, the request `GET http://redirect.example/cinammon` will result in a
+301 response with a `location: https://redirect.example/cinnamon` header. The
+hostname (`redirect.example`), path (`/cinnamon`), and port (implicit) remain
+unchanged.
+
+### Path redirects
+
+!!! info "Experimental Channel"
+
+    The `Path` field described below is currently only included in the
+    "Experimental" channel of Gateway API. For more information on release
+    channels, refer to the [related documentation](https://gateway-api.sigs.k8s.io/concepts/versioning).
+
+Path redirects use an HTTP Path Modifier to replace either entire paths or path
+prefixes. For example, the HTTPRoute below will issue a 302 redirect to all
+`redirect.example` requests whose path begins with `/cayenne` to `/paprika`:
+
+```yaml
+{% include 'experimental/http-redirect-rewrite/httproute-redirect-full.yaml' %}
+```
+
+Both requests to
+`https://redirect.example/cayenne/pinch` and
+`https://redirect.example/cayenne/teaspoon` will receive a redirect with a
+`location: https://redirect.example/paprika`.
+
+The other path redirect type, `ReplacePrefixMatch`, replaces only the path
+portion matching `matches.path.value`. Changing the filter in the above to:
+
+```yaml
+{% include 'experimental/http-redirect-rewrite/httproute-redirect-prefix.yaml' %}
+```
+
+will result in redirects with `location:
+https://redirect.example/paprika/pinch` and `location:
+https://redirect.example/paprika/teaspoon` response headers.
+
+## Rewrites
+
+!!! info "Experimental Channel"
+
+    The `URLRewrite` filter described below is currently only included in the
+    "Experimental" channel of Gateway API. For more information on release
+    channels, refer to the [related documentation](https://gateway-api.sigs.k8s.io/concepts/versioning).
+
+Rewrites modify components of a client request before proxying it upstream. A
+[`URLRewrite`
+filter](/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPURLRewriteFilter)
+can change the upstream request hostname and/or path. For example, the
+following HTTPRoute will accept a request for
+`https://rewrite.example/cardamom` and send it upstream to `example-svc` with
+`host: elsewhere.example` in request headers instead of `host:
+rewrite.example`.
+
+```yaml
+{% include 'experimental/http-redirect-rewrite/httproute-rewrite.yaml' %}
+```
+
+Path rewrites also make use of HTTP Path Modifiers. The HTTPRoute below
+will take request for `https://rewrite.example/cardamom/smidgen` and proxy a
+request to `https://elsewhere.example/fennel` upstream to `example-svc`.
+Instead using `type: ReplacePrefixMatch` and `replacePrefixMatch: /fennel` will
+request `https://elsewhere.example/fennel/smidgen` upstream.
+
+```yaml
+{% include 'experimental/http-redirect-rewrite/httproute-rewrite.yaml' %}
+```