docs: add example with ws route (envoyproxy#34855)

Signed-off-by: zvlb <[email protected]>
zhxie · Jun 23, 2024 · 6a63ccd · 6a63ccd
1 parent 23048ff
commit 6a63ccd
Show file tree

Hide file tree

Showing 4 changed files with 107 additions and 8 deletions.
diff --git a/examples/websocket/docker-compose.yaml b/examples/websocket/docker-compose.yaml
@@ -19,14 +19,23 @@ services:
     ports:
     - "${PORT_PROXY0:-10000}:10000"
 
+  proxy-ws-route:
+    build:
+      context: .
+      dockerfile: ../shared/envoy/Dockerfile
+      args:
+        ENVOY_CONFIG: ./envoy-ws-route.yaml
+    ports:
+    - "${PORT_PROXY1:-15000}:10000"
+
   proxy-wss-wss:
     build:
       context: .
       dockerfile: ../shared/envoy/Dockerfile
       args:
         ENVOY_CONFIG: ./envoy-wss.yaml
     ports:
-    - "${PORT_PROXY1:-20000}:10000"
+    - "${PORT_PROXY2:-20000}:10000"
 
   proxy-wss-passthrough:
     build:
@@ -35,7 +44,7 @@ services:
       args:
         ENVOY_CONFIG: ./envoy-wss-passthrough.yaml
     ports:
-    - "${PORT_PROXY2:-30000}:10000"
+    - "${PORT_PROXY3:-30000}:10000"
 
   service-ws:
     build:

diff --git a/examples/websocket/envoy-ws-route.yaml b/examples/websocket/envoy-ws-route.yaml
@@ -0,0 +1,49 @@
+static_resources:
+  listeners:
+  - address:
+      socket_address:
+        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
+          stat_prefix: ingress_ws_to_ws
+          route_config:
+            name: local_route
+            virtual_hosts:
+            - name: app-ws
+              domains:
+              - "*"
+              routes:
+              - match:
+                  prefix: "/ws"
+                route:
+                  cluster: service_ws
+                  upgrade_configs:
+                  - upgrade_type: websocket
+              - match:
+                  prefix: "/"
+                direct_response:
+                  status: 200
+                  body:
+                    inline_string: "NotWebSocket\n"
+          http_filters:
+          - name: envoy.filters.http.router
+            typed_config:
+              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+
+  clusters:
+  - name: service_ws
+    type: STRICT_DNS
+    lb_policy: ROUND_ROBIN
+    load_assignment:
+      cluster_name: service_ws
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: service-ws
+                port_value: 80
diff --git a/examples/websocket/example.rst b/examples/websocket/example.rst
@@ -47,7 +47,7 @@ Change directory to ``examples/websocket`` in the Envoy repository.
 Step 2: Build and start the sandbox
 ***********************************
 
-This starts three proxies listening on ``localhost`` ports ``10000-30000``.
+This starts four proxies listening on ``localhost`` ports ``10000``, ``15000``, ``20000``, ``30000``.
 
 It also starts two upstream services, one ``ws`` and one ``wss``.
 
@@ -65,6 +65,7 @@ The socket servers are very trivial implementations, that simply output ``[ws] H
               Name                             Command               State            Ports
   ---------------------------------------------------------------------------------------------------
   websocket_proxy-ws_1                /docker-entrypoint.sh /usr ... Up      0.0.0.0:10000->10000/tcp
+  websocket_proxy-ws-route_1          /docker-entrypoint.sh /usr ... Up      0.0.0.0:15000->10000/tcp
   websocket_proxy-wss_1               /docker-entrypoint.sh /usr ... Up      0.0.0.0:20000->10000/tcp
   websocket_proxy-wss-passthrough_1   /docker-entrypoint.sh /usr ... Up      0.0.0.0:30000->10000/tcp
   websocket_service-ws_1              websocat -E ws-listen:0.0. ... Up
@@ -99,7 +100,43 @@ You can start an interactive session with the socket as follows:
 
 Type ``Ctrl-c`` to exit the socket session.
 
-Step 4: Test proxying ``wss`` -> ``wss``
+Step 4: Test proxying ``ws`` -> ``ws`` on specific route
+********************************************************
+
+The proxy listening on port ``15000`` terminates the WebSocket connection without ``TLS`` on specific route ``/ws`` and then proxies
+to an upstream socket, also without ``TLS``.
+
+In order for Envoy to terminate the WebSocket connection, the
+:ref:`upgrade_configs <envoy_v3_api_msg_config.route.v3.RouteAction.UpgradeConfig>`
+in :ref:`RouteAction <envoy_v3_api_msg_config.route.v3.RouteAction>`
+must be set, as can be seen in the provided :download:`ws -> ws configuration <_include/websocket/envoy-ws-route.yaml>`:
+
+.. literalinclude:: _include/websocket/envoy-ws-route.yaml
+   :language: yaml
+   :lines: 19-25
+   :linenos:
+   :emphasize-lines: 6-7
+   :caption: :download:`envoy-ws-route.yaml <_include/websocket/envoy-ws-route.yaml>`
+
+You can start an interactive session with the socket as follows:
+
+.. code-block:: console
+
+   $ docker run -ti --network=host solsson/websocat ws://localhost:15000/ws
+   HELO
+   [ws] HELO
+   GOODBYE
+   [ws] HELO
+
+   $ curl http://localhost:15000
+   NotWebSocket
+
+   $ curl http://localhost:15000/ws
+   Only WebSocket connections are welcome here
+
+Type ``Ctrl-c`` to exit the socket session.
+
+Step 5: Test proxying ``wss`` -> ``wss``
 ****************************************
 
 The proxy listening on port ``20000`` terminates the WebSocket connection with ``TLS`` and then proxies
@@ -125,7 +162,7 @@ You can start an interactive session with the socket as follows:
 
 Type ``Ctrl-c`` to exit the socket session.
 
-Step 5: Test proxying ``wss`` passthrough
+Step 6: Test proxying ``wss`` passthrough
 *****************************************
 
 The proxy listening on port ``30000`` passes through all ``TCP`` traffic to an upstream ``TLS`` WebSocket.

diff --git a/examples/websocket/verify.sh b/examples/websocket/verify.sh
@@ -8,6 +8,7 @@ export MANUAL=true
 export PORT_PROXY0="${WEBSOCKET_PORT_PROXY0:-12300}"
 export PORT_PROXY1="${WEBSOCKET_PORT_PROXY1:-12301}"
 export PORT_PROXY2="${WEBSOCKET_PORT_PROXY2:-12302}"
+export PORT_PROXY3="${WEBSOCKET_PORT_PROXY3:-12303}"
 
 # shellcheck source=examples/verify-common.sh
 . "$(dirname "${BASH_SOURCE[0]}")/../verify-common.sh"
@@ -21,15 +22,18 @@ mkdir -p certs
 openssl req -batch -new -x509 -nodes -keyout certs/key.pem -out certs/cert.pem
 openssl pkcs12 -export -passout pass: -out certs/output.pkcs12 -inkey certs/key.pem -in certs/cert.pem
 
-UPARGS="proxy-ws proxy-wss-wss proxy-wss-passthrough service-ws service-wss"
+UPARGS="proxy-ws proxy-ws-route proxy-wss-wss proxy-wss-passthrough service-ws service-wss"
 
 bring_up_example
 
 run_log "Interact with web socket ws -> ws"
 "${DOCKER_COMPOSE[@]}" run client-ws "${PORT_PROXY0}" ws ws
 
+run_log "Interact with web socket ws -> ws for specific route"
+"${DOCKER_COMPOSE[@]}" run client-ws "${PORT_PROXY1}/ws" ws ws
+
 run_log "Interact with web socket wss -> wss"
-"${DOCKER_COMPOSE[@]}" run client-ws "${PORT_PROXY1}" wss wss
+"${DOCKER_COMPOSE[@]}" run client-ws "${PORT_PROXY2}" wss wss
 
 run_log "Interact with web socket wss passthrough"
-"${DOCKER_COMPOSE[@]}" run client-ws "${PORT_PROXY2}" wss wss
+"${DOCKER_COMPOSE[@]}" run client-ws "${PORT_PROXY3}" wss wss