From 0e0850960600c8e15154b38e4dc4c5bbf0427fff Mon Sep 17 00:00:00 2001
From: Florent Benoit <fbenoit@redhat.com>
Date: Tue, 12 May 2020 14:40:01 +0200
Subject: [PATCH] Implements documentation for
 https://github.com/openshift/origin/issues/20474 and
 https://github.com/openshift/enhancements/pull/287

---
 modules/nw-route-specific-annotations.adoc | 36 ++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/modules/nw-route-specific-annotations.adoc b/modules/nw-route-specific-annotations.adoc
index 47f2fb7d071c..e63ac8e53bd6 100644
--- a/modules/nw-route-specific-annotations.adoc
+++ b/modules/nw-route-specific-annotations.adoc
@@ -30,6 +30,7 @@ and "-". The default is the hashed internal key name for the route. |
 |`haproxy.router.openshift.io/ip_whitelist` | Sets a whitelist for the route. |
 |`haproxy.router.openshift.io/hsts_header` | Sets a Strict-Transport-Security header for the edge terminated or re-encrypt route. |
 |`haproxy.router.openshift.io/log-send-hostname` | Sets the `hostname` field in the Syslog header. Uses the host name of the system. `log-send-hostname` is enabled by default if any Ingress API logging method, such as sidecar or Syslog facility, is enabled for the router. |
+|`haproxy.router.openshift.io/rewrite-target` | Sets the rewrite path of the request on the backend. |
 |===
 
 [NOTE]
@@ -54,3 +55,38 @@ metadata:
 Setting a server-side timeout value for passthrough routes too low can cause
 WebSocket connections to timeout frequently on that route.
 ====
+
+
+.A route specifying a rewrite target
+[source,yaml]
+----
+apiVersion: v1
+kind: Route
+metadata:
+  annotations:
+    haproxy.router.openshift.io/rewrite-target: / <1>
+...
+----
+<1> Sets `/` as rewrite path of the request on the backend.
+
+Setting the `haproxy.router.openshift.io/rewrite-target` annotation on a route specifies that the Ingress Controller should rewrite paths in HTTP requests using this route before forwarding the requests to the backend application.
+The part of the request path that matches the path specified in `spec.path` is replaced with the rewrite target specified in the annotation.
+
+The following table provides examples of the path rewriting behavior for various combinations of `spec.path`, request path, and rewrite target.
+
+.rewrite-target examples:
+[cols="4*", options="header"]
+|===
+|Route.spec.path|Request path|Rewrite target| Forwarded request path
+|/foo|/foo|/|/
+|/foo|/foo/|/|/
+|/foo|/foo/bar|/|/bar
+|/foo|/foo/bar/|/|/bar/
+|/foo|/foo|/bar|/bar
+|/foo|/foo/|/bar|/bar/
+|/foo|/foo/bar|/baz|/baz/bar
+|/foo|/foo/bar/|/baz|/baz/bar/
+|/foo/|/foo|/|N/A (request path does not match route path)
+|/foo/|/foo/|/|/
+|/foo/|/foo/bar|/|/bar
+|===