WebSockets

Setup your sandbox environment with Docker and Docker Compose, and clone the Envoy repository with Git.

Generate SSL keys and certificates.

This example walks through some of the ways that Envoy can be configured to proxy WebSockets.

It demonstrates terminating a WebSocket connection with and without TLS, and provides some basic examples of proxying to encrypted and non-encrypted upstream sockets.

Warning

For the sake of simplicity, the examples provided here do not authenticate any client certificates, or validate any of the provided certificates.

When using TLS, you are strongly encouraged to validate all certificates wherever possible.

You should also where you control both sides of the connection, or relevant protocols are available.

This starts three proxies listening on localhost ports 10000-30000.

It also starts two upstream services, one ws and one wss.

The upstream services listen on the internal Docker network on ports 80 and 443 respectively.

The socket servers are very trivial implementations, that simply output [ws] HELO and [wss] HELO in response to any input.

$ docker-compose pull
$ docker-compose up --build -d
$ docker-compose ps
            Name                             Command               State            Ports
---------------------------------------------------------------------------------------------------
websocket_proxy-ws_1                /docker-entrypoint.sh /usr ... Up      0.0.0.0:10000->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
websocket_service-wss_1             websocat wss-listen:0.0.0. ... Up

The proxy listening on port 10000 terminates the WebSocket connection without TLS and then proxies to an upstream socket, also without TLS.

In order for Envoy to terminate the WebSocket connection, the upgrade_configs in must be set, as can be seen in the provided ws -> ws configuration:

You can start an interactive session with the socket as follows:

$ docker run -ti --network=host solsson/websocat ws://localhost:10000
[ws] HELO
GOODBYE
[ws] HELO

Type Ctrl-c to exit the socket session.

The proxy listening on port 20000 terminates the WebSocket connection with TLS and then proxies to an upstream TLS WebSocket.

In addition to the in HttpConnectionManager, the adds a TLS transport_socket to both the and the cluster.

Type Ctrl-c to exit the socket session.

The proxy listening on port 30000 passes through all TCP traffic to an upstream TLS WebSocket.

The requires no TLS or HTTP setup, and instead uses a simple tcp_proxy.

You can start an interactive session with the socket as follows:

$ docker run -ti --network=host solsson/websocat --insecure wss://localhost:30000
HELO
[wss] HELO
GOODBYE
[wss] HELO

Type Ctrl-c to exit the socket session.