docs: misc doc debt

README.md

@@ -72,7 +72,8 @@ have prior experience. To get started:
 
 The Envoy team meets every other Tuesday at 9am PT. The public Google calendar is here: https://goo.gl/PkDijT
 
-Meeting minutes are here: https://goo.gl/5Cergb
+* Meeting minutes are [here](https://goo.gl/5Cergb)
+* Recorded videos are posted [here](https://www.youtube.com/channel/UCvqbFHwN-nwalWPjPUKpvTA/videos?view=0&sort=dd&shelf_id=1)
 
 ## Security
 

api/envoy/api/v2/core/protocol.proto

@@ -151,7 +151,7 @@ message Http2ProtocolOptions {
   // the whole HTTP/2 connection is terminated upon receiving invalid HEADERS frame. However,
   // when this option is enabled, only the offending stream is terminated.
   //
-  // See [RFC7540, sec. 8.1](https://tools.ietf.org/html/rfc7540#section-8.1) for details.
+  // See `RFC7540, sec. 8.1 <https://tools.ietf.org/html/rfc7540#section-8.1>`_ for details.
   bool stream_error_on_invalid_http_messaging = 12;
 }
 

api/envoy/api/v2/srds.proto

@@ -15,7 +15,7 @@ import "validate/validate.proto";
 
 // [#protodoc-title: HTTP scoped routing configuration]
 // * Routing :ref:`architecture overview <arch_overview_http_routing>`
-//
+
 // The Scoped Routes Discovery Service (SRDS) API distributes
 // :ref:`ScopedRouteConfiguration<envoy_api_msg.ScopedRouteConfiguration>`
 // resources. Each ScopedRouteConfiguration resource represents a "routing

api/envoy/api/v3alpha/core/protocol.proto

@@ -151,7 +151,7 @@ message Http2ProtocolOptions {
   // the whole HTTP/2 connection is terminated upon receiving invalid HEADERS frame. However,
   // when this option is enabled, only the offending stream is terminated.
   //
-  // See [RFC7540, sec. 8.1](https://tools.ietf.org/html/rfc7540#section-8.1) for details.
+  // See `RFC7540, sec. 8.1 <https://tools.ietf.org/html/rfc7540#section-8.1>`_ for details.
   bool stream_error_on_invalid_http_messaging = 12;
 }
 

api/envoy/api/v3alpha/srds.proto

@@ -15,7 +15,7 @@ import "validate/validate.proto";
 
 // [#protodoc-title: HTTP scoped routing configuration]
 // * Routing :ref:`architecture overview <arch_overview_http_routing>`
-//
+
 // The Scoped Routes Discovery Service (SRDS) API distributes
 // :ref:`ScopedRouteConfiguration<envoy_api_msg.ScopedRouteConfiguration>`
 // resources. Each ScopedRouteConfiguration resource represents a "routing

docs/root/api-v2/config/cluster/cluster.rst

@@ -3,7 +3,7 @@ Cluster
 
 .. toctree::
   :glob:
-  :maxdepth: 1
+  :maxdepth: 2
 
   dynamic_forward_proxy/v2alpha/*
   redis/*

docs/root/api-v2/config/grpc_credential/grpc_credential.rst

@@ -3,6 +3,6 @@ Grpc Credentials
 
 .. toctree::
   :glob:
-  :maxdepth: 1
+  :maxdepth: 2
 
   v2alpha/*

docs/root/api-v2/config/health_checker/health_checker.rst

@@ -3,6 +3,6 @@ Health checkers
 
 .. toctree::
   :glob:
-  :maxdepth: 1
+  :maxdepth: 2
 
   */v2/*

docs/root/api-v2/config/listener/listener.rst

@@ -3,6 +3,6 @@ Listener
 
 .. toctree::
   :glob:
-  :maxdepth: 1
+  :maxdepth: 2
 
   v2/*

docs/root/api-v2/config/rbac/rbac.rst

@@ -3,6 +3,6 @@ RBAC
 
 .. toctree::
   :glob:
-  :maxdepth: 1
+  :maxdepth: 2
 
   v2/*

docs/root/api-v2/config/resource_monitor/resource_monitor.rst

@@ -5,6 +5,6 @@ Resource monitors
 
 .. toctree::
   :glob:
-  :maxdepth: 1
+  :maxdepth: 2
 
   */v2alpha/*

docs/root/api-v2/config/transport_socket/transport_socket.rst

@@ -3,6 +3,6 @@ Transport sockets
 
 .. toctree::
   :glob:
-  :maxdepth: 1
+  :maxdepth: 2
 
   */v2alpha/*

docs/root/configuration/overview/v2_overview.rst

@@ -5,8 +5,8 @@ Overview
 
 The Envoy v2 APIs are defined as `proto3
 <https://developers.google.com/protocol-buffers/docs/proto3>`_ `Protocol Buffers
-<https://developers.google.com/protocol-buffers/>`_ in the `data plane API
-repository <https://github.com/envoyproxy/data-plane-api/tree/master/envoy/api>`_. They support
+<https://developers.google.com/protocol-buffers/>`_ in the :repo:`api tree <api/>`. They
+support:
 
 * Streaming delivery of :ref:`xDS <xds_protocol>` API updates via gRPC. This reduces
   resource requirements and can lower the update latency.
@@ -334,7 +334,7 @@ The management server could respond to EDS requests with:
 
 .. _config_overview_v2_management_server:
 
-Management server
+xDS API endpoints
 -----------------
 
 A v2 xDS management server will implement the below endpoints as required for
@@ -421,9 +421,70 @@ for the service definition. This is used by Envoy as a client when
             cluster_name: some_xds_cluster
 
 is set in the :ref:`rds
-<envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.rds>` field of the :ref:`HttpConnectionManager
+<envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.rds>` field
+of the :ref:`HttpConnectionManager
+<envoy_api_msg_config.filter.network.http_connection_manager.v2.HttpConnectionManager>` config.
+
+.. http:post:: /envoy.api.v2.ScopedRoutesDiscoveryService/StreamScopedRoutes
+
+See :repo:`srds.proto
+<api/envoy/api/v2/srds.proto>`
+for the service definition. This is used by Envoy as a client when
+
+.. code-block:: yaml
+
+    name: some_scoped_route_name
+    scoped_rds:
+      config_source:
+        api_config_source:
+          api_type: GRPC
+          grpc_services:
+            envoy_grpc:
+              cluster_name: some_xds_cluster
+
+is set in the :ref:`scoped_routes
+<envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.scoped_routes>`
+field of the :ref:`HttpConnectionManager
 <envoy_api_msg_config.filter.network.http_connection_manager.v2.HttpConnectionManager>` config.
 
+.. http:post:: /envoy.service.discovery.v2.SecretDiscoveryService/StreamSecrets
+
+See :repo:`sds.proto
+<api/envoy/service/discovery/v2/srds.proto>`
+for the service definition. This is used by Envoy as a client when
+
+.. code-block:: yaml
+
+    name: some_secret_name
+    config_source:
+      api_config_source:
+        api_type: GRPC
+        grpc_services:
+          envoy_grpc:
+            cluster_name: some_xds_cluster
+
+is set inside a :ref:`SdsSecretConfig <envoy_api_msg_auth.SdsSecretConfig>` message. This message
+is used in various places such as the :ref:`CommonTlsContext <envoy_api_msg_auth.CommonTlsContext>`.
+
+.. http:post:: /envoy.service.discovery.v2.RuntimeDiscoveryService/StreamRuntime
+
+See :repo:`rtds.proto
+<api/envoy/service/discovery/v2/rtds.proto>`
+for the service definition. This is used by Envoy as a client when
+
+.. code-block:: yaml
+
+    name: some_runtime_layer_name
+    config_source:
+      api_config_source:
+        api_type: GRPC
+        grpc_services:
+          envoy_grpc:
+            cluster_name: some_xds_cluster
+
+is set inside the :ref:`rtds_layer <envoy_api_field_config.bootstrap.v2.RuntimeLayer.rtds_layer>`
+field.
+
 REST endpoints
 ^^^^^^^^^^^^^^
 

docs/root/faq/build/boringssl.rst

@@ -0,0 +1,8 @@
+Why does Envoy use BoringSSL?
+=============================
+
+`BoringSSL <https://boringssl.googlesource.com/boringssl/>`_ is a slimmed down TLS implementation
+maintained by Google. Getting TLS right is very, very hard. Envoy has chosen to align with
+BoringSSL so as to obtain access to the world class experts that Google employs to work on this
+code base. In short: if BoringSSL is good enough for Google's production systems it is good enough
+for Envoy and the project will not offer first class support for any other TLS implementation.

docs/root/faq/configure_flow_control.rst → docs/root/faq/configuration/flow_control.rst

@@ -1,4 +1,4 @@
-How can I configure flow control
+How do I configure flow control?
 ================================
 
 Flow control may cause problems where Envoy is using non-streaming L7 filters, and request or

docs/root/faq/sni.rst → docs/root/faq/configuration/sni.rst

@@ -1,7 +1,7 @@
 .. _faq_how_to_setup_sni:
 
-How do I setup SNI?
-===================
+How do I configure SNI?
+=======================
 
 `SNI <https://en.wikipedia.org/wiki/Server_Name_Indication>`_ is only supported in the :ref:`v2
 configuration/API <config_overview_v2>`.

docs/root/faq/configuration/timeouts.rst

@@ -0,0 +1,96 @@
+.. _faq_configuration_timeouts:
+
+How do I configure timeouts?
+============================
+
+Envoy supports a wide range of timeouts that may need to be configured depending on the deployment.
+This page summarizes the most important timeouts used in various scenarios.
+
+.. attention::
+
+  This is not an exhaustive list of all of the configurable timeouts that Envoy supports. Depending
+  on the deployment additional configuration may be required.
+
+HTTP/gRPC
+---------
+
+Connection timeouts
+^^^^^^^^^^^^^^^^^^^
+
+Connection timeouts apply to the entire HTTP connection and all streams the connection carries.
+
+* The HTTP protocol :ref:`idle timeout <envoy_api_field_core.HttpProtocolOptions.idle_timeout>`
+  is defined in a generic message used by both the HTTP connection manager as well as upstream
+  cluster HTTP connections. The idle timeout is the time at which a downstream or upstream
+  connection will be terminated if there are no active streams. The default idle timeout if not
+  otherwise specified is *1 hour*. To modify the idle timeout for downstream connections use the
+  :ref:`common_http_protocol_options
+  <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.common_http_protocol_options>`
+  field in the HTTP connection manager configuration. To modify the idle timeout for upstream
+  connections use the
+  :ref:`common_http_protocol_options <envoy_api_field_Cluster.common_http_protocol_options>` field
+  in the cluster configuration.
+
+Stream timeouts
+^^^^^^^^^^^^^^^
+
+Stream timeouts apply to individual streams carried by an HTTP connection. Note that a stream is
+an HTTP/2 and HTTP/3 concept, however internally Envoy maps HTTP/1 requests to streams so in this
+context request/stream is interchangeable.
+
+* The HTTP connection manager :ref:`request_timeout
+  <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.request_timeout>`
+  is the amount of time the connection manager will allow for the *entire request stream* to be
+  received by the client.
+
+  .. attention::
+
+    This timeout is not enforced by default as it is not compatible with streaming requests
+    (requests that never end). See the stream idle timeout that follows. However, if using the
+    :ref:`buffer filter <config_http_filters_buffer>`, it is recommended to configure this timeout.
+* The HTTP connection manager :ref:`stream_idle_timeout
+  <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.stream_idle_timeout>`
+  is the amount of time that the connection manager will allow a stream to exist with no upstream
+  or downstream activity. The default stream idle timeout is *5 minutes*. This timeout is strongly
+  recommended for streaming APIs (requests or responses that never end).
+
+Route timeouts
+^^^^^^^^^^^^^^
+
+Envoy supports additional stream timeouts at the route level, as well as overriding some of the
+stream timeouts already introduced above.
+
+* A route :ref:`timeout <envoy_api_field_route.RouteAction.timeout>` is the amount of time that
+  Envoy will wait for the upstream to respond with a complete response. *This timeout does not
+  start until the entire downstream request stream has been received*.
+
+  .. attention::
+
+    This timeout defaults to *15 seconds*, however, it is not compatible with streaming responses
+    (responses that never end), and will need to be disabled. Stream idle timeouts should be used
+    in the case of streaming APIs as described elsewhere on this page.
+* The route :ref:`idle_timeout <envoy_api_field_route.RouteAction.idle_timeout>` allows overriding
+  of the HTTP connection manager :ref:`stream_idle_timeout
+  <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.stream_idle_timeout>`
+  and does the same thing.
+* The route :ref:`per_try_timeout <envoy_api_field_route.RetryPolicy.per_try_timeout>` can be
+  configured when using retries so that individual tries using a shorter timeout than the overall
+  request timeout described above. This type of timeout will not work with streaming APIs (in which
+  retries are typically not possible) but is useful for decreasing the tail latency of non-streaming
+  APIs.
+
+TCP
+---
+
+* The cluster :ref:`connect_timeout <envoy_api_field_Cluster.connect_timeout>` specifies the amount
+  of time Envoy will wait for an upstream TCP connection to be established. This timeout has no
+  default, but is required in the configuration.
+
+  .. attention::
+
+    For TLS connections, the connect timeout includes the TLS handshake.
+* The TCP proxy :ref:`idle_timeout
+  <envoy_api_field_config.filter.network.tcp_proxy.v2.TcpProxy.idle_timeout>`
+  is the amount of time that the TCP proxy will allow a connection to exist with no upstream
+  or downstream activity. This timeout currently has no default value but configuring it is
+  strongly recommended.

docs/root/faq/zipkin_tracing.rst → docs/root/faq/configuration/zipkin_tracing.rst

@@ -1,7 +1,7 @@
 .. _common_configuration_zipkin_tracing:
 
-How do I setup Zipkin tracing?
-==============================
+How do I configure Zipkin tracing?
+==================================
 
 Refer to the :ref:`zipkin sandbox setup <install_sandboxes_zipkin_tracing>`
 for an example of zipkin tracing configuration.

docs/root/faq/zone_aware_routing.rst → docs/root/faq/configuration/zone_aware_routing.rst

@@ -1,7 +1,7 @@
 .. _common_configuration_zone_aware_routing:
 
-How do I setup zone aware routing?
-==================================
+How do I configure zone aware routing?
+======================================
 
 There are several steps required for enabling :ref:`zone aware routing <arch_overview_load_balancing_zone_aware_routing>`
 between source service ("cluster_a") and destination service ("cluster_b").

docs/root/faq/overview.rst

@@ -3,16 +3,42 @@
 FAQ
 ===
 
+Build
+-----
+
+.. toctree::
+  :maxdepth: 2
+
+  build/binaries
+  build/boringssl
+
+Performance
+-----------
+
+.. toctree::
+  :maxdepth: 2
+
+  performance/how_fast_is_envoy
+
+Configuration
+-------------
+
 .. toctree::
-  :maxdepth: 1
-
-  how_fast_is_envoy
-  binaries
-  sni
-  zone_aware_routing
-  zipkin_tracing
-  lb_panic_threshold
-  concurrency_lb
-  disable_circuit_breaking
-  configure_flow_control
-  transient_failures
+  :maxdepth: 2
+
+  configuration/sni
+  configuration/zone_aware_routing
+  configuration/zipkin_tracing
+  configuration/flow_control
+  configuration/timeouts
+
+Load balancing
+--------------
+
+.. toctree::
+  :maxdepth: 2
+
+  load_balancing/lb_panic_threshold
+  load_balancing/concurrency_lb
+  load_balancing/disable_circuit_breaking
+  load_balancing/transient_failures