How to Properly Configure Envoy for WebSocket Proxying and Avoid Common Pitfalls

Introduction

After checking the backend services and network stability, the root cause turned out to be a misconfiguration of the Envoy proxy. If you are using Envoy to proxy WebSocket services, this article helps you avoid the pitfalls that most people encounter.

Environment Description

The backend provides three services at 172.139.20.3:8090, 172.139.20.92:8090, and 172.139.20.170:8090. The /websocket path uses the WebSocket protocol, while all other paths use HTTP.

Tip: Test the backend host 172.139.20.92:8090/websocket service.

WebSocket Proxy Configuration

Use the following Envoy configuration to enable WebSocket upgrades:

static_resources:
  listeners:
  - name: listener_0
    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_http
          http_filters:
          - name: envoy.filters.http.router
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
          upgrade_configs:
          - upgrade_type: websocket
          route_config:
            name: local_route
            virtual_hosts:
            - name: local_service
              domains: ["*"]
              routes:
              - match:
                  prefix: "/websocket"
                route:
                  cluster: simple_cluster
              - match:
                  prefix: "/"
                route:
                  cluster: simple_cluster
  clusters:
  - name: simple_cluster
    lb_policy: ROUND_ROBIN
    type: STATIC
    load_assignment:
      cluster_name: simple_cluster
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address: { address: 172.139.20.170, port_value: 8090 }
        - endpoint:
            address:
              socket_address: { address: 172.139.20.3, port_value: 8090 }
        - endpoint:
            address:
              socket_address: { address: 172.139.20.92, port_value: 8090 }

Testing verification:

Separate Route WebSocket Proxy

If you need a dedicated route for WebSocket, apply the following configuration:

static_resources:
  listeners:
  - name: listener_0
    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_http
          http_filters:
          - name: envoy.filters.http.router
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
          upgrade_configs:
          - upgrade_type: websocket
          route_config:
            name: local_route
            virtual_hosts:
            - name: local_service
              domains: ["*"]
              routes:
              - match:
                  prefix: "/websocket"
                route:
                  cluster: simple_cluster
              - match:
                  prefix: "/"
                route:
                  cluster: simple_cluster
  clusters:
  - name: simple_cluster
    lb_policy: ROUND_ROBIN
    type: STATIC
    load_assignment:
      cluster_name: simple_cluster
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address: { address: 172.139.20.170, port_value: 8090 }
        - endpoint:
            address:
              socket_address: { address: 172.139.20.3, port_value: 8090 }
        - endpoint:
            address:
              socket_address: { address: 172.139.20.92, port_value: 8090 }

Testing verification:

Conclusion

WebSocket is not a "special traffic" type but a protocol that must be understood. Envoy, as a modern cloud‑native proxy, natively supports WebSocket, but you need the correct configuration to "wake" its capability. As operations engineers, we must ensure both services and protocols are reachable.