Transport layer security (TLS)

This example walks through some of the ways that Envoy can be configured to make use of encrypted connections using HTTP over TLS.

It demonstrates a number of commonly used proxying and TLS termination patterns:

  • https -> http

  • https -> https

  • http -> https

  • https passthrough

To better understand the provided examples, and for a description of how TLS is configured with Envoy, please see the securing Envoy quick start guide.

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 authenticate clients where you control both sides of the connection, or relevant protocols are available.

Step 1: Build the sandbox

Change directory to examples/tls in the Envoy repository.

This starts four proxies listening on localhost ports 10000-10003.

It also starts two upstream services, one HTTP and one HTTPS, which echo back received headers in json format.

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

$ pwd
envoy/examples/tls
$ docker compose pull
$ docker compose up --build -d
$ docker compose ps

       Name                            Command                 State          Ports
-----------------------------------------------------------------------------------------------
tls_proxy-https-to-http_1       /docker-entrypoint.sh /usr ... Up      0.0.0.0:10000->10000/tcp
tls_proxy-https-to-https_1      /docker-entrypoint.sh /usr ... Up      0.0.0.0:10001->10000/tcp
tls_proxy-http-to-https_1       /docker-entrypoint.sh /usr ... Up      0.0.0.0:10002->10000/tcp
tls_proxy-https-passthrough_1   /docker-entrypoint.sh /usr ... Up      0.0.0.0:10003->10000/tcp
tls_service-http_1              node ./index.js                Up
tls_service-https_1             node ./index.js                Up

Step 2: Test proxying https -> http

The Envoy proxy listening on https://localhost:10000 terminates HTTPS and proxies to the upstream HTTP service.

The https -> http configuration adds a TLS transport_socket to the listener.

Querying the service at port 10000 you should see an x-forwarded-proto header of https has been added:

$ curl -sk https://localhost:10000  | jq -r '.headers["x-forwarded-proto"]'
https

The upstream service-http handles the request.

$ curl -sk https://localhost:10000  | jq -r '.os.hostname'
service-http

Step 3: Test proxying https -> https

The Envoy proxy listening on https://localhost:10001 terminates HTTPS and proxies to the upstream HTTPS service.

The https -> https configuration adds a TLS transport_socket to both the listener and the cluster.

Querying the service at port 10001 you should see an x-forwarded-proto header of https has been added:

$ curl -sk https://localhost:10001  | jq -r '.headers["x-forwarded-proto"]'
https

The upstream service-https handles the request.

$ curl -sk https://localhost:10001  | jq -r '.os.hostname'
service-https

Step 4: Test proxying http -> https

The Envoy proxy listening on http://localhost:10002 terminates HTTP and proxies to the upstream HTTPS service.

The http -> https configuration adds a TLS transport_socket to the cluster.

Querying the service at port 10002 you should see an x-forwarded-proto header of http has been added:

$ curl -s http://localhost:10002  | jq -r '.headers["x-forwarded-proto"]'
http

The upstream service-https handles the request.

$ curl -s http://localhost:10002  | jq -r '.os.hostname'
service-https

Step 5: Test proxying https passthrough

The Envoy proxy listening on https://localhost:10003 proxies directly to the upstream HTTPS service which does the TLS termination.

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

Querying the service at port 10003 you should see that no x-forwarded-proto header has been added:

$ curl -sk https://localhost:10003  | jq -r '.headers["x-forwarded-proto"]'
null

The upstream service-https handles the request.

$ curl -sk https://localhost:10003  | jq -r '.os.hostname'
service-https

See also

Securing Envoy quick start guide

Outline of key concepts for securing Envoy.

TLS SNI sandbox

Example of using Envoy to serve multiple domains protected by TLS and served from the same IP address.

Double proxy sandbox

An example of securing traffic between proxies with validation and mutual authentication using mTLS with non-HTTP traffic.