From e5dc27c4c6d92e96873fd5a37c8f03fe3e811f89 Mon Sep 17 00:00:00 2001 From: Matt Klein Date: Mon, 14 Oct 2019 09:58:43 -0700 Subject: [PATCH 1/2] docs: misc doc debt Fixes https://github.com/envoyproxy/envoy/issues/8190 Fixes https://github.com/envoyproxy/envoy/issues/7420 Fixes https://github.com/envoyproxy/envoy/issues/7331 Fixes https://github.com/envoyproxy/envoy/issues/7312 Fixes https://github.com/envoyproxy/envoy/issues/7284 Signed-off-by: Matt Klein --- README.md | 3 +- api/envoy/api/v2/core/protocol.proto | 2 +- api/envoy/api/v2/srds.proto | 2 +- api/envoy/api/v3alpha/core/protocol.proto | 2 +- api/envoy/api/v3alpha/srds.proto | 2 +- docs/root/api-v2/config/cluster/cluster.rst | 2 +- .../grpc_credential/grpc_credential.rst | 2 +- .../config/health_checker/health_checker.rst | 2 +- docs/root/api-v2/config/listener/listener.rst | 2 +- docs/root/api-v2/config/rbac/rbac.rst | 2 +- .../resource_monitor/resource_monitor.rst | 2 +- .../transport_socket/transport_socket.rst | 2 +- .../configuration/overview/v2_overview.rst | 69 +++++++++++++++- docs/root/faq/{ => build}/binaries.rst | 0 docs/root/faq/build/boringssl.rst | 8 ++ .../flow_control.rst} | 2 +- docs/root/faq/{ => configuration}/sni.rst | 4 +- docs/root/faq/configuration/timeouts.rst | 81 +++++++++++++++++++ .../{ => configuration}/zipkin_tracing.rst | 4 +- .../zone_aware_routing.rst | 4 +- .../{ => load_balancing}/concurrency_lb.rst | 0 .../disable_circuit_breaking.rst | 0 .../lb_panic_threshold.rst | 0 .../transient_failures.rst | 0 docs/root/faq/overview.rst | 50 +++++++++--- .../{ => performance}/how_fast_is_envoy.rst | 0 docs/root/install/building.rst | 2 +- .../intro/arch_overview/http/http_routing.rst | 2 +- .../arch_overview/listeners/listeners.rst | 21 ++--- .../operations/dynamic_configuration.rst | 81 ++++++++++++------- .../root/intro/arch_overview/security/ssl.rst | 14 +++- docs/root/intro/deprecated.rst | 15 ++-- docs/root/start/start.rst | 4 +- 33 files changed, 302 insertions(+), 84 deletions(-) rename docs/root/faq/{ => build}/binaries.rst (100%) create mode 100644 docs/root/faq/build/boringssl.rst rename docs/root/faq/{configure_flow_control.rst => configuration/flow_control.rst} (98%) rename docs/root/faq/{ => configuration}/sni.rst (97%) create mode 100644 docs/root/faq/configuration/timeouts.rst rename docs/root/faq/{ => configuration}/zipkin_tracing.rst (70%) rename docs/root/faq/{ => configuration}/zone_aware_routing.rst (96%) rename docs/root/faq/{ => load_balancing}/concurrency_lb.rst (100%) rename docs/root/faq/{ => load_balancing}/disable_circuit_breaking.rst (100%) rename docs/root/faq/{ => load_balancing}/lb_panic_threshold.rst (100%) rename docs/root/faq/{ => load_balancing}/transient_failures.rst (100%) rename docs/root/faq/{ => performance}/how_fast_is_envoy.rst (100%) diff --git a/README.md b/README.md index a432d99c40cd..ed3f25df923d 100644 --- a/README.md +++ b/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 diff --git a/api/envoy/api/v2/core/protocol.proto b/api/envoy/api/v2/core/protocol.proto index 7f577bd6280f..7bea7d0c8209 100644 --- a/api/envoy/api/v2/core/protocol.proto +++ b/api/envoy/api/v2/core/protocol.proto @@ -152,7 +152,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 `_ for details. bool stream_error_on_invalid_http_messaging = 12; } diff --git a/api/envoy/api/v2/srds.proto b/api/envoy/api/v2/srds.proto index 224ae0707740..5cb12ce4fc09 100644 --- a/api/envoy/api/v2/srds.proto +++ b/api/envoy/api/v2/srds.proto @@ -15,7 +15,7 @@ import "validate/validate.proto"; // [#protodoc-title: HTTP scoped routing configuration] // * Routing :ref:`architecture overview ` -// + // The Scoped Routes Discovery Service (SRDS) API distributes // :ref:`ScopedRouteConfiguration` // resources. Each ScopedRouteConfiguration resource represents a "routing diff --git a/api/envoy/api/v3alpha/core/protocol.proto b/api/envoy/api/v3alpha/core/protocol.proto index 43b5e4d84a1c..dc2591ad8081 100644 --- a/api/envoy/api/v3alpha/core/protocol.proto +++ b/api/envoy/api/v3alpha/core/protocol.proto @@ -152,7 +152,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 `_ for details. bool stream_error_on_invalid_http_messaging = 12; } diff --git a/api/envoy/api/v3alpha/srds.proto b/api/envoy/api/v3alpha/srds.proto index fb971d77845e..f30a40322424 100644 --- a/api/envoy/api/v3alpha/srds.proto +++ b/api/envoy/api/v3alpha/srds.proto @@ -15,7 +15,7 @@ import "validate/validate.proto"; // [#protodoc-title: HTTP scoped routing configuration] // * Routing :ref:`architecture overview ` -// + // The Scoped Routes Discovery Service (SRDS) API distributes // :ref:`ScopedRouteConfiguration` // resources. Each ScopedRouteConfiguration resource represents a "routing diff --git a/docs/root/api-v2/config/cluster/cluster.rst b/docs/root/api-v2/config/cluster/cluster.rst index 0e8dabab3a8a..d76baee4aeb3 100644 --- a/docs/root/api-v2/config/cluster/cluster.rst +++ b/docs/root/api-v2/config/cluster/cluster.rst @@ -3,7 +3,7 @@ Cluster .. toctree:: :glob: - :maxdepth: 1 + :maxdepth: 2 dynamic_forward_proxy/v2alpha/* redis/* diff --git a/docs/root/api-v2/config/grpc_credential/grpc_credential.rst b/docs/root/api-v2/config/grpc_credential/grpc_credential.rst index 4f154fbf04d0..ceb0be145d94 100644 --- a/docs/root/api-v2/config/grpc_credential/grpc_credential.rst +++ b/docs/root/api-v2/config/grpc_credential/grpc_credential.rst @@ -3,6 +3,6 @@ Grpc Credentials .. toctree:: :glob: - :maxdepth: 1 + :maxdepth: 2 v2alpha/* diff --git a/docs/root/api-v2/config/health_checker/health_checker.rst b/docs/root/api-v2/config/health_checker/health_checker.rst index 533492de84a4..3e5d28372505 100644 --- a/docs/root/api-v2/config/health_checker/health_checker.rst +++ b/docs/root/api-v2/config/health_checker/health_checker.rst @@ -3,6 +3,6 @@ Health checkers .. toctree:: :glob: - :maxdepth: 1 + :maxdepth: 2 */v2/* \ No newline at end of file diff --git a/docs/root/api-v2/config/listener/listener.rst b/docs/root/api-v2/config/listener/listener.rst index 85a3b3a13af3..acd6e1ab5385 100644 --- a/docs/root/api-v2/config/listener/listener.rst +++ b/docs/root/api-v2/config/listener/listener.rst @@ -3,6 +3,6 @@ Listener .. toctree:: :glob: - :maxdepth: 1 + :maxdepth: 2 v2/* diff --git a/docs/root/api-v2/config/rbac/rbac.rst b/docs/root/api-v2/config/rbac/rbac.rst index d52784dce18a..fd0810e9cfc6 100644 --- a/docs/root/api-v2/config/rbac/rbac.rst +++ b/docs/root/api-v2/config/rbac/rbac.rst @@ -3,6 +3,6 @@ RBAC .. toctree:: :glob: - :maxdepth: 1 + :maxdepth: 2 v2/* diff --git a/docs/root/api-v2/config/resource_monitor/resource_monitor.rst b/docs/root/api-v2/config/resource_monitor/resource_monitor.rst index 8f37328b3a0a..70bfdf15f020 100644 --- a/docs/root/api-v2/config/resource_monitor/resource_monitor.rst +++ b/docs/root/api-v2/config/resource_monitor/resource_monitor.rst @@ -5,6 +5,6 @@ Resource monitors .. toctree:: :glob: - :maxdepth: 1 + :maxdepth: 2 */v2alpha/* diff --git a/docs/root/api-v2/config/transport_socket/transport_socket.rst b/docs/root/api-v2/config/transport_socket/transport_socket.rst index b1e462c0630a..267a92949810 100644 --- a/docs/root/api-v2/config/transport_socket/transport_socket.rst +++ b/docs/root/api-v2/config/transport_socket/transport_socket.rst @@ -3,6 +3,6 @@ Transport sockets .. toctree:: :glob: - :maxdepth: 1 + :maxdepth: 2 */v2alpha/* diff --git a/docs/root/configuration/overview/v2_overview.rst b/docs/root/configuration/overview/v2_overview.rst index f65a420a5e93..9e2a93805123 100644 --- a/docs/root/configuration/overview/v2_overview.rst +++ b/docs/root/configuration/overview/v2_overview.rst @@ -5,8 +5,8 @@ Overview The Envoy v2 APIs are defined as `proto3 `_ `Protocol Buffers -`_ in the `data plane API -repository `_. They support +`_ in the :repo:`api tree `. They +support: * Streaming delivery of :ref:`xDS ` 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 -` field of the :ref:`HttpConnectionManager +` field +of the :ref:`HttpConnectionManager +` config. + +.. http:post:: /envoy.api.v2.ScopedRoutesDiscoveryService/StreamScopedRoutes + +See :repo:`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 +` +field of the :ref:`HttpConnectionManager ` config. +.. http:post:: /envoy.service.discovery.v2.SecretDiscoveryService/StreamSecrets + +See :repo:`sds.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 ` message. This message +is used in various places such as the :ref:`CommonTlsContext `. + +.. http:post:: /envoy.service.discovery.v2.RuntimeDiscoveryService/StreamRuntime + +See :repo:`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 ` +field. + REST endpoints ^^^^^^^^^^^^^^ diff --git a/docs/root/faq/binaries.rst b/docs/root/faq/build/binaries.rst similarity index 100% rename from docs/root/faq/binaries.rst rename to docs/root/faq/build/binaries.rst diff --git a/docs/root/faq/build/boringssl.rst b/docs/root/faq/build/boringssl.rst new file mode 100644 index 000000000000..dbf087a8ec0b --- /dev/null +++ b/docs/root/faq/build/boringssl.rst @@ -0,0 +1,8 @@ +Why does Envoy use BoringSSL? +============================= + +`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. diff --git a/docs/root/faq/configure_flow_control.rst b/docs/root/faq/configuration/flow_control.rst similarity index 98% rename from docs/root/faq/configure_flow_control.rst rename to docs/root/faq/configuration/flow_control.rst index f1a94ca2e409..0a0793ff56e0 100644 --- a/docs/root/faq/configure_flow_control.rst +++ b/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 diff --git a/docs/root/faq/sni.rst b/docs/root/faq/configuration/sni.rst similarity index 97% rename from docs/root/faq/sni.rst rename to docs/root/faq/configuration/sni.rst index 61ef2619db03..769af5c6c6d9 100644 --- a/docs/root/faq/sni.rst +++ b/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 `_ is only supported in the :ref:`v2 configuration/API `. diff --git a/docs/root/faq/configuration/timeouts.rst b/docs/root/faq/configuration/timeouts.rst new file mode 100644 index 000000000000..d9be10920f12 --- /dev/null +++ b/docs/root/faq/configuration/timeouts.rst @@ -0,0 +1,81 @@ +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 +^^^^^^^^^^^^^^^^^^^ + +* The HTTP protocol :ref:`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 + ` + field in the HTTP connection manager configuration. To modify the idle timeout for upstream + connections use the + :ref:`common_http_protocol_options ` field + in the cluster configuration. +* The HTTP connection manager :ref:`request_timeout + ` + is the amount of time the connection manager will allow for the *entire request* to be received + by the client. + + .. attention:: + + This timeout has no default value 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 + `, it is recommended to configure this timeout. +* The HTTP connection manager :ref:`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 if not otherwise specified is *5 minutes*. + This timeout is strongly recommended for streaming APIs. + +Route timeouts +^^^^^^^^^^^^^^ + +* A route :ref:`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 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 ` allows overriding + of the HTTP connection manager :ref:`stream_idle_timeout + ` + and does the same thing. +* The route :ref:`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 ` 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 + ` + 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. diff --git a/docs/root/faq/zipkin_tracing.rst b/docs/root/faq/configuration/zipkin_tracing.rst similarity index 70% rename from docs/root/faq/zipkin_tracing.rst rename to docs/root/faq/configuration/zipkin_tracing.rst index de06ef5d17a8..ab66ba8820c1 100644 --- a/docs/root/faq/zipkin_tracing.rst +++ b/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 ` for an example of zipkin tracing configuration. diff --git a/docs/root/faq/zone_aware_routing.rst b/docs/root/faq/configuration/zone_aware_routing.rst similarity index 96% rename from docs/root/faq/zone_aware_routing.rst rename to docs/root/faq/configuration/zone_aware_routing.rst index 6fe9f03f4ccc..3fffa973cde7 100644 --- a/docs/root/faq/zone_aware_routing.rst +++ b/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 ` between source service ("cluster_a") and destination service ("cluster_b"). diff --git a/docs/root/faq/concurrency_lb.rst b/docs/root/faq/load_balancing/concurrency_lb.rst similarity index 100% rename from docs/root/faq/concurrency_lb.rst rename to docs/root/faq/load_balancing/concurrency_lb.rst diff --git a/docs/root/faq/disable_circuit_breaking.rst b/docs/root/faq/load_balancing/disable_circuit_breaking.rst similarity index 100% rename from docs/root/faq/disable_circuit_breaking.rst rename to docs/root/faq/load_balancing/disable_circuit_breaking.rst diff --git a/docs/root/faq/lb_panic_threshold.rst b/docs/root/faq/load_balancing/lb_panic_threshold.rst similarity index 100% rename from docs/root/faq/lb_panic_threshold.rst rename to docs/root/faq/load_balancing/lb_panic_threshold.rst diff --git a/docs/root/faq/transient_failures.rst b/docs/root/faq/load_balancing/transient_failures.rst similarity index 100% rename from docs/root/faq/transient_failures.rst rename to docs/root/faq/load_balancing/transient_failures.rst diff --git a/docs/root/faq/overview.rst b/docs/root/faq/overview.rst index 0fe96c0fd675..31aee1721fcb 100644 --- a/docs/root/faq/overview.rst +++ 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 diff --git a/docs/root/faq/how_fast_is_envoy.rst b/docs/root/faq/performance/how_fast_is_envoy.rst similarity index 100% rename from docs/root/faq/how_fast_is_envoy.rst rename to docs/root/faq/performance/how_fast_is_envoy.rst diff --git a/docs/root/install/building.rst b/docs/root/install/building.rst index 56b13ee1f20c..9541bc6316bd 100644 --- a/docs/root/install/building.rst +++ b/docs/root/install/building.rst @@ -83,6 +83,6 @@ is to use Docker. This guide will walk through the process of building your own Envoy binary, and putting the binary in an Ubuntu container. .. toctree:: - :maxdepth: 1 + :maxdepth: 2 sandboxes/local_docker_build diff --git a/docs/root/intro/arch_overview/http/http_routing.rst b/docs/root/intro/arch_overview/http/http_routing.rst index 574efa611ecf..fddf3f964cbd 100644 --- a/docs/root/intro/arch_overview/http/http_routing.rst +++ b/docs/root/intro/arch_overview/http/http_routing.rst @@ -53,7 +53,7 @@ request. The router filter supports the following features: .. _arch_overview_http_routing_route_scope: Route Scope --------------- +----------- Scoped routing enables Envoy to put constraints on search space of domains and route rules. A :ref:`Route Scope` associates a key with a :ref:`route table `. diff --git a/docs/root/intro/arch_overview/listeners/listeners.rst b/docs/root/intro/arch_overview/listeners/listeners.rst index dee42bd45fa6..a6fb8f6ecd82 100644 --- a/docs/root/intro/arch_overview/listeners/listeners.rst +++ b/docs/root/intro/arch_overview/listeners/listeners.rst @@ -5,17 +5,20 @@ Listeners The Envoy configuration supports any number of listeners within a single process. Generally we recommend running a single Envoy per machine regardless of the number of configured listeners. This -allows for easier operation and a single source of statistics. Currently Envoy only supports TCP +allows for easier operation and a single source of statistics. Envoy supports both TCP and UDP listeners. -Each listener is independently configured with some number of network level (L3/L4) :ref:`filters -`. When a new connection is received on a listener, the configured -connection local filter stack is instantiated and begins processing subsequent events. The generic -listener architecture is used to perform the vast majority of different proxy tasks that Envoy is -used for (e.g., :ref:`rate limiting `, :ref:`TLS client authentication -`, :ref:`HTTP connection management `, -MongoDB :ref:`sniffing `, raw :ref:`TCP proxy `, -etc.). +Each listener is independently configured with some number :ref:`filter chains +`, where an individual chain is selected based on its +:ref:`match criteria `. An individual filter chain is +composed of one or more network level (L3/L4) :ref:`filters `. When +a new connection is received on a listener, the appropriate filter chain is selected, and the +configured connection local filter stack is instantiated and begins processing subsequent events. +The generic listener architecture is used to perform the vast majority of different proxy tasks that +Envoy is used for (e.g., :ref:`rate limiting `, :ref:`TLS client +authentication `, :ref:`HTTP connection management +`, MongoDB :ref:`sniffing `, raw :ref:`TCP proxy +`, etc.). Listeners are optionally also configured with some number of :ref:`listener filters `. These filters are processed before the network level filters, diff --git a/docs/root/intro/arch_overview/operations/dynamic_configuration.rst b/docs/root/intro/arch_overview/operations/dynamic_configuration.rst index 99bb323ed7c2..854317b7316e 100644 --- a/docs/root/intro/arch_overview/operations/dynamic_configuration.rst +++ b/docs/root/intro/arch_overview/operations/dynamic_configuration.rst @@ -1,26 +1,27 @@ .. _arch_overview_dynamic_config: -Dynamic configuration -===================== +xDS configuration API overview +============================== Envoy is architected such that different types of configuration management approaches are possible. The approach taken in a deployment will be dependent on the needs of the implementor. Simple deployments are possible with a fully static configuration. More complicated deployments can incrementally add more complex dynamic configuration, the downside being that the implementor must -provide one or more external REST based configuration provider APIs. This document gives an overview -of the options currently available. +provide one or more external gRPC/REST based configuration provider APIs. These APIs are +collectively known as :ref:`"xDS" ` (* discovery service). This document gives an +overview of the options currently available. * Top level configuration :ref:`reference `. * :ref:`Reference configurations `. * Envoy :ref:`v2 API overview `. +* :ref:`xDS API endpoints `. Fully static ------------ In a fully static configuration, the implementor provides a set of :ref:`listeners ` (and :ref:`filter chains `), :ref:`clusters -`, and optionally :ref:`HTTP route configurations -`. Dynamic host discovery is only possible via DNS based +`, etc. Dynamic host discovery is only possible via DNS based :ref:`service discovery `. Configuration reloads must take place via the built in :ref:`hot restart ` mechanism. @@ -29,21 +30,21 @@ graceful hot restarts. .. _arch_overview_dynamic_config_eds: -EDS only ------------- +EDS +--- -The :ref:`Endpoint Discovery Service (EDS) API ` provides a -more advanced mechanism by which Envoy can discover members of an upstream cluster. -Layered on top of a static configuration, EDS allows an Envoy deployment to circumvent the -limitations of DNS (maximum records in a response, etc.) as well as consume more information used in -load balancing and routing (e.g., canary status, zone, etc.). +The :ref:`Endpoint Discovery Service (EDS) API ` provides +a more advanced mechanism by which Envoy can discover members of an upstream cluster. Layered on top +of a static configuration, EDS allows an Envoy deployment to circumvent the limitations of DNS +(maximum records in a response, etc.) as well as consume more information used in load balancing and +routing (e.g., canary status, zone, etc.). .. _arch_overview_dynamic_config_cds: -EDS and CDS ---------------- +CDS +--- -The :ref:`cluster discovery service (CDS) API ` layers on a mechanism by +The :ref:`Cluster Discovery Service (CDS) API ` layers on a mechanism by which Envoy can discover upstream clusters used during routing. Envoy will gracefully add, update, and remove clusters as specified by the API. This API allows implementors to build a topology in which Envoy does not need to be aware of all upstream clusters at initial configuration time. @@ -59,44 +60,66 @@ existing hosts in the cluster are unaffected. .. _arch_overview_dynamic_config_rds: -EDS, CDS, and RDS ---------------------- +RDS +--- -The :ref:`route discovery service (RDS) API ` layers on a mechanism by +The :ref:`Route Discovery Service (RDS) API ` layers on a mechanism by which Envoy can discover the entire route configuration for an HTTP connection manager filter at runtime. The route configuration will be gracefully swapped in without affecting existing requests. This API, when used alongside EDS and CDS, allows implementors to build a complex routing topology (:ref:`traffic shifting `, blue/green deployment, etc). +SRDS +---- + +The :ref:`Scoped Route Discovery Service (SRDS) API ` allows +a route table to be broken up into multiple pieces. This API is typically used in deployments of +HTTP routing with massive route tables in which simple linear searches are not feasible. + .. _arch_overview_dynamic_config_lds: -EDS, CDS, RDS, and LDS --------------------------- +LDS +--- -The :ref:`listener discovery service (LDS) ` layers on a mechanism by which +The :ref:`Listener Discovery Service (LDS) API ` layers on a mechanism by which Envoy can discover entire listeners at runtime. This includes all filter stacks, up to and including HTTP filters with embedded references to :ref:`RDS `. Adding LDS into the mix allows almost every aspect of Envoy to be dynamically configured. Hot restart should only be required for very rare configuration changes (admin, tracing driver, etc.), certificate rotation, or binary updates. -EDS, CDS, RDS, LDS, and SDS ------------------------------ +SDS +--- -The :ref:`secret discovery service (SDS) ` layers on a mechanism +The :ref:`Secret Discovery Service (SDS) API ` layers on a mechanism by which Envoy can discover cryptographic secrets (certificate plus private key, TLS session ticket keys) for its listeners, as well as configuration of peer certificate validation logic (trusted root certs, revocations, etc). +RTDS +---- + +The :ref:`RunTime Discovery Service (RTDS) API ` allows +:ref:`runtime ` layers to be fetched via an xDS API. This may be favorable to, +or augmented by, file system layers. + Aggregated xDS ("ADS") ------------------------------ +---------------------- -EDS, CDS, etc. are each separate services, with different REST/gRPC service names, e.g. StreamListeners, StreamSecrets. For users looking to enforce the order in which resources of different types reach Envoy, there is aggregated xDS, a single gRPC service that carries all resource types in a single gRPC stream. (ADS is only supported by gRPC). :ref:`More details about ADS `. +EDS, CDS, etc. are each separate services, with different REST/gRPC service names, e.g. +StreamListeners, StreamSecrets. For users looking to enforce the order in which resources of +different types reach Envoy, there is aggregated xDS, a single gRPC service that carries all +resource types in a single gRPC stream. (ADS is only supported by gRPC). +:ref:`More details about ADS `. .. _arch_overview_dynamic_config_delta: Delta gRPC xDS ------------------------------ +-------------- -Standard xDS is "state-of-the-world": every CDS update must contain every cluster, with the absence of a cluster from an update implying that the cluster is gone. As of 1.12.0, Envoy supports a "delta" variant of xDS (including ADS), where updates only contain resources added/changed/removed. Delta xDS is a new protocol, with request/response protos different from SotW; existing control plane servers will need support added. :ref:`More details about delta `. +Standard xDS is "state-of-the-world": every update must contain every resource, with the absence of +a resource from an update implying that the resource is gone. Envoy supports a "delta" variant of +xDS (including ADS), where updates only contain resources added/changed/removed. Delta xDS is a +new protocol, with request/response APIs different from SotW. +:ref:`More details about delta `. diff --git a/docs/root/intro/arch_overview/security/ssl.rst b/docs/root/intro/arch_overview/security/ssl.rst index a44a8f531872..bd706818b94b 100644 --- a/docs/root/intro/arch_overview/security/ssl.rst +++ b/docs/root/intro/arch_overview/security/ssl.rst @@ -105,12 +105,15 @@ Example configuration certificate_chain: { "filename": "/cert.crt" } private_key: { "filename": "/cert.key" } validation_context: + verify_subject_alt_name: [ foo ] trusted_ca: filename: /etc/ssl/certs/ca-certificates.crt */etc/ssl/certs/ca-certificates.crt* is the default path for the system CA bundle on Debian systems. -This makes Envoy verify the server identity of *127.0.0.2:1234* in the same way as e.g. cURL does on -standard Debian installations. Common paths for system CA bundles on Linux and BSD are +:ref:`trusted_ca ` along with +:ref:`verify_subject_alt_name ` +makes Envoy verify the server identity of *127.0.0.2:1234* as "foo" in the same way as e.g. cURL +does on standard Debian installations. Common paths for system CA bundles on Linux and BSD are: * /etc/ssl/certs/ca-certificates.crt (Debian/Ubuntu/Gentoo etc.) * /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) @@ -122,6 +125,13 @@ standard Debian installations. Common paths for system CA bundles on Linux and B See the reference for :ref:`UpstreamTlsContexts ` and :ref:`DownstreamTlsContexts ` for other TLS options. +.. attention:: + + If only :ref:`trusted_ca ` is + specified, Envoy will verify the certificate chain of the presented certificate, but not its + subject name, hash, etc. Other validation context configuration is typically required depending + on the deployment. + .. _arch_overview_ssl_cert_select: Certificate selection diff --git a/docs/root/intro/deprecated.rst b/docs/root/intro/deprecated.rst index db85685e69be..58b57f691f20 100644 --- a/docs/root/intro/deprecated.rst +++ b/docs/root/intro/deprecated.rst @@ -39,12 +39,17 @@ Version 1.12.0 (pending) has been deprecated in favor of the `traffic_direction` field in :ref:`Listener `. The latter takes priority if specified. -* The `use_http2` field in :ref:`HTTP health checker ` has been deprecated in favor of the `codec_client_type` field. - -1.11.2 (October 8, 2019) -======================== -* Use of :ref:`idle_timeout ` is deprecated. Use :ref:`common_http_protocol_options ` instead. +* The `use_http2` field in + :ref:`HTTP health checker ` has been deprecated in + favor of the `codec_client_type` field. +Version 1.11.2 (October 8, 2019) +================================ +* Use of :ref:`idle_timeout + ` + is deprecated. Use :ref:`common_http_protocol_options + ` + instead. Version 1.11.0 (July 11, 2019) ============================== diff --git a/docs/root/start/start.rst b/docs/root/start/start.rst index 59a02b741b1e..99ff2488541e 100644 --- a/docs/root/start/start.rst +++ b/docs/root/start/start.rst @@ -155,7 +155,7 @@ gauge peoples' interests we will add more sandboxes demonstrating different features. The following sandboxes are available: .. toctree:: - :maxdepth: 1 + :maxdepth: 2 sandboxes/cors sandboxes/csrf @@ -176,7 +176,7 @@ In addition to the proxy itself, Envoy is also bundled as part of several open source distributions that target specific use cases. .. toctree:: - :maxdepth: 1 + :maxdepth: 2 distro/ambassador distro/gloo From fe3f964ad3d58e554634bd6d21a1c72af830c0e5 Mon Sep 17 00:00:00 2001 From: Matt Klein Date: Mon, 21 Oct 2019 10:51:32 -0700 Subject: [PATCH 2/2] comments Signed-off-by: Matt Klein --- .../configuration/overview/v2_overview.rst | 2 +- docs/root/faq/configuration/timeouts.rst | 33 ++++++++++++++----- .../http/http_connection_management.rst | 23 ++----------- .../arch_overview/listeners/listeners.rst | 2 +- docs/root/intro/version_history.rst | 3 ++ 5 files changed, 32 insertions(+), 31 deletions(-) diff --git a/docs/root/configuration/overview/v2_overview.rst b/docs/root/configuration/overview/v2_overview.rst index 9e2a93805123..004361529f13 100644 --- a/docs/root/configuration/overview/v2_overview.rst +++ b/docs/root/configuration/overview/v2_overview.rst @@ -5,7 +5,7 @@ Overview The Envoy v2 APIs are defined as `proto3 `_ `Protocol Buffers -`_ in the :repo:`api tree `. They +`_ in the :repo:`api tree `. They support: * Streaming delivery of :ref:`xDS ` API updates via gRPC. This reduces diff --git a/docs/root/faq/configuration/timeouts.rst b/docs/root/faq/configuration/timeouts.rst index d9be10920f12..ca34f0a97591 100644 --- a/docs/root/faq/configuration/timeouts.rst +++ b/docs/root/faq/configuration/timeouts.rst @@ -1,3 +1,5 @@ +.. _faq_configuration_timeouts: + How do I configure timeouts? ============================ @@ -15,6 +17,8 @@ HTTP/gRPC Connection timeouts ^^^^^^^^^^^^^^^^^^^ +Connection timeouts apply to the entire HTTP connection and all streams the connection carries. + * The HTTP protocol :ref:`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 @@ -26,28 +30,39 @@ Connection timeouts connections use the :ref:`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 ` - is the amount of time the connection manager will allow for the *entire request* to be received - by the client. + is the amount of time the connection manager will allow for the *entire request stream* to be + received by the client. .. attention:: - This timeout has no default value 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 - `, it is recommended to configure this timeout. + 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 `, it is recommended to configure this timeout. * The HTTP connection manager :ref:`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 if not otherwise specified is *5 minutes*. - This timeout is strongly recommended for streaming APIs. + 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 ` 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 has been received. + 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:: diff --git a/docs/root/intro/arch_overview/http/http_connection_management.rst b/docs/root/intro/arch_overview/http/http_connection_management.rst index dd7fc29fb8eb..fb7a37483b15 100644 --- a/docs/root/intro/arch_overview/http/http_connection_management.rst +++ b/docs/root/intro/arch_overview/http/http_connection_management.rst @@ -178,23 +178,6 @@ A sample redirect flow might look like this: Timeouts -------- -Various configurable timeouts apply to an HTTP connection and its constituent streams: - -* Connection-level :ref:`idle timeout - `: - this applies to the idle period where no streams are active. -* Connection-level :ref:`drain timeout - `: - this spans between an Envoy originated GOAWAY and connection termination. -* Stream-level idle timeout: this applies to each individual stream. It may be configured at both - the :ref:`connection manager - ` - and :ref:`per-route ` granularity. - Header/data/trailer events on the stream reset the idle timeout. -* Stream-level :ref:`per-route upstream timeout `: this - applies to the upstream response, i.e. a maximum bound on the time from the end of the downstream - request until the end of the upstream response. This may also be specified at the :ref:`per-retry - ` granularity. -* Stream-level :ref:`per-route gRPC max timeout - `: this bounds the upstream timeout and allows - the timeout to be overridden via the *grpc-timeout* request header. +Various configurable timeouts apply to an HTTP connection and its constituent streams. Please see +:ref:`this FAQ entry ` for an overview of important timeout +configuration. diff --git a/docs/root/intro/arch_overview/listeners/listeners.rst b/docs/root/intro/arch_overview/listeners/listeners.rst index a6fb8f6ecd82..2f841e220f4b 100644 --- a/docs/root/intro/arch_overview/listeners/listeners.rst +++ b/docs/root/intro/arch_overview/listeners/listeners.rst @@ -5,7 +5,7 @@ Listeners The Envoy configuration supports any number of listeners within a single process. Generally we recommend running a single Envoy per machine regardless of the number of configured listeners. This -allows for easier operation and a single source of statistics. Envoy supports both TCP and UDP +allows for easier operation and a single source of statistics. Currently Envoy only supports TCP listeners. Each listener is independently configured with some number :ref:`filter chains diff --git a/docs/root/intro/version_history.rst b/docs/root/intro/version_history.rst index fa3ce3065340..666b3acf727b 100644 --- a/docs/root/intro/version_history.rst +++ b/docs/root/intro/version_history.rst @@ -71,6 +71,9 @@ Version history header mutations wins flag ` * router: added :ref:`respect_expected_rq_timeout ` that instructs ingress Envoy to respect :ref:`config_http_filters_router_x-envoy-expected-rq-timeout-ms` header, populated by egress Envoy, when deriving timeout for upstream cluster. * router: added new :ref:`retriable request headers ` to retry policies. Retries can now be configured to only trigger on request header match. +* router: added the ability to match a route based on whether a TLS certificate has been + :ref:`presented ` by the + downstream connection. * router check tool: add coverage reporting & enforcement. * router check tool: add comprehensive coverage reporting. * router check tool: add deprecated field check.