.. _install_sandboxes_tls: Transport Layer Security (TLS) ============================== .. sidebar:: Requirements .. include:: _include/docker-env-setup-link.rst :ref:`curl ` Used to make HTTP requests. :ref:`jq ` Parse JSON output from the upstream echo servers. 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 :ref:`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 :ref:`validate ` all certificates wherever possible. You should also :ref:`authenticate clients ` where you control both sides of the connection, or relevant protocols are available. Step 1: Build the sandbox ************************* Change to the ``tls`` directory. 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. .. code-block:: console $ pwd 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 :download:`https -> http configuration <_include/tls/envoy-https-http.yaml>` adds a TLS :ref:`transport_socket ` to the :ref:`listener `. Querying the service at port ``10000`` you should see an ``x-forwarded-proto`` header of ``https`` has been added: .. code-block:: console $ curl -sk https://localhost:10000 | jq -r '.headers["x-forwarded-proto"]' https The upstream ``service-http`` handles the request. .. code-block:: console $ 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 :download:`https -> https configuration <_include/tls/envoy-https-https.yaml>` adds a ``TLS`` :ref:`transport_socket ` to both the :ref:`listener ` and the :ref:`cluster `. Querying the service at port ``10001`` you should see an ``x-forwarded-proto`` header of ``https`` has been added: .. code-block:: console $ curl -sk https://localhost:10001 | jq -r '.headers["x-forwarded-proto"]' https The upstream ``service-https`` handles the request. .. code-block:: console $ 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 :download:`http -> https configuration <_include/tls/envoy-http-https.yaml>` adds a TLS :ref:`transport_socket ` to the :ref:`cluster `. Querying the service at port ``10002`` you should see an ``x-forwarded-proto`` header of ``http`` has been added: .. code-block:: console $ curl -s http://localhost:10002 | jq -r '.headers["x-forwarded-proto"]' http The upstream ``service-https`` handles the request. .. code-block:: console $ 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 :download:`https passthrough configuration <_include/tls/envoy-https-passthrough.yaml>` requires no TLS or HTTP setup, and instead uses a simple :ref:`tcp_proxy `. Querying the service at port ``10003`` you should see that no ``x-forwarded-proto`` header has been added: .. code-block:: console $ curl -sk https://localhost:10003 | jq -r '.headers["x-forwarded-proto"]' null The upstream ``service-https`` handles the request. .. code-block:: console $ curl -sk https://localhost:10003 | jq -r '.os.hostname' service-https .. seealso:: :ref:`Securing Envoy quick start guide ` Outline of key concepts for securing Envoy. :ref:`TLS SNI sandbox ` Example of using Envoy to serve multiple domains protected by TLS and served from the same IP address. :ref:`Double proxy sandbox ` An example of securing traffic between proxies with validation and mutual authentication using mTLS with non-HTTP traffic.