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.