docs: describe the reverse proxy filter

1 files changed, 57 insertions, 19 deletions

diff --git a/share/man/ENVOY.md b/share/man/ENVOY.md
index 882fb7b..64a0a12 100644
--- a/share/man/ENVOY.md
+++ b/share/man/ENVOY.md
@@ -286,6 +286,55 @@ architecture of how these pieces work together.
 
 The proposed architecture ensures that authorization decisions are made consistently at the edge before requests reach the application.
 
+Envoy can be configured to host multiple listeners and each listener can be
+configured to have its own pipeline of middleware to execute in the order that
+the middleware is declared. Sparkle uses a single listener on all interfaces
+listening for TCP traffic on port 10000 to accept all incoming HTTP traffic.
+The last HTTP filter to execute is the `envoy.filter.http.router` filter that
+will reverse proxy the incoming request to Sparkle.
+
+Below is a snippet of configuration required to setup the reverse proxy.
+
+```yaml
+static_resources:
+    - name: listener_0
+      address:
+        socket_address:
+          protocol: TCP
+          address: 0.0.0.0
+          port_value: 10000
+      filter_chains:
+        - filters:
+            - name: envoy.filters.network.http_connection_manager
+              typed_config:
+                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+                http_filters:
+                  - name: envoy.filters.http.router
+                    typed_config:
+                      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+                route_config:
+                  virtual_hosts:
+                    - name: local
+                      domains: ["*"]
+                      routes:
+                        - match:
+                            prefix: "/"
+                          route:
+                            cluster: sparkle
+  clusters:
+    - name: sparkle
+      load_assignment:
+        cluster_name: sparkle
+        endpoints:
+          - lb_endpoints:
+              - endpoint:
+                  address:
+                    socket_address:
+                      address: 127.0.0.1
+                      port_value: 8080
+```
+
+
 ### Authentication Flow
 
 ```mermaid
@@ -317,13 +366,7 @@ does not support the OIDC Discovery endpoint but an Envoy Gateway
 Envoy Gateway is a control plane that is outside the scope of this document.
 
 ```yaml
-static_resources:
-  listeners:
-    - filter_chains:
-        - filters:
-            - name: envoy.filters.network.http_connection_manager
-              typed_config:
-                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+                # ...
                 http_filters:
                   - name: envoy.filters.http.oauth2
                     typed_config:
@@ -348,6 +391,8 @@ static_resources:
                         token_endpoint:
                           uri: "https://gitlab.com/oauth/token"
                         use_refresh_token: true
+                  - name: envoy.filters.http.router
+                  # ...
 ```
 
 ### Authorization Flow
@@ -390,14 +435,7 @@ This filter ensures ensures the integrity and authenticity of the detected JWT
 and will immediately reject tokens that are invalid.
 
 ```yaml
-static_resources:
-  listeners:
-    - filter_chains:
-        - filters:
-            - name: envoy.filters.network.http_connection_manager
-              typed_config:
-                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
-                http_filters:
+                  # ...
                   - name: envoy.filters.http.oauth2
                     # ...
                   - name: envoy.filters.http.jwt_authn
@@ -423,6 +461,8 @@ static_resources:
                             path: /
                           requires:
                             provider_name: gitlab_provider
+                  - name: envoy.filters.http.router
+                  # ...
 ```
 
 The `envoy.filters.http.ext_authz` filter can be used to forward the incoming HTTP request to an external
@@ -443,6 +483,8 @@ authorization decision specifically on the contents of the HTTP request.
                         envoy_grpc:
                           cluster_name: authzd
                       failure_mode_allow: false
+                  - name: envoy.filters.http.router
+                  # ...
 ```
 
 The external authorization service must implement the [`CheckRequest` protobuf](https://github.com/envoyproxy/envoy/blob/04378898516847d1107c5b15c22ac602ff06372c/api/envoy/service/auth/v3/external_auth.proto#L35) service definition.
@@ -506,7 +548,3 @@ func (svc *CheckService) Denied(ctx context.Context) *auth.CheckResponse {
 	}
 }
 ```
-
-## Envoy Configuration
-
-Let's dive into the envoy configuration.