Add documentation for deploying envoy as level 2 proxy (#74)

Signed-off-by: Yan Avlasov <[email protected]>
envoyproxy · Dec 10, 2019 · ecf8e03 · ecf8e03
1 parent 6a6ac1c
commit ecf8e03
Show file tree

Hide file tree

Showing 5 changed files with 48 additions and 0 deletions.
diff --git a/docs/root/_static/multilevel_deployment.svg b/docs/root/_static/multilevel_deployment.svg
diff --git a/docs/root/configuration/best_practices/best_practices.rst b/docs/root/configuration/best_practices/best_practices.rst
@@ -5,3 +5,5 @@ Configuration best practices
   :maxdepth: 2
 
   edge
+  level_two
+
diff --git a/docs/root/configuration/best_practices/level_two.rst b/docs/root/configuration/best_practices/level_two.rst
@@ -0,0 +1,37 @@
+.. _best_practices_level2:
+
+Configuring Envoy as a level two proxy
+======================================
+
+Envoy is a production-ready proxy, however, the default settings that are tailored for the
+edge use case may need to be adjusted when using Envoy in a multi-level deployment as a
+"level two" HTTP/2 proxy.
+
+.. image:: /_static/multilevel_deployment.svg
+
+**In summary, if you run level two Envoy version 1.11.1 or greater which terminates 
+HTTP/2, we strongly advise you to change the HTTP/2 configuration of your level 
+two Envoy, by setting its downstream
+:ref:`validation of HTTP/2 messaging option <envoy_api_field_core.Http2ProtocolOptions.stream_error_on_invalid_http_messaging>`
+to true.**
+
+If there is an invalid HTTP/2 request and this option is not set, the Envoy in 
+question will reset the entire connection. This behavior was changed as part of 
+the 1.11.1 security release, to increase the security of Edge Envoys. Unfortunately, 
+because there are no guarantees that edge proxies will enforce HTTP/1 or HTTP/2 
+standards compliance as rigorously as Envoy’s HTTP/2 stack does, this can result 
+in a problem as follows. If one client sends a request that for example passes 
+level one proxy's validation checks, and it is forwarded over an upstream multiplexed 
+HTTP/2 connection (potentially shared with other clients) the strict enforcement on 
+the level two Envoy HTTP/2 will reset all the streams on that connection, causing 
+a service disruption to the clients sharing that L1-L2 connection. If a malicious 
+user has insight into what traffic will bypass level one checks, they could spray
+“bad” traffic across the level one fleet, causing serious disruption to other users’ 
+traffic.
+
+Please note that the
+:ref:`validation of HTTP/2 messaging option <envoy_api_field_core.Http2ProtocolOptions.stream_error_on_invalid_http_messaging>`
+is planned to be deprecated and replaced with mandatory configuration in the HttpConnectionManager, to ensure
+that what is now an easily overlooked option would need to be configured, ideally
+appropriately for the given Envoy deployment. Please refer to the
+https://github.com/envoyproxy/envoy/issues/9285 for more information.
diff --git a/docs/root/faq/configuration/level_two.rst b/docs/root/faq/configuration/level_two.rst
@@ -0,0 +1,7 @@
+.. _faq_level2:
+
+How do I configure Envoy as a level two proxy?
+==============================================
+
+Refer to :ref:`configuring Envoy as a level two proxy <best_practices_level2>`
+for an example of the level 2 proxy configuration.
diff --git a/docs/root/faq/overview.rst b/docs/root/faq/overview.rst
@@ -27,6 +27,7 @@ Configuration
   :maxdepth: 2
 
   configuration/edge
+  configuration/level_two
   configuration/sni
   configuration/zone_aware_routing
   configuration/zipkin_tracing
Original file line number	Diff line number	Diff line change
Expand Up		@@ -5,3 +5,5 @@ Configuration best practices
		:maxdepth: 2

		edge
		level_two