diff --git a/docs/_static/double_proxy.svg b/docs/_static/double_proxy.svg new file mode 100644 index 000000000000..7c1ac6365b3a --- /dev/null +++ b/docs/_static/double_proxy.svg @@ -0,0 +1,4 @@ + + + + diff --git a/docs/_static/front_proxy.svg b/docs/_static/front_proxy.svg new file mode 100644 index 000000000000..a5cc53a4ed4a --- /dev/null +++ b/docs/_static/front_proxy.svg @@ -0,0 +1,4 @@ + + + + diff --git a/docs/_static/service_to_service.svg b/docs/_static/service_to_service.svg new file mode 100644 index 000000000000..08f4cb398bc3 --- /dev/null +++ b/docs/_static/service_to_service.svg @@ -0,0 +1,4 @@ + + + + diff --git a/docs/configuration/http_conn_man/access_log.rst b/docs/configuration/http_conn_man/access_log.rst index 0fe2e7833c52..b5777379862d 100644 --- 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 b/docs/intro/deployment_types/deployment_types.rst similarity index 52% rename from docs/intro/deployment_types.rst rename to docs/intro/deployment_types/deployment_types.rst index 47e2f9baf6f5..889c9c87ebd6 100644 --- a/docs/intro/deployment_types.rst +++ b/docs/intro/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 new file mode 100644 index 000000000000..28b9e822ae41 --- /dev/null +++ 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 ` 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 new file mode 100644 index 000000000000..f8f88697ac23 --- /dev/null +++ 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 ` +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 + ` 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 new file mode 100644 index 000000000000..eae43bb50a85 --- /dev/null +++ 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 index 595247416af6..b47ca828d98b 100644 --- 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