envoyproxy · mattklein123 · Aug 15, 2016 · Aug 15, 2016
diff --git a/docs/_static/double_proxy.svg b/docs/_static/double_proxy.svg
diff --git a/docs/_static/front_proxy.svg b/docs/_static/front_proxy.svg
diff --git a/docs/_static/service_to_service.svg b/docs/_static/service_to_service.svg
diff --git a/docs/configuration/http_conn_man/access_log.rst b/docs/configuration/http_conn_man/access_log.rst
@@ -97,14 +97,18 @@ entry. The following command operators are supported:
 Default format
 --------------
 
-If custom format is not specified, Envoy uses the following default format::
+If custom format is not specified, Envoy uses the following default format:
+
+.. code-block:: none
 
   [%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%"
   %RESPONSE_CODE% %FAILURE_REASON% %BYTES_RECEIVED% %BYTES_SENT% %DURATION%
   %RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)% "%REQ(X-FORWARDED-FOR)%" "%REQ(USER-AGENT)%"
   "%REQ(X-REQUEST-ID)%" "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%"
 
-Example of the default Envoy access log format::
+Example of the default Envoy access log format:
+
+.. code-block:: none
 
   [2016-04-15T20:17:00.310Z] "POST /api/v1/locations HTTP/2" 204 - 154 0 226 100 "10.0.35.28"
   "nsq2http" "cc21d9b0-cf5c-432b-8c7e-98aeb7988cd2" "locations" "tcp://10.0.2.1:80"

diff --git a/docs/intro/deployment_types.rst → ...tro/deployment_types/deployment_types.rst b/docs/intro/deployment_types.rst → ...tro/deployment_types/deployment_types.rst
@@ -5,17 +5,8 @@ Envoy is usable in a variety of different scenarios, however it's most useful wh
 *mesh* across all hosts in an infrastructure. This section describes three recommended deployment
 types in increasing order of complexity.
 
-Service to service only
------------------------
+.. toctree::
 
-FIXFIX
-
-Service to service plus front proxy
------------------------------------
-
-FIXFIX
-
-Service to service, front proxy, and double proxy
--------------------------------------------------
-
-FIXFIX
+  service_to_service
+  front_proxy
+  double_proxy
diff --git a/docs/intro/deployment_types/double_proxy.rst b/docs/intro/deployment_types/double_proxy.rst
@@ -0,0 +1,22 @@
+Service to service, front proxy, and double proxy
+-------------------------------------------------
+
+.. image:: /_static/double_proxy.svg
+  :width: 70%
+
+The above diagram shows the :ref:`front proxy <deployment_type_front_proxy>` configuration alongside
+another Envoy cluster running as a *double proxy*. The idea behind the double proxy is that it is
+more efficient to terminate SSL and client connections as close as possible to the user (shorter
+round trip times for the SSL handshake, faster TCP CWND expansion, less chance for packet loss,
+etc.). Connections that terminate in the double proxy are then multiplexed onto long lived HTTP/2
+connections running in the main data center.
+
+In the above diagram, the front Envoy proxy running in region 1 authenticates itself with the front
+Envoy proxy running in region 2 via SSL mutual authentication and pinned certificates. This allows
+the front Envoy instances running in region 2 to trust elements of the incoming requests that
+ordinarily would not be trustable (such as the x-forwaded-for HTTP header).
+
+Configuration template
+^^^^^^^^^^^^^^^^^^^^^^
+
+FIXFIX
diff --git a/docs/intro/deployment_types/front_proxy.rst b/docs/intro/deployment_types/front_proxy.rst
@@ -0,0 +1,24 @@
+.. _deployment_type_front_proxy:
+
+Service to service plus front proxy
+-----------------------------------
+
+.. image:: /_static/front_proxy.svg
+
+The above diagram shows the :ref:`service to service <deployment_type_service_to_service>`
+configuration sitting behind an Envoy cluster used as an HTTP L7 edge reverse proxy. The
+reverse proxy provides the following features:
+
+* Terminates SSL.
+* Supports both HTTP/1.1 and HTTP/2.
+* Full HTTP L7 routing support.
+* Talks to the service to service Envoy clusters via the standard :ref:`ingress port
+  <deployment_type_service_to_service_ingress>` and using the discovery service for host
+  lookup. Thus, the front Envoy hosts work identically to any other Envoy host, other than the
+  fact that they do not run collocated with another service. This means that are operated in the
+  same way and emit the same statistics.
+
+Configuration template
+^^^^^^^^^^^^^^^^^^^^^^
+
+FIXFIX
diff --git a/docs/intro/deployment_types/service_to_service.rst b/docs/intro/deployment_types/service_to_service.rst
@@ -0,0 +1,60 @@
+.. _deployment_type_service_to_service:
+
+Service to service only
+-----------------------
+
+.. image:: /_static/service_to_service.svg
+  :width: 60%
+
+The above diagram shows the simplest Envoy deployment which uses Envoy as a communication bus for
+all traffic internal to a service oriented architecture (SOA). In this scenario, Envoy exposes
+several listeners that are used for local origin traffic as well as service to service traffic.
+
+Service to service egress listener
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is the port used by applications to talk to other services in the infrastructure. For example,
+*http://localhost:9001*. HTTP and GRPC requests use the HTTP/1.1 *host* header or the HTTP/2
+*:authority* header to indicate which remote cluster the request is destined for. Envoy handles
+service discovery, load balancing, rate limiting, etc. depending on the details in the
+configuration. Services only need to know about the local Envoy and do not need to concern
+themselves with network topology, whether they are running in development or production, etc.
+
+This listener supports both HTTP/1.1 or HTTP/2 depending on the capabilities of the application.
+
+.. _deployment_type_service_to_service_ingress:
+
+Service to service ingress listener
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is the port used by remote Envoys when they want to talk to the local Envoy. For example,
+*http://localhost:9211*. Incoming requests are routed to the local service on the configured
+port(s). Multiple application ports may be involved depending on application or load balancing
+needs (for example if the service needs both an HTTP port and a GRPC port). The local Envoy
+performs buffering, circuit breaking, etc. as needed.
+
+Our default configurations use HTTP/2 for all Envoy to Envoy communication, regardless of whether
+the application uses HTTP/1.1 or HTTP/2 when egressing out of a local Envoy. HTTP/2 provides
+better performance via long lived connections and explicit reset notifications.
+
+Optional external service egress listeners
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Generally, an explicit egress port is used for each external service that a local service wants
+to talk to. This is done because some external service SDKs do not easily support overriding the
+*host* header to allow for standard HTTP reverse proxy behavior. For example,
+*http://localhost:9250* might be allocated for connections destined for DynamoDB. Instead of using
+*host* routing for some external services and dedicated local port routing for others, we recommend
+being consistent and using local port routing for all external services.
+
+Discovery service integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The recommended service to service configuration uses an external discovery service for all cluster
+lookups. This provides Envoy with the most detailed information possible for use when performing
+load balancing, statistics gathering, etc.
+
+Configuration template
+^^^^^^^^^^^^^^^^^^^^^^
+
+FIXFIX
diff --git a/docs/intro/intro.rst b/docs/intro/intro.rst
@@ -8,7 +8,7 @@ Introduction
 
   what_is_envoy
   arch_overview/arch_overview
-  deployment_types
+  deployment_types/deployment_types
   real_world_deployments
   comparison
   getting_help