Merge pull request #187 from datum-cloud/docs/envoy-gateway-extension-server

Enhancement proposal: Envoy Gateway extension server

Author: scotwells

docs/enhancements/envoy-gateway-extension-server/README.md

@@ -0,0 +1,38 @@
+@startuml c4-container
+!$NEW_C4_STYLE = 1
+!include <C4/C4_Container>
+!include /Users/scotwells/repos/datum-cloud/enhancements/enhancements/datum-theme.puml
+
+LAYOUT_LEFT_RIGHT()
+
+Person_Ext(customer, "Customer", "Creates Gateways and routing\nrules to expose workloads;\nsends traffic to exposed services")
+System_Ext(backend, "Customer's Private\nBackend", "A service running on the\ncustomer's own network;\nnot directly exposed to\nthe internet")
+
+System_Boundary(datum, "Datum Network Services") {
+
+    Boundary(cp, "Control Plane") {
+        Container(nso, "Network Services\nOperator", "Kubernetes Operator", "Watches Gateway and routing\nresources; manages the lifecycle\nof network policy objects")
+
+        Container_Ext(eg, "Envoy Gateway", "Configuration Builder", "Translates Gateway and routing\nresources into proxy configuration;\ncalls the Extension Server\nduring every configuration build")
+
+        Container(ext, "Extension Server", "Configuration Plugin  [NEW]", "Plugs into Envoy Gateway's\nbuild pipeline; injects WAF\nprotection and connector routing\ndirectly during the build")
+
+        Container_Ext(certmgr, "cert-manager", "Certificate Manager", "Automatically issues and renews\nTLS certificates (e.g. via\nLet's Encrypt) for customer domains")
+    }
+
+    Boundary(dp, "Data Plane") {
+        Container(envoy, "Envoy Proxy", "Traffic Handler", "Receives and forwards all\ncustomer HTTP/HTTPS traffic;\nenforces WAF rules and\nhandles connector routing")
+    }
+}
+
+Rel_R(customer, nso, "Creates Gateways\nand routing rules", "Kubernetes API")
+Rel_R(customer, envoy, "Sends HTTP/HTTPS\nrequests", "HTTPS")
+
+Rel_L(nso, eg, "Publishes Gateway\nand policy resources", "Kubernetes API")
+Rel(eg, ext, "Calls extension hook\nduring config build", "gRPC")
+Rel(eg, envoy, "Pushes complete\nproxy configuration", "gRPC")
+Rel_U(certmgr, envoy, "Delivers TLS\ncertificates", "Kubernetes Secret")
+Rel_U(envoy, backend, "Forwards traffic through\nconnector tunnel", "TCP")
+
+SHOW_LEGEND()
+@enduml

docs/enhancements/envoy-gateway-extension-server/c4-container.png

@@ -0,0 +1,50 @@
+@startuml seq-current-flow
+!include /Users/scotwells/repos/datum-cloud/enhancements/enhancements/datum-theme-sequence.puml
+
+title Configuration Flow — Current Approach (EnvoyPatchPolicy)
+
+participant "Customer" as C <<Person>>
+participant "Network Services\nOperator" as NSO
+participant "Envoy Gateway\n(Control Plane)" as EG
+participant "Envoy Proxy\n(Data Plane)" as EP
+
+== Customer changes a Gateway or route ==
+
+C -> NSO : Create or update a\nGateway / HTTPRoute
+
+NSO -> EG : Create WAF EnvoyPatchPolicy\n(one per gateway with WAF)
+NSO -> EG : Create Connector EnvoyPatchPolicy\n(one per gateway with Connector)
+
+note right of NSO
+  At 140 gateways, this produces
+  hundreds of patch objects that
+  must all be re-applied on every
+  single rebuild.
+end note
+
+== Envoy Gateway rebuilds and patches ==
+
+EG -> EG : Rebuild the ENTIRE shared\nconfiguration (all gateways)
+
+loop For every EnvoyPatchPolicy across all gateways
+    EG -> EG : Apply patch to\nconfiguration
+end
+
+note right of EG
+  Rebuild time scales with the
+  total number of gateways —
+  not the number of changed ones.
+  At ~140 gateways: >1 minute.
+end note
+
+EG -> EP : Push patched configuration
+
+note right of EP
+  If a TLS certificate challenge
+  was pending, it may have already
+  expired during the rebuild.
+end note
+
+EP --> C : Serve traffic (with WAF\nand Connector active)
+
+@enduml

docs/enhancements/envoy-gateway-extension-server/c4-container.puml

@@ -0,0 +1,45 @@
+@startuml seq-proposed-flow
+!include /Users/scotwells/repos/datum-cloud/enhancements/enhancements/datum-theme-sequence.puml
+
+title Configuration Flow — Proposed Approach (Extension Server)
+
+participant "Customer" as C <<Person>>
+participant "Network Services\nOperator" as NSO
+participant "Envoy Gateway\n(Control Plane)" as EG
+participant "Extension Server\n[NEW]" as EXT
+participant "Envoy Proxy\n(Data Plane)" as EP
+
+== Customer changes a Gateway or route ==
+
+C -> NSO : Create or update a\nGateway / HTTPRoute
+
+NSO -> EG : Create or update Gateway\nand policy resources\n(no patch objects needed)
+
+== Envoy Gateway builds configuration ==
+
+EG -> EG : Build configuration for\nthe changed gateway
+
+EG -> EXT : Call extension hook —\n"here is the configuration\nin progress"
+
+note right of EXT
+  Called ONCE per build,
+  regardless of how many
+  gateways exist.
+end note
+
+EXT -> EXT : Read WAF and Connector\npolicies for this gateway
+
+EXT -> EG : Return modified configuration —\nWAF filter and Connector\nroutes already injected
+
+EG -> EP : Push complete,\nready-to-use configuration
+
+note right of EG
+  Build completes in seconds,
+  not minutes. TLS certificate
+  challenges can be served
+  before they expire.
+end note
+
+EP --> C : Serve traffic (with WAF\nand Connector active)
+
+@enduml