Lds docs (#295)

Signed-off-by: Matt Klein <mklein@lyft.com>

api/lds.proto

@@ -11,7 +11,10 @@ import "google/api/annotations.proto";
 import "google/protobuf/struct.proto";
 import "google/protobuf/wrappers.proto";
 
+import "validate/validate.proto";
+
 // [#protodoc-title: Listeners and LDS]
+// Listener :ref:`configuration overview <config_listeners>`
 
 // The Envoy instance initiates an RPC at startup to discover a list of
 // listeners. Updates are delivered via streaming from the LDS server and
@@ -33,55 +36,82 @@ service ListenerDiscoveryService {
 
 message Filter {
   // The name of the filter to instantiate. The name must match a supported
-  // filter.
-  string name = 1;
+  // filter. The built-in filters are:
+  //
+  // [#comment:TODO(mattklein123): Auto generate the following list]
+  // * :ref:`envoy.echo <config_network_filters_echo>`
+  // * :ref:`envoy.http_connection_manager <config_http_conn_man>`
+  // * :ref:`envoy.mongo_proxy <config_network_filters_mongo_proxy>`
+  // * :ref:`envoy.redis_proxy <config_network_filters_redis_proxy>`
+  // * :ref:`envoy.tcp_proxy <config_network_filters_tcp_proxy>`
+  string name = 1 [(validate.rules).string.min_len = 1];
+
   // Filter specific configuration which depends on the filter being
   // instantiated. See the supported filters for further documentation.
   google.protobuf.Struct config = 2;
 
+  // [#not-implemented-hide:]
   message DeprecatedV1 {
     string type = 1;
   }
+
+  // [#not-implemented-hide:]
   DeprecatedV1 deprecated_v1 = 3;
 }
 
 // Specifies the match criteria for selecting a specific filter chain for a
-// listener [V2-API-DIFF].
+// listener.
 message FilterChainMatch {
   // If non-empty, the SNI domains to consider. May contain a wildcard prefix,
   // e.g. ``*.example.com``.
+  //
+  // .. attention::
+  //
+  //   See the :ref:`FAQ entry <faq_how_to_setup_sni>` on how to configure SNI for more
+  //   information.
   repeated string sni_domains = 1;
 
   // If non-empty, an IP address and prefix length to match addresses when the
   // listener is bound to 0.0.0.0/:: or when use_original_dst is specified.
+  // [#not-implemented-hide:]
   repeated CidrRange prefix_ranges = 3;
 
   // If non-empty, an IP address and suffix length to match addresses when the
   // listener is bound to 0.0.0.0/:: or when use_original_dst is specified.
+  // [#not-implemented-hide:]
   string address_suffix = 4;
+
+  // [#not-implemented-hide:]
   google.protobuf.UInt32Value suffix_len = 5;
 
   // The criteria is satisfied if the source IP address of the downstream
   // connection is contained in at least one of the specified subnets. If the
   // parameter is not specified or the list is empty, the source IP address is
   // ignored.
+  // [#not-implemented-hide:]
   repeated CidrRange source_prefix_ranges = 6;
 
   // The criteria is satisfied if the source port of the downstream connection
   // is contained in at least one of the specified ports. If the parameter is
   // not specified, the source port is ignored.
+  // [#not-implemented-hide:]
   repeated google.protobuf.UInt32Value source_ports = 7;
 
   // Optional destination port to consider when use_original_dst is set on the
   // listener in determining a filter chain match.
+  // [#not-implemented-hide:]
   google.protobuf.UInt32Value destination_port = 8;
 }
 
-// Grouping of FilterChainMatch criteria, DownstreamTlsContext, the actual filter chain
-// and related parameters.
+// A filter chain wraps a set of match criteria, an option TLS context, a set of filters, and
+// various other parameters.
 message FilterChain {
+  // The criteria to use when matching a connection to this filter chain.
   FilterChainMatch filter_chain_match = 1;
+
+  // The TLS context for this filter chain.
   DownstreamTlsContext tls_context = 2;
+
   // A list of individual network filters that make up the filter chain for
   // connections established with the listener. Order matters as the filters are
   // processed sequentially as connection events happen.  Note: If the filter
@@ -96,50 +126,56 @@ message FilterChain {
   // connection as the remote address.
   google.protobuf.BoolValue use_proxy_proto = 4;
 
-  // See base.Metadata description.
+  // [#not-implemented-hide:] filter chain metadata.
   Metadata metadata = 5;
 
-  // See base.TransportSocket description.
+  // [#not-implemented-hide:] See base.TransportSocket description.
   TransportSocket transport_socket = 6;
 }
 
 message Listener {
-  // The unique name of the listener. If no name is provided, Envoy will generate a
-  // UUID for internal use. The name is used for dynamic listener update and removal
-  // via the LDS APIs.
+  // The unique name by which this listener is known. If no name is provided,
+  // Envoy will allocate an internal UUID for the listener. If the listener is to be dynamically
+  // updated or removed via :ref:`LDS <config_listeners_lds>` a unique name must be provided.
+  // By default, the maximum length of a listener's name is limited to 60 characters. This limit can be
+  // increased by setting the :option:`--max-obj-name-len` command line argument to the desired value.
   string name = 1;
 
-  // The address that the listener should listen on.
-  Address address = 2;
+  // The address that the listener should listen on. In general, the address must be unique, though
+  // that is governed by the bind rules of the OS. E.g., multiple listeners can listen on port 0 on
+  // Linux as the actual port will be allocated by the OS.
+  Address address = 2 [(validate.rules).message.required = true];
 
-  // A list of filter chains to consider for this listener. The FilterChain with
-  // the most specific FilterChainMatch criteria is used on a connection. The
-  // algorithm works as follows:
+  // A list of filter chains to consider for this listener. The
+  // :ref:`FilterChain <envoy_api_msg_FilterChain>` with the most specific :ref:`FilterChainMatch
+  // <envoy_api_msg_FilterChainMatch>` criteria is used on a connection.
+  //
+  // .. attention::
   //
-  // 1. If SNI information is presented at connection time, only the
-  //    FilterChains matching the SNI are considered. Otherwise, only
-  //    FilterChains with no SNI domains are considered.
-  // 2. Of the FilterChains from step 1, the longest prefix match on the
-  //    bound destination address is used to select the next set of
-  //    FilterChains. This may be one FilterChain or multiple if there is
-  //    a tie.
-  // 3. The longest suffix match on the bound destination address is used to
-  //    select the FilterChain from step 2 that is used.
-  repeated FilterChain filter_chains = 3;
-
-  // If a connection is redirected using iptables, the port on which the proxy
-  // receives it might be different from the original destination port. When
-  // this flag is set to true, the listener uses the original destination
-  // address and port during FilterChain matching. Default is false.
+  //   In the current version, multiple filter chains are supported **only** so that SNI can be
+  //   configured. See the :ref:`FAQ entry <faq_how_to_setup_sni>` on how to configure SNI for more
+  //   information. When multiple filter chains are configured, each filter chain must have an
+  //   **identical** set of :ref:`filters <envoy_api_field_FilterChain.filters>`. If the filters
+  //   differ, the configuration will fail to load. In the future, this limitation will be relaxed such that
+  //   different filters can be used depending on which filter chain matches (based on SNI or
+  //   some other parameter).
+  repeated FilterChain filter_chains = 3 [(validate.rules).repeated.min_items = 1];
+
+  // If a connection is redirected using *iptables*, the port on which the proxy
+  // receives it might be different from the original destination address. When this flag is set to true,
+  // the listener hands off redirected connections to the listener associated with the original
+  // destination address. If there is no listener associated with the original destination address, the
+  // connection is handled by the listener that receives it. Defaults to false.
   google.protobuf.BoolValue use_original_dst = 4;
 
   // Soft limit on size of the listener’s new connection read and write buffers.
   // If unspecified, an implementation defined default is applied (1MiB).
   google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5;
 
-  // See base.Metadata description.
+  // [#not-implemented-hide:] Listener metadata.
   Metadata metadata = 6;
 
+  // [#not-implemented-hide:]
   message DeprecatedV1 {
     // Whether the listener should bind to the port. A listener that doesn’t
     // bind can only receive connections redirected from other listeners that
@@ -151,6 +187,8 @@ message Listener {
     // port specified in the FilterChainMatch destination_port field.
     google.protobuf.BoolValue bind_to_port = 1;
   }
+
+  // [#not-implemented-hide:]
   DeprecatedV1 deprecated_v1 = 7;
 
   enum DrainType {

docs/root/api-v1/api.rst

@@ -5,6 +5,7 @@ v1 API reference
   :glob:
   :maxdepth: 2
 
+  listeners/listeners
   network_filters/network_filters
   route_config/route_config
   http_filters/http_filters

docs/root/api-v1/listeners/lds.rst

@@ -0,0 +1,49 @@
+.. _config_listeners_lds_v1:
+
+Listener discovery service (LDS)
+================================
+
+.. code-block:: json
+
+  {
+    "cluster": "...",
+    "refresh_delay_ms": "..."
+  }
+
+cluster
+  *(required, string)* The name of an upstream :ref:`cluster <config_cluster_manager_cluster>` that
+  hosts the listener discovery service. The cluster must run a REST service that implements the
+  :ref:`LDS HTTP API <config_listeners_lds_v1_api>`. NOTE: This is the *name* of a cluster defined
+  in the :ref:`cluster manager <config_cluster_manager>` configuration, not the full definition of
+  a cluster as in the case of SDS and CDS.
+
+refresh_delay_ms
+  *(optional, integer)* The delay, in milliseconds, between fetches to the LDS API. Envoy will add
+  an additional random jitter to the delay that is between zero and *refresh_delay_ms*
+  milliseconds. Thus the longest possible refresh delay is 2 \* *refresh_delay_ms*. Default value
+  is 30000ms (30 seconds).
+
+.. _config_listeners_lds_v1_api:
+
+REST API
+--------
+
+.. http:get:: /v1/listeners/(string: service_cluster)/(string: service_node)
+
+Asks the discovery service to return all listeners for a particular `service_cluster` and
+`service_node`. `service_cluster` corresponds to the :option:`--service-cluster` CLI option.
+`service_node` corresponds to the :option:`--service-node` CLI option. Responses use the following
+JSON schema:
+
+.. code-block:: json
+
+  {
+    "listeners": []
+  }
+
+listeners
+  *(Required, array)* A list of :ref:`listeners <config_listeners>` that will be
+  dynamically added/modified within the listener manager. The management server is expected to
+  respond with the complete set of listeners that Envoy should configure during each polling cycle.
+  Envoy will reconcile this list with the listeners that are currently loaded and either
+  add/modify/remove listeners as necessary.

docs/root/api-v1/listeners/listeners.rst

@@ -1,7 +1,111 @@
+.. _config_listeners_v1:
+
+Listeners
+=========
+
+.. toctree::
+  :hidden:
+
+  lds
+
+.. code-block:: json
+
+  {
+    "name": "...",
+    "address": "...",
+    "filters": [],
+    "ssl_context": "{...}",
+    "bind_to_port": "...",
+    "use_proxy_proto": "...",
+    "use_original_dst": "...",
+    "per_connection_buffer_limit_bytes": "...",
+    "drain_type": "..."
+  }
+
+.. _config_listeners_name:
+
+name
+  *(optional, string)* The unique name by which this listener is known. If no name is provided,
+  Envoy will allocate an internal UUID for the listener. If the listener is to be dynamically
+  updated or removed via :ref:`LDS <config_listeners_lds>` a unique name must be provided.
+  By default, the maximum length of a listener's name is limited to 60 characters. This limit can be
+  increased by setting the :option:`--max-obj-name-len` command line argument to the desired value.
+
+address
+  *(required, string)* The address that the listener should listen on. Currently only TCP
+  listeners are supported, e.g., "tcp://127.0.0.1:80". Note, "tcp://0.0.0.0:80" is the wild card
+  match for any IPv4 address with port 80.
+
+:ref:`filters <config_listener_filters>`
+  *(required, array)* A list of individual :ref:`network filters <arch_overview_network_filters>`
+  that make up the filter chain for connections established with the listener. Order matters as the
+  filters are processed sequentially as connection events happen.
+
+  **Note:** If the filter list is empty, the connection will close by default.
+
+:ref:`ssl_context <config_listener_ssl_context>`
+  *(optional, object)* The :ref:`TLS <arch_overview_ssl>` context configuration for a TLS listener.
+  If no TLS context block is defined, the listener is a plain text listener.
+
+bind_to_port
+  *(optional, boolean)* Whether the listener should bind to the port. A listener that doesn't bind
+  can only receive connections redirected from other listeners that set use_original_dst parameter to
+  true. Default is true.
+
+use_proxy_proto
+  *(optional, boolean)* Whether the listener should expect a
+  `PROXY protocol V1 <http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt>`_ header on new
+  connections. If this option is enabled, the listener will assume that that remote address of the
+  connection is the one specified in the header. Some load balancers including the AWS ELB support
+  this option. If the option is absent or set to false, Envoy will use the physical peer address
+  of the connection as the remote address.
+
+use_original_dst
+  *(optional, boolean)* If a connection is redirected using *iptables*, the port on which the proxy
+  receives it might be different from the original destination address. When this flag is set to true,
+  the listener hands off redirected connections to the listener associated with the original
+  destination address. If there is no listener associated with the original destination address, the
+  connection is handled by the listener that receives it. Defaults to false.
+
+.. _config_listeners_per_connection_buffer_limit_bytes:
+
+per_connection_buffer_limit_bytes
+  *(optional, integer)* Soft limit on size of the listener's new connection read and write buffers.
+  If unspecified, an implementation defined default is applied (1MiB).
+
+.. _config_listeners_drain_type:
+
+drain_type
+  *(optional, string)* The type of draining that the listener does. Allowed values include *default*
+  and *modify_only*. See the :ref:`draining <arch_overview_draining>` architecture overview for
+  more information.
+
+.. _config_listener_filters:
+
+Filters
+-------
+
+Network filter :ref:`architecture overview <arch_overview_network_filters>`.
+
+.. code-block:: json
+
+  {
+    "name": "...",
+    "config": "{...}"
+  }
+
+name
+  *(required, string)* The name of the filter to instantiate. The name must match a :ref:`supported
+  filter <config_network_filters>`.
+
+config
+  *(required, object)* Filter specific configuration which depends on the filter being instantiated.
+  See the :ref:`supported filters <config_network_filters>` for further documentation.
+
 .. _config_listener_ssl_context:
 
 TLS context
-===========
+-----------
 
 TLS :ref:`architecture overview <arch_overview_ssl>`.
 

docs/root/configuration/cluster_manager/cds.rst

@@ -7,6 +7,9 @@ The cluster discovery service (CDS) is an optional API that Envoy will call to d
 cluster manager members. Envoy will reconcile the API response and add, modify, or remove known
 clusters depending on what is required.
 
+* :ref:`v1 CDS API <config_cluster_manager_cds_v1>`
+* :ref:`v2 CDS API <v2_grpc_streaming_endpoints>`
+
 Statistics
 ----------
 

docs/root/configuration/listeners/filters.rst

@@ -1,21 +0,0 @@
-.. _config_listener_filters:
-
-Filters
-=======
-
-Network filter :ref:`architecture overview <arch_overview_network_filters>`.
-
-.. code-block:: json
-
-  {
-    "name": "...",
-    "config": "{...}"
-  }
-
-name
-  *(required, string)* The name of the filter to instantiate. The name must match a :ref:`supported
-  filter <config_network_filters>`.
-
-config
-  *(required, object)* Filter specific configuration which depends on the filter being instantiated.
-  See the :ref:`supported filters <config_network_filters>` for further documentation.

docs/root/configuration/listeners/lds.rst

@@ -1,7 +1,7 @@
 .. _config_listeners_lds:
 
-Listener discovery service
-==========================
+Listener discovery service (LDS)
+================================
 
 The listener discovery service (LDS) is an optional API that Envoy will call to dynamically fetch
 listeners. Envoy will reconcile the API response and add, modify, or remove known listeners
@@ -23,50 +23,11 @@ The semantics of listener updates are as follows:
   be gracefully closed (if possible) for some period of time before the listener is removed and any
   remaining connections are closed. The drain time is set via the :option:`--drain-time-s` option.
 
-.. code-block:: json
+Configuration
+-------------
 
-  {
-    "cluster": "...",
-    "refresh_delay_ms": "..."
-  }
-
-cluster
-  *(required, string)* The name of an upstream :ref:`cluster <config_cluster_manager_cluster>` that
-  hosts the listener discovery service. The cluster must run a REST service that implements the
-  :ref:`LDS HTTP API <config_listeners_lds_api>`. NOTE: This is the *name* of a cluster defined
-  in the :ref:`cluster manager <config_cluster_manager>` configuration, not the full definition of
-  a cluster as in the case of SDS and CDS.
-
-refresh_delay_ms
-  *(optional, integer)* The delay, in milliseconds, between fetches to the LDS API. Envoy will add
-  an additional random jitter to the delay that is between zero and *refresh_delay_ms*
-  milliseconds. Thus the longest possible refresh delay is 2 \* *refresh_delay_ms*. Default value
-  is 30000ms (30 seconds).
-
-.. _config_listeners_lds_api:
-
-REST API
---------
-
-.. http:get:: /v1/listeners/(string: service_cluster)/(string: service_node)
-
-Asks the discovery service to return all listeners for a particular `service_cluster` and
-`service_node`. `service_cluster` corresponds to the :option:`--service-cluster` CLI option.
-`service_node` corresponds to the :option:`--service-node` CLI option. Responses use the following
-JSON schema:
-
-.. code-block:: json
-
-  {
-    "listeners": []
-  }
-
-listeners
-  *(Required, array)* A list of :ref:`listeners <config_listeners>` that will be
-  dynamically added/modified within the listener manager. The management server is expected to
-  respond with the complete set of listeners that Envoy should configure during each polling cycle.
-  Envoy will reconcile this list with the listeners that are currently loaded and either
-  add/modify/remove listeners as necessary.
+* :ref:`v1 LDS API <config_listeners_lds_v1>`
+* :ref:`v2 LDS API <v2_grpc_streaming_endpoints>`
 
 Statistics
 ----------

docs/root/configuration/listeners/listeners.rst

@@ -3,105 +3,15 @@
 Listeners
 =========
 
+The top level Envoy configuration contains a list of :ref:`listeners <arch_overview_listeners>`.
+Each individual listener configuration has the following format:
+
+* :ref:`v1 API reference <config_listeners_v1>`
+* :ref:`v2 API reference <envoy_api_msg_Listener>`
+
 .. toctree::
   :hidden:
 
-  filters
-  ssl
   stats
   runtime
   lds
-
-The top level Envoy configuration contains a list of :ref:`listeners <arch_overview_listeners>`.
-Each individual listener configuration has the following format:
-
-.. code-block:: json
-
-  {
-    "name": "...",
-    "address": "...",
-    "filters": [],
-    "ssl_context": "{...}",
-    "bind_to_port": "...",
-    "use_proxy_proto": "...",
-    "use_original_dst": "...",
-    "per_connection_buffer_limit_bytes": "...",
-    "drain_type": "..."
-  }
-
-.. _config_listeners_name:
-
-name
-  *(optional, string)* The unique name by which this listener is known. If no name is provided,
-  Envoy will allocate an internal UUID for the listener. If the listener is to be dynamically
-  updated or removed via :ref:`LDS <config_listeners_lds>` a unique name must be provided.
-  By default, the maximum length of a listener's name is limited to 60 characters. This limit can be
-  increased by setting the :option:`--max-obj-name-len` command line argument to the desired value.
-
-address
-  *(required, string)* The address that the listener should listen on. Currently only TCP
-  listeners are supported, e.g., "tcp://127.0.0.1:80". Note, "tcp://0.0.0.0:80" is the wild card
-  match for any IPv4 address with port 80.
-
-:ref:`filters <config_listener_filters>`
-  *(required, array)* A list of individual :ref:`network filters <arch_overview_network_filters>`
-  that make up the filter chain for connections established with the listener. Order matters as the
-  filters are processed sequentially as connection events happen.
-
-  **Note:** If the filter list is empty, the connection will close by default.
-
-:ref:`ssl_context <config_listener_ssl_context>`
-  *(optional, object)* The :ref:`TLS <arch_overview_ssl>` context configuration for a TLS listener.
-  If no TLS context block is defined, the listener is a plain text listener.
-
-bind_to_port
-  *(optional, boolean)* Whether the listener should bind to the port. A listener that doesn't bind
-  can only receive connections redirected from other listeners that set use_original_dst parameter to
-  true. Default is true.
-
-use_proxy_proto
-  *(optional, boolean)* Whether the listener should expect a
-  `PROXY protocol V1 <http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt>`_ header on new
-  connections. If this option is enabled, the listener will assume that that remote address of the
-  connection is the one specified in the header. Some load balancers including the AWS ELB support
-  this option. If the option is absent or set to false, Envoy will use the physical peer address
-  of the connection as the remote address.
-
-use_original_dst
-  *(optional, boolean)* If a connection is redirected using *iptables*, the port on which the proxy
-  receives it might be different from the original destination port. When this flag is set to true,
-  the listener hands off redirected connections to the listener associated with the original
-  destination port. If there is no listener associated with the original destination port, the
-  connection is handled by the listener that receives it. Default is false.
-
-.. _config_listeners_per_connection_buffer_limit_bytes:
-
-per_connection_buffer_limit_bytes
-  *(optional, integer)* Soft limit on size of the listener's new connection read and write buffers.
-  If unspecified, an implementation defined default is applied (1MiB).
-
-.. _config_listeners_drain_type:
-
-drain_type
-  *(optional, string)* The type of draining that the listener does. Allowed values include *default*
-  and *modify_only*. See the :ref:`draining <arch_overview_draining>` architecture overview for
-  more information.
-
-Statistics
-----------
-
-The listener manager has a statistics tree rooted at *listener_manager.* with the following
-statistics. Any ``:`` character in the stats name is replaced with ``_``.
-
-.. csv-table::
-  :header: Name, Type, Description
-  :widths: 1, 1, 2
-
-  listener_added, Counter, Total listeners added (either via static config or LDS)
-  listener_modified, Counter, Total listeners modified (via LDS)
-  listener_removed, Counter, Total listeners removed (via LDS)
-  listener_create_success, Counter, Total listener objects successfully added to workers.
-  listener_create_failure, Counter, Total failed listener object additions to workers.
-  total_listeners_warming, Gauge, Number of currently warming listeners
-  total_listeners_active, Gauge, Number of currently active listeners
-  total_listeners_draining, Gauge, Number of currently draining listeners

docs/root/configuration/listeners/stats.rst

@@ -3,6 +3,9 @@
 Statistics
 ==========
 
+Listener
+--------
+
 Every listener has a statistics tree rooted at *listener.<address>.* with the following statistics:
 
 .. csv-table::
@@ -23,3 +26,22 @@ Every listener has a statistics tree rooted at *listener.<address>.* with the fo
    ssl.fail_verify_san, Counter, Total TLS connections that failed SAN verification
    ssl.fail_verify_cert_hash, Counter, Total TLS connections that failed certificate pinning verification
    ssl.cipher.<cipher>, Counter, Total TLS connections that used <cipher>
+
+Listener manager
+----------------
+
+The listener manager has a statistics tree rooted at *listener_manager.* with the following
+statistics. Any ``:`` character in the stats name is replaced with ``_``.
+
+.. csv-table::
+   :header: Name, Type, Description
+   :widths: 1, 1, 2
+
+   listener_added, Counter, Total listeners added (either via static config or LDS)
+   listener_modified, Counter, Total listeners modified (via LDS)
+   listener_removed, Counter, Total listeners removed (via LDS)
+   listener_create_success, Counter, Total listener objects successfully added to workers.
+   listener_create_failure, Counter, Total failed listener object additions to workers.
+   total_listeners_warming, Gauge, Number of currently warming listeners
+   total_listeners_active, Gauge, Number of currently active listeners
+   total_listeners_draining, Gauge, Number of currently draining listeners

docs/root/configuration/network_filters/echo_filter.rst

@@ -1,3 +1,5 @@
+.. _config_network_filters_echo:
+
 Echo
 ====
 

docs/root/faq/how_fast_is_envoy.rst

@@ -0,0 +1,12 @@
+How fast is Envoy?
+==================
+
+We are frequently asked *how fast is Envoy?* or *how much latency will Envoy add to my requests?*
+The answer is: *it depends*. Performance depends a great deal on which Envoy features are being
+used and the environment in which Envoy is run. In addition, doing accurate performance testing
+is an incredibly difficult task that the project does not currently have resources for.
+
+Although we have done quite a bit of performance tuning of Envoy in the critical path and we
+believe it performs extremely well, because of the previous points we do not currently publish
+any official benchmarks. We encourage users to benchmark Envoy in their own environments with a
+configuration similar to what they plan on using in production.

docs/root/faq/overview.rst

@@ -6,5 +6,7 @@ FAQ
 .. toctree::
   :maxdepth: 1
 
+  how_fast_is_envoy
+  sni
   zone_aware_routing
   zipkin_tracing

docs/root/faq/sni.rst

@@ -0,0 +1,52 @@
+.. _faq_how_to_setup_sni:
+
+How do I setup SNI?
+===================
+
+`SNI <https://en.wikipedia.org/wiki/Server_Name_Indication>`_ is only supported in the :ref:`v2
+configuration/API <config_overview_v2>`.
+
+The current implementation has the requirement that the :ref:`filters
+<envoy_api_field_FilterChain.filters>` in every :ref:`FilterChain <envoy_api_msg_FilterChain>` must
+be identical. In a future release, this requirement will be relaxed so that SNI can be used to
+choose between completely different filter chains. :ref:`Domain name matching
+<envoy_api_field_VirtualHost.domains>` can still be used within the HTTP connection manager to
+choose different routes. This is by far the most common use case for SNI.
+
+The following is a YAML example of the above requirement.
+
+.. code-block:: yaml
+
+  address:
+    socket_address: { address: 127.0.0.1, port_value: 1234 }
+  filter_chains:
+  - filter_chain_match:
+      sni_domains: "example.com"
+    tls_context:
+      common_tls_context:
+        tls_certificates:
+          - certificate_chain: { filename: "example_com_cert.pem" }
+            private_key: { filename: "example_com_key.pem" }
+    filters:
+    - name: envoy.http_connection_manager
+      config:
+        route_config:
+          virtual_hosts:
+          - routes:
+            - match: { prefix: "/" }
+              route: { cluster: service_foo }
+  - filter_chain_match:
+      sni_domains: "www.example.com"
+    tls_context:
+      common_tls_context:
+        tls_certificates:
+          - certificate_chain: { filename: "www_example_com_cert.pem" }
+            private_key: { filename: "www_example_com_key.pem" }
+    filters:
+    - name: envoy.http_connection_manager
+      config:
+        route_config:
+          virtual_hosts:
+          - routes:
+            - match: { prefix: "/" }
+              route: { cluster: service_foo }