From 7843577725d9f59d68c699b18e12dcc6abcb6801 Mon Sep 17 00:00:00 2001
From: Blake Covarrubias <blake@covarrubi.as>
Date: Tue, 15 Sep 2020 15:37:47 -0700
Subject: [PATCH] Add path-based routing example to Ingress docs (#8672)

Add configuration example for HTTP path-based routing with virtual
services to Ingress gateway configuration entry documentation.

Resolves #8018
---
 .../agent/config-entries/ingress-gateway.mdx  | 248 ++++++++++++++++++
 1 file changed, 248 insertions(+)

diff --git a/website/pages/docs/agent/config-entries/ingress-gateway.mdx b/website/pages/docs/agent/config-entries/ingress-gateway.mdx
index 1c5e96b0c9..9604a57b10 100644
--- a/website/pages/docs/agent/config-entries/ingress-gateway.mdx
+++ b/website/pages/docs/agent/config-entries/ingress-gateway.mdx
@@ -44,6 +44,8 @@ A wildcard specifier cannot be set on a listener of protocol `tcp`.
 
 ## Sample Config Entries
 
+### TCP listener
+
 <Tabs>
 <Tab heading="HCL">
 
@@ -143,6 +145,8 @@ to proxy traffic to the "db" service in the ops namespace:
 </Tab>
 </Tabs>
 
+### Wildcard HTTP listener
+
 <Tabs>
 <Tab heading="HCL">
 
@@ -318,6 +322,250 @@ Also make two services in the frontend namespace available over a custom port wi
 </Tab>
 </Tabs>
 
+### HTTP listener with path-based routing
+
+<Tabs>
+<Tab heading="HCL">
+
+Set up a HTTP listener on an ingress gateway named "us-east-ingress" to proxy
+traffic to a virtual service named "api".
+
+```hcl
+Kind = "ingress-gateway"
+Name = "us-east-ingress"
+
+Listeners = [
+  {
+    Port     = 80
+    Protocol = "http"
+    Services = [
+      {
+        Name = "api"
+      }
+    ]
+  }
+]
+```
+
+</Tab>
+<Tab heading="HCL (Consul Enterprise)">
+
+Set up a HTTP listener on an ingress gateway named "us-east-ingress" in the
+default namespace to proxy traffic to a virtual service named "api".
+
+```hcl
+Kind = "ingress-gateway"
+Name = "us-east-ingress"
+Namespace = "default"
+
+Listeners = [
+  {
+    Port     = 80
+    Protocol = "http"
+    Services = [
+      {
+        Name = "api"
+        Namespace = "frontend"
+      }
+    ]
+  }
+]
+```
+
+</Tab>
+<Tab heading="JSON">
+
+Set up a HTTP listener on an ingress gateway named "us-east-ingress" to proxy
+traffic to a virtual service named "api".
+
+```json
+{
+  "Kind": "ingress-gateway",
+  "Name": "us-east-ingress",
+  "Listeners": [
+    {
+      "Port": 80,
+      "Protocol": "http",
+      "Services": [
+        {
+          "Name": "api",
+        }
+      ]
+    }
+  ]
+}
+```
+
+</Tab>
+<Tab heading="JSON (Consul Enterprise)">
+
+Set up a HTTP listener on an ingress gateway named "us-east-ingress" in the
+default namespace to proxy traffic to a virtual service named "api".
+
+```json
+{
+  "Kind": "ingress-gateway",
+  "Name": "us-east-ingress",
+  "Namespace": "default",
+  "Listeners": [
+    {
+      "Port": 80,
+      "Protocol": "http",
+      "Services": [
+        {
+          "Name": "api",
+          "Namespace": "frontend"
+        }
+      ]
+    }
+  ]
+}
+```
+
+</Tab>
+</Tabs>
+
+The `api` service is not an actual registered service. It exist as a "virtual"
+service for L7 configuration only. A `service-router` is defined for this
+virtual service which uses path-based routing to route requests to different
+backend services.
+
+<Tabs>
+<Tab heading="HCL">
+
+```hcl
+Kind = "service-router"
+Name = "api"
+Routes = [
+  {
+    Match {
+      HTTP {
+        PathPrefix = "/billing"
+      }
+    }
+
+    Destination {
+      Service = "billing-api"
+    }
+  },
+  {
+    Match {
+      HTTP {
+        PathPrefix = "/payments"
+      }
+    }
+
+    Destination {
+      Service = "payments-api"
+    }
+  }
+]
+```
+
+</Tab>
+<Tab heading="HCL (Consul Enterprise)">
+
+```hcl
+Kind = "service-router"
+Name = "api"
+Namespace = "default"
+Routes = [
+  {
+    Match {
+      HTTP {
+        PathPrefix = "/billing"
+      }
+    }
+
+    Destination {
+      Service = "billing-api"
+      Namespace = "frontend"
+    }
+  },
+  {
+    Match {
+      HTTP {
+        PathPrefix = "/payments"
+      }
+    }
+
+    Destination {
+      Service = "payments-api"
+      Namespace = "frontend"
+    }
+  }
+]
+```
+
+</Tab>
+<Tab heading="JSON">
+
+```json
+{
+  "Kind": "service-router",
+  "Name": "api",
+  "Routes": [
+    {
+      "Match": {
+        "HTTP": {
+          "PathPrefix": "/billing"
+        }
+      },
+      "Destination": {
+        "Service": "billing-api"
+      }
+    },
+    {
+      "Match": {
+        "HTTP": {
+          "PathPrefix": "/payments"
+        }
+      },
+      "Destination": {
+        "Service": "payments-api"
+      }
+    }
+  ]
+}
+```
+
+</Tab>
+<Tab heading="JSON (Consul Enterprise)">
+
+```json
+{
+  "Kind": "service-router",
+  "Name": "api",
+  "Namespace": "default",
+  "Routes": [
+    {
+      "Match": {
+        "HTTP": {
+          "PathPrefix": "/billing"
+        }
+      },
+      "Destination": {
+        "Service": "billing-api",
+        "Namespace": "frontend"
+      }
+    },
+    {
+      "Match": {
+        "HTTP": {
+          "PathPrefix": "/payments"
+        }
+      },
+      "Destination": {
+        "Service": "payments-api",
+        "Namespace": "frontend"
+      }
+    }
+  ]
+}
+```
+</Tab>
+</Tabs>
+
 ## Available Fields
 
 - `Kind` - Must be set to `ingress-gateway`