From ec93037026ac614dacdcc3df0c69a0eb9be7e331 Mon Sep 17 00:00:00 2001
From: Samantha Gidlow <sagidlow@redhat.com>
Date: Wed, 31 Mar 2021 09:18:54 -0400
Subject: [PATCH] BZ-1783799: Added path based route doc

---
 modules/nw-path-based-routes.adoc          | 44 ++++++++++++++++++++++
 networking/routes/route-configuration.adoc |  2 +
 2 files changed, 46 insertions(+)
 create mode 100644 modules/nw-path-based-routes.adoc

diff --git a/modules/nw-path-based-routes.adoc b/modules/nw-path-based-routes.adoc
new file mode 100644
index 0000000000..5baad76843
--- /dev/null
+++ b/modules/nw-path-based-routes.adoc
@@ -0,0 +1,44 @@
+// Module filename: nw-path-based-routes.adoc
+// Module included in the following assemblies:
+// * networking/routes/route-configuration.adoc
+
+[id="nw-path-based-routes_{context}"]
+= Path-based routes
+
+Path-based routes specify a path component that can be compared against a URL, which requires that the traffic for the route be HTTP based. Thus, multiple routes can be served using the same host name, each with a different path. Routers should match routes based on the most specific path to the least. However, this depends on the router implementation.
+
+The following table shows example routes and their accessibility:
+
+.Route availability
+[cols="3*", options="header"]
+|===
+|Route | When Compared to | Accessible
+.2+|_www.example.com/test_ |_www.example.com/test_|Yes
+|_www.example.com_|No
+.2+|_www.example.com/test_ and _www.example.com_ | _www.example.com/test_|Yes
+|_www.example.com_|Yes
+.2+|_www.example.com_|_www.example.com/text_|Yes (Matched by the host, not the route)
+|_www.example.com_|Yes
+|===
+
+.An unsecured route with a path
+
+[source,yaml]
+----
+apiVersion: v1
+kind: Route
+metadata:
+  name: route-unsecured
+spec:
+  host: www.example.com
+  path: "/test" <1>
+  to:
+    kind: Service
+    name: service-name
+----
+<1> The path is the only added attribute for a path-based route.
+
+[NOTE]
+====
+Path-based routing is not available when using passthrough TLS, as the router does not terminate TLS in that case and cannot read the contents of the request.
+====
diff --git a/networking/routes/route-configuration.adoc b/networking/routes/route-configuration.adoc
index 6023675307..0c7aac089a 100644
--- a/networking/routes/route-configuration.adoc
+++ b/networking/routes/route-configuration.adoc
@@ -20,6 +20,8 @@ include::modules/nw-throughput-troubleshoot.adoc[leveloffset=+1]
 include::modules/nw-using-cookies-keep-route-statefulness.adoc[leveloffset=+1]
 include::modules/nw-annotating-a-route-with-a-cookie-name.adoc[leveloffset=+2]
 
+include::modules/nw-path-based-routes.adoc[leveloffset=+1]
+
 include::modules/nw-route-specific-annotations.adoc[leveloffset=+1]
 
 include::modules/nw-route-admission-policy.adoc[leveloffset=+1]