examples: add an example for tls inspector

docs/root/start/sandboxes/index.rst

@@ -63,6 +63,7 @@ The following sandboxes are available:
     postgres
     redis
     skywalking_tracing
+    tls-inspector
     tls-sni
     tls
     udp

docs/root/start/sandboxes/tls-inspector.rst

@@ -0,0 +1,108 @@
+.. _install_sandboxes_tls_inspector:
+
+TLS Inspector Listener Filter
+=============================
+
+.. sidebar:: Requirements
+
+   .. include:: _include/docker-env-setup-link.rst
+
+   :ref:`curl <start_sandboxes_setup_curl>`
+    Used to make ``HTTP`` requests.
+
+   :ref:`jq <start_sandboxes_setup_jq>`
+    Parse ``json`` output from the upstream echo servers.
+
+This example demonstrates how the ``TLS``  inspector can be used to select ``FilterChains`` to
+distribute the traffic between upstream clusters according to the matched ``transport_protocol`` and/or
+``application_protocols``.
+
+It also demonstrates the admin statistics generated by the ``TLS`` inspector listener filter.
+
+Step 1: Build the sandbox
+*************************
+
+Change directory to ``examples/tls-inspector`` in the Envoy repository, and bring up the services.
+
+This starts one proxy listening on ``localhost:10000``, and with an admin interface listening on port 12345.
+
+It also starts three upstream ``HTTP`` services that echo back received headers in ``json`` format.
+
+The first 2 services are ``HTTPS`` services listening on port ``443`` and the other has no ``TLS`` and listens on
+port ``80``.
+
+.. code-block:: console
+
+  $ pwd
+  envoy/examples/tls-inspector
+  $ docker-compose pull
+  $ docker-compose up --build -d
+  $ docker-compose ps
+
+                Name                               Command               State                         Ports
+  ---------------------------------------------------------------------------------------------------------------------------------
+  tls-inspector_service-http_1            docker-entrypoint.sh node  ... Up
+  tls-inspector_service-https-http1.1_1   docker-entrypoint.sh node  ... Up
+  tls-inspector_service-https-http2_1     docker-entrypoint.sh node  ... Up
+  tls-inspector_tls-inspector_1           /docker-entrypoint.sh /usr ... Up      0.0.0.0:10000->10000/tcp, 0.0.0.0:12345->12345/tcp
+
+
+Step 2: Access services
+***********************
+
+Querying the service at port 10000 with a different HTTP version specified over TLS, or
+with HTTP protocol without TLS, the requests will be handled by different upstream services.
+
+Query the proxy with ``HTTP1.1`` and ``TLS``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+   $ curl -sk --http1.1 https://localhost:10000  | jq  '.os.hostname'
+   "service-https-http1.1"
+
+The upstream ``service-https-http1.1`` handles the request.
+
+Query the proxy with ``HTTP2`` and ``TLS``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+   $ curl -sk --http2  https://localhost:10000  | jq  '.os.hostname'
+   "service-https-http2"
+
+The upstream ``service-https-http2`` handles the request.
+
+Query the proxy with no ``TLS``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+   $ curl -sk http://localhost:10000  | jq  '.os.hostname'
+   "service-http"
+
+The upstream ``service-http`` handles the request. Since TLS Inspector listener filter detects the
+transport is plaintext, it will not set transport_protocol to ``TLS``.
+
+Step 3: View the admin statistics
+*********************************
+
+TLS inspector has a statistics tree rooted at ``tls_inspector``, which can be extracted with the
+admin access entrypoint configured.
+
+.. code-block:: console
+
+   $ curl -sk http://localhost:12345/stats |grep tls_inspector
+   tls_inspector.alpn_found: 2
+   tls_inspector.alpn_not_found: 0
+   tls_inspector.client_hello_too_large: 0
+   tls_inspector.connection_closed: 0
+   tls_inspector.read_error: 0
+   tls_inspector.sni_found: 2
+   tls_inspector.sni_not_found: 0
+   tls_inspector.tls_found: 2
+   tls_inspector.tls_not_found: 1
+
+Viewing the admin statistics we can see that ``TLS``, ``SNI`` and ``ALPN`` are all detected since
+we access services twice via ``HTTP`` over ``TLS``. It also shows one ``tls_not_found`` from the
+plaintext query.

examples/tls-inspector/Dockerfile

@@ -0,0 +1,5 @@
+FROM envoyproxy/envoy-dev:latest
+
+COPY ./envoy.yaml /etc/envoy.yaml
+RUN chmod go+r /etc/envoy.yaml
+CMD ["/usr/local/bin/envoy", "-c /etc/envoy.yaml"]

examples/tls-inspector/README.md

@@ -0,0 +1,2 @@
+To learn about this sandbox and for instructions on how to run it please head over
+to the [Envoy docs](https://www.envoyproxy.io/docs/envoy/latest/start/sandboxes/tls-inspector.html).

examples/tls-inspector/docker-compose.yaml

@@ -0,0 +1,28 @@
+version: "3.7"
+services:
+
+  tls-inspector:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "10000:10000"
+      - "12345:12345"
+
+  service-https-http2:
+    image: mendhak/http-https-echo
+    hostname: service-https-http2
+    environment:
+      - HTTP_PORT=0
+
+  service-https-http1.1:
+    image: mendhak/http-https-echo
+    hostname: service-https-http1.1
+    environment:
+      - HTTP_PORT=0
+
+  service-http:
+    image: mendhak/http-https-echo
+    hostname: service-http
+    environment:
+      - HTTPS_PORT=0

examples/tls-inspector/envoy.yaml

@@ -0,0 +1,83 @@
+admin:
+  access_log_path: "/dev/null"
+  address:
+    socket_address:
+      address: 0.0.0.0
+      port_value: 12345
+static_resources:
+  listeners:
+  - address:
+      socket_address:
+        address: 0.0.0.0
+        port_value: 10000
+    listener_filters:
+      - name: "envoy.filters.listener.tls_inspector"
+        typed_config:
+          "@type": type.googleapis.com/envoy.extensions.filters.listener.tls_inspector.v3.TlsInspector
+    filter_chains:
+    - filter_chain_match:
+        transport_protocol: tls
+        application_protocols: [h2]
+      filters:
+      - name: envoy.filters.network.tcp_proxy
+        typed_config:
+          "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
+          cluster: service-https-http2
+          stat_prefix: https_passthrough
+    - filter_chain_match:
+        transport_protocol: tls
+        application_protocols: [http/1.1]
+      filters:
+      - name: envoy.filters.network.tcp_proxy
+        typed_config:
+          "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
+          cluster: service-https-http1.1
+          stat_prefix: https_passthrough
+    - filter_chain_match:
+      filters:
+      - name: envoy.filters.network.tcp_proxy
+        typed_config:
+          "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
+          cluster: service-http
+          stat_prefix: ingress_http
+
+  clusters:
+  - name: service-https-http2
+    connect_timeout: 0.25s
+    type: STRICT_DNS
+    lb_policy: ROUND_ROBIN
+    load_assignment:
+      cluster_name: service-https-http2
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: service-https-http2
+                port_value: 443
+  - name: service-https-http1.1
+    connect_timeout: 0.25s
+    type: STRICT_DNS
+    lb_policy: ROUND_ROBIN
+    load_assignment:
+      cluster_name: service-https-http1.1
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: service-https-http1.1
+                port_value: 443
+  - name: service-http
+    connect_timeout: 0.25s
+    type: STRICT_DNS
+    lb_policy: ROUND_ROBIN
+    load_assignment:
+      cluster_name: service-http
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: service-http
+                port_value: 80

examples/tls-inspector/verify.sh

@@ -0,0 +1,21 @@
+#!/bin/bash -e
+
+export NAME=tls-inspector
+
+# shellcheck source=examples/verify-common.sh
+. "$(dirname "${BASH_SOURCE[0]}")/../verify-common.sh"
+
+run_log "Curl tls inspector: HTTPS -> HTTP/1.1"
+curl -sk --http1.1 https://localhost:10000  | jq  '.os.hostname' | grep service-https-http1.1
+
+run_log "Curl tls inspector: HTTPS -> HTTP/2"
+curl -sk --http2 https://localhost:10000  | jq  '.os.hostname' | grep service-https-http2
+
+run_log "Curl tls inspector: HTTP"
+curl -s http://localhost:10000  | jq  '.os.hostname' | grep service-http
+
+run_log "Check stats of tls inspector"
+curl -s http://localhost:12345/stats | grep "tls_inspector.alpn_found: 2"
+curl -s http://localhost:12345/stats | grep "tls_inspector.sni_found: 2"
+curl -s http://localhost:12345/stats | grep "tls_inspector.tls_found: 2"
+curl -s http://localhost:12345/stats | grep "tls_inspector.tls_not_found: 1"