diff --git a/api/envoy/config/core/v3/protocol.proto b/api/envoy/config/core/v3/protocol.proto index 65bd64d863a2..2c0ee96803dc 100644 --- a/api/envoy/config/core/v3/protocol.proto +++ b/api/envoy/config/core/v3/protocol.proto @@ -438,8 +438,6 @@ message GrpcProtocolOptions { Http2ProtocolOptions http2_protocol_options = 1; } -// [#not-implemented-hide:] -// // A message which allows using HTTP/3. message Http3ProtocolOptions { QuicProtocolOptions quic_protocol_options = 1; diff --git a/api/envoy/config/core/v4alpha/protocol.proto b/api/envoy/config/core/v4alpha/protocol.proto index 59c61510b4bc..965596136e06 100644 --- a/api/envoy/config/core/v4alpha/protocol.proto +++ b/api/envoy/config/core/v4alpha/protocol.proto @@ -432,8 +432,6 @@ message GrpcProtocolOptions { Http2ProtocolOptions http2_protocol_options = 1; } -// [#not-implemented-hide:] -// // A message which allows using HTTP/3. message Http3ProtocolOptions { option (udpa.annotations.versioning).previous_message_type = diff --git a/api/envoy/config/listener/v3/udp_listener_config.proto b/api/envoy/config/listener/v3/udp_listener_config.proto index 614f7e9d323e..57088ac5fe1f 100644 --- a/api/envoy/config/listener/v3/udp_listener_config.proto +++ b/api/envoy/config/listener/v3/udp_listener_config.proto @@ -33,8 +33,10 @@ message UdpListenerConfig { // Configuration for QUIC protocol. If empty, QUIC will not be enabled on this listener. Set // to the default object to enable QUIC without modifying any additional options. - // [#not-implemented-hide:] - // [#comment:Unhide when QUIC alpha is announced with other docs.] + // + // .. warning:: + // QUIC support is currently alpha and should be used with caution. Please + // see :ref:`here ` for details. QuicProtocolOptions quic_options = 7; } diff --git a/api/envoy/config/listener/v4alpha/udp_listener_config.proto b/api/envoy/config/listener/v4alpha/udp_listener_config.proto index fc99b86dd420..3cd272de3172 100644 --- a/api/envoy/config/listener/v4alpha/udp_listener_config.proto +++ b/api/envoy/config/listener/v4alpha/udp_listener_config.proto @@ -33,8 +33,10 @@ message UdpListenerConfig { // Configuration for QUIC protocol. If empty, QUIC will not be enabled on this listener. Set // to the default object to enable QUIC without modifying any additional options. - // [#not-implemented-hide:] - // [#comment:Unhide when QUIC alpha is announced with other docs.] + // + // .. warning:: + // QUIC support is currently alpha and should be used with caution. Please + // see :ref:`here ` for details. QuicProtocolOptions quic_options = 7; } diff --git a/api/envoy/extensions/upstreams/http/v3/http_protocol_options.proto b/api/envoy/extensions/upstreams/http/v3/http_protocol_options.proto index 2ce22fe6c0a7..6f28a4f4b234 100644 --- a/api/envoy/extensions/upstreams/http/v3/http_protocol_options.proto +++ b/api/envoy/extensions/upstreams/http/v3/http_protocol_options.proto @@ -59,7 +59,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#next-free-field: 6] message HttpProtocolOptions { // If this is used, the cluster will only operate on one of the possible upstream protocols. - // Note that HTTP/2 should generally be used for upstream clusters doing gRPC. + // Note that HTTP/2 or above should generally be used for upstream gRPC clusters. message ExplicitHttpConfig { oneof protocol_config { option (validate.required) = true; @@ -68,7 +68,9 @@ message HttpProtocolOptions { config.core.v3.Http2ProtocolOptions http2_protocol_options = 2; - // [#not-implemented-hide:] + // .. warning:: + // QUIC support is currently alpha and should be used with caution. Please + // see :ref:`here ` for details. config.core.v3.Http3ProtocolOptions http3_protocol_options = 3; } } @@ -80,7 +82,9 @@ message HttpProtocolOptions { config.core.v3.Http2ProtocolOptions http2_protocol_options = 2; - // [#not-implemented-hide:] + // .. warning:: + // QUIC support is currently alpha and should be used with caution. Please + // see :ref:`here ` for details. config.core.v3.Http3ProtocolOptions http3_protocol_options = 3; } @@ -98,11 +102,17 @@ message HttpProtocolOptions { config.core.v3.Http2ProtocolOptions http2_protocol_options = 2; - // [#not-implemented-hide:] // Unlike HTTP/1 and HTTP/2, HTTP/3 will not be configured unless it is - // present. If HTTP/3 is present, attempts to connect will first be made - // via HTTP/3, and if the HTTP/3 connection fails, TCP (HTTP/1 or HTTP/2 - // based on ALPN) will be used instead. + // present, and (soon) only if there is an indication of server side + // support. + // See :ref:`here ` for more information on + // when HTTP/3 will be used, and when Envoy will fail over to TCP. + // + // .. warning:: + // QUIC support is currently alpha and should be used with caution. Please + // see :ref:`here ` for details. + // AutoHttpConfig config is undergoing especially rapid change and as it + // is alpha is not guaranteed to be API-stable. config.core.v3.Http3ProtocolOptions http3_protocol_options = 3; } diff --git a/api/envoy/extensions/upstreams/http/v4alpha/http_protocol_options.proto b/api/envoy/extensions/upstreams/http/v4alpha/http_protocol_options.proto index 2011abc5a5a7..8545b77c1f0b 100644 --- a/api/envoy/extensions/upstreams/http/v4alpha/http_protocol_options.proto +++ b/api/envoy/extensions/upstreams/http/v4alpha/http_protocol_options.proto @@ -63,7 +63,7 @@ message HttpProtocolOptions { "envoy.extensions.upstreams.http.v3.HttpProtocolOptions"; // If this is used, the cluster will only operate on one of the possible upstream protocols. - // Note that HTTP/2 should generally be used for upstream clusters doing gRPC. + // Note that HTTP/2 or above should generally be used for upstream gRPC clusters. message ExplicitHttpConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig"; @@ -75,7 +75,9 @@ message HttpProtocolOptions { config.core.v4alpha.Http2ProtocolOptions http2_protocol_options = 2; - // [#not-implemented-hide:] + // .. warning:: + // QUIC support is currently alpha and should be used with caution. Please + // see :ref:`here ` for details. config.core.v4alpha.Http3ProtocolOptions http3_protocol_options = 3; } } @@ -90,7 +92,9 @@ message HttpProtocolOptions { config.core.v4alpha.Http2ProtocolOptions http2_protocol_options = 2; - // [#not-implemented-hide:] + // .. warning:: + // QUIC support is currently alpha and should be used with caution. Please + // see :ref:`here ` for details. config.core.v4alpha.Http3ProtocolOptions http3_protocol_options = 3; } @@ -111,11 +115,17 @@ message HttpProtocolOptions { config.core.v4alpha.Http2ProtocolOptions http2_protocol_options = 2; - // [#not-implemented-hide:] // Unlike HTTP/1 and HTTP/2, HTTP/3 will not be configured unless it is - // present. If HTTP/3 is present, attempts to connect will first be made - // via HTTP/3, and if the HTTP/3 connection fails, TCP (HTTP/1 or HTTP/2 - // based on ALPN) will be used instead. + // present, and (soon) only if there is an indication of server side + // support. + // See :ref:`here ` for more information on + // when HTTP/3 will be used, and when Envoy will fail over to TCP. + // + // .. warning:: + // QUIC support is currently alpha and should be used with caution. Please + // see :ref:`here ` for details. + // AutoHttpConfig config is undergoing especially rapid change and as it + // is alpha is not guaranteed to be API-stable. config.core.v4alpha.Http3ProtocolOptions http3_protocol_options = 3; } diff --git a/configs/envoyproxy_io_proxy_http3_downstream.template.yaml b/configs/envoyproxy_io_proxy_http3_downstream.yaml similarity index 56% rename from configs/envoyproxy_io_proxy_http3_downstream.template.yaml rename to configs/envoyproxy_io_proxy_http3_downstream.yaml index 2e7ace6c478a..2037b192af08 100644 --- a/configs/envoyproxy_io_proxy_http3_downstream.template.yaml +++ b/configs/envoyproxy_io_proxy_http3_downstream.yaml @@ -6,6 +6,50 @@ admin: address: 0.0.0.0 port_value: 9901 static_resources: + listeners: + - name: listener_tcp + address: + socket_address: + protocol: TCP + address: 0.0.0.0 + port_value: 10000 + filter_chains: + - transport_socket: + name: envoy.transport_sockets.tls + typed_config: + "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext + downstream_tls_context: + common_tls_context: + tls_certificates: + - certificate_chain: + filename: certs/servercert.pem + private_key: + filename: certs/serverkey.pem + filters: + - name: envoy.filters.network.http_connection_manager + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager + codec_type: HTTP2 + stat_prefix: ingress_http + route_config: + name: local_route + virtual_hosts: + - name: local_service + response_headers_to_add: + - header: + key: alt-svc + value: h3=":10000"; ma=86400, h3-29=":10000"; ma=86400 + domains: ["*"] + routes: + - match: + prefix: "/" + route: + host_rewrite_literal: www.envoyproxy.io + cluster: service_envoyproxy_io + http3_protocol_options: + http_filters: + - name: envoy.filters.http.router + listeners: - name: listener_udp address: @@ -19,18 +63,17 @@ static_resources: downstream_socket_config: prefer_gro: true filter_chains: - transport_socket: + - transport_socket: name: envoy.transport_sockets.quic typed_config: '@type': type.googleapis.com/envoy.extensions.transport_sockets.quic.v3.QuicDownstreamTransport downstream_tls_context: common_tls_context: - alpn_protocols: h3 tls_certificates: - certificate_chain: - filename: test/config/integration/certs/servercert.pem + - certificate_chain: + filename: certs/servercert.pem private_key: - filename: test/config/integration/certs/serverkey.pem + filename: certs/serverkey.pem filters: - name: envoy.filters.network.http_connection_manager typed_config: diff --git a/docs/root/configuration/best_practices/edge.rst b/docs/root/configuration/best_practices/edge.rst index d61c4684c71a..fdeb376d23b4 100644 --- a/docs/root/configuration/best_practices/edge.rst +++ b/docs/root/configuration/best_practices/edge.rst @@ -20,7 +20,7 @@ HTTP proxies should additionally configure: to true (to avoid consuming HTTP headers from external clients, see :ref:`HTTP header sanitizing ` for details), * :ref:`connection and stream timeouts `, -* :ref:`HTTP/2 maximum concurrent streams limit ` to 100, +* :ref:`HTTP/2 maximum concurrent streams limit ` and :ref:`HTTP/3 maximum concurrent streams limit ` to 100 * :ref:`HTTP/2 initial stream window size limit ` to 64 KiB, * :ref:`HTTP/2 initial connection window size limit ` to 1 MiB. * :ref:`headers_with_underscores_action setting ` to REJECT_REQUEST, to protect upstream services that treat '_' and '-' as interchangeable. diff --git a/docs/root/configuration/best_practices/level_two.rst b/docs/root/configuration/best_practices/level_two.rst index 857649ce6787..18d26b0318c9 100644 --- a/docs/root/configuration/best_practices/level_two.rst +++ b/docs/root/configuration/best_practices/level_two.rst @@ -10,20 +10,20 @@ edge use case may need to be adjusted when using Envoy in a multi-level deployme .. image:: /_static/multilevel_deployment.svg **In summary, if you run level two Envoy version 1.11.1 or greater which terminates -HTTP/2, we strongly advise you to change the HttpConnectionManager configuration of your level +HTTP/2 or above, we strongly advise you to change the HttpConnectionManager configuration of your level two Envoy, by setting its downstream** :ref:`validation of HTTP messaging option ` **to true.** -If there is an invalid HTTP/2 request and this option is not set, the Envoy in +If there is an invalid request and this option is not set, the Envoy in question will reset the entire connection. This behavior was changed as part of the 1.11.1 security release, to increase the security of Edge Envoys. Unfortunately, -because there are no guarantees that edge proxies will enforce HTTP/1 or HTTP/2 -standards compliance as rigorously as Envoy’s HTTP/2 stack does, this can result +because there are no guarantees that edge proxies will enforce HTTP +standards compliance as rigorously as Envoy’s stack does, this can result in a problem as follows. If one client sends a request that for example passes level one proxy's validation checks, and it is forwarded over an upstream multiplexed -HTTP/2 connection (potentially shared with other clients) the strict enforcement on -the level two Envoy HTTP/2 will reset all the streams on that connection, causing +connection (potentially shared with other clients) the strict enforcement on +the level two Envoy will reset all the streams on that connection, causing a service disruption to the clients sharing that L1-L2 connection. If a malicious user has insight into what traffic will bypass level one checks, they could spray “bad” traffic across the level one fleet, causing serious disruption to other users’ diff --git a/docs/root/configuration/http/http_conn_man/stats.rst b/docs/root/configuration/http/http_conn_man/stats.rst index bbabd97d60e9..21e561f92070 100644 --- a/docs/root/configuration/http/http_conn_man/stats.rst +++ b/docs/root/configuration/http/http_conn_man/stats.rst @@ -15,6 +15,7 @@ statistics: downstream_cx_http1_total, Counter, Total HTTP/1.1 connections downstream_cx_upgrades_total, Counter, Total successfully upgraded connections. These are also counted as total http1/http2 connections. downstream_cx_http2_total, Counter, Total HTTP/2 connections + downstream_cx_http3_total, Counter, Total HTTP/3 connections downstream_cx_destroy, Counter, Total connections destroyed downstream_cx_destroy_remote, Counter, Total connections destroyed due to remote close downstream_cx_destroy_local, Counter, Total connections destroyed due to local close @@ -26,6 +27,7 @@ statistics: downstream_cx_http1_active, Gauge, Total active HTTP/1.1 connections downstream_cx_upgrades_active, Gauge, Total active upgraded connections. These are also counted as active http1/http2 connections. downstream_cx_http2_active, Gauge, Total active HTTP/2 connections + downstream_cx_http3_active, Gauge, Total active HTTP/3 connections downstream_cx_protocol_error, Counter, Total protocol errors downstream_cx_length_ms, Histogram, Connection length milliseconds downstream_cx_rx_bytes_total, Counter, Total bytes received @@ -41,6 +43,7 @@ statistics: downstream_rq_total, Counter, Total requests downstream_rq_http1_total, Counter, Total HTTP/1.1 requests downstream_rq_http2_total, Counter, Total HTTP/2 requests + downstream_rq_http3_total, Counter, Total HTTP/3 requests downstream_rq_active, Gauge, Total active requests downstream_rq_response_before_rq_complete, Counter, Total responses sent before the request was complete downstream_rq_rx_reset, Counter, Total request resets received @@ -150,8 +153,8 @@ On the upstream side all http2 statistics are rooted at *cluster..http2.* .. attention:: - The HTTP/2 ``streams_active`` gauge may be greater than the HTTP connection manager - ``downstream_rq_active`` gauge due to differences in stream accounting between the codec and the + The HTTP/2 `streams_active` gauge may be greater than the HTTP connection manager + `downstream_rq_active` gauge due to differences in stream accounting between the codec and the HTTP connection manager. Tracing statistics diff --git a/docs/root/configuration/http/http_filters/aws_lambda_filter.rst b/docs/root/configuration/http/http_filters/aws_lambda_filter.rst index 38813aaeb8e0..701b399d7e24 100644 --- a/docs/root/configuration/http/http_filters/aws_lambda_filter.rst +++ b/docs/root/configuration/http/http_filters/aws_lambda_filter.rst @@ -11,7 +11,7 @@ AWS Lambda The AWS Lambda filter is currently under active development. -The HTTP AWS Lambda filter is used to trigger an AWS Lambda function from a standard HTTP/1.x or HTTP/2 request. +The HTTP AWS Lambda filter is used to trigger an AWS Lambda function from a standard HTTP request. It supports a few options to control whether to pass through the HTTP request payload as is or to wrap it in a JSON schema. diff --git a/docs/root/configuration/http/http_filters/grpc_http1_bridge_filter.rst b/docs/root/configuration/http/http_filters/grpc_http1_bridge_filter.rst index 5454468c5ac2..e1cb31cab22a 100644 --- a/docs/root/configuration/http/http_filters/grpc_http1_bridge_filter.rst +++ b/docs/root/configuration/http/http_filters/grpc_http1_bridge_filter.rst @@ -32,7 +32,7 @@ response trailers to a compliant gRPC server. It works by doing the following: work with unary gRPC APIs. This filter also collects stats for all gRPC requests that transit, even if those requests are -normal gRPC requests over HTTP/2. +normal gRPC requests over HTTP/2 or above. More info: wire format in `gRPC over HTTP/2 `_. diff --git a/docs/root/configuration/http/http_filters/grpc_http1_reverse_bridge_filter.rst b/docs/root/configuration/http/http_filters/grpc_http1_reverse_bridge_filter.rst index d8d918c76c3b..96e1c4979042 100644 --- a/docs/root/configuration/http/http_filters/grpc_http1_reverse_bridge_filter.rst +++ b/docs/root/configuration/http/http_filters/grpc_http1_reverse_bridge_filter.rst @@ -8,7 +8,7 @@ gRPC HTTP/1.1 reverse bridge * This filter should be configured with the name *envoy.filters.http.grpc_http1_reverse_bridge*. This is a filter that enables converting an incoming gRPC request into a HTTP/1.1 request to allow -a server that does not understand HTTP/2 or gRPC semantics to handle the request. +a server that does not understand HTTP/2 or HTTP/3 or gRPC semantics to handle the request. The filter works by: diff --git a/docs/root/configuration/http/http_filters/lua_filter.rst b/docs/root/configuration/http/http_filters/lua_filter.rst index 32180e901451..05cd149fc6ba 100644 --- a/docs/root/configuration/http/http_filters/lua_filter.rst +++ b/docs/root/configuration/http/http_filters/lua_filter.rst @@ -659,7 +659,7 @@ protocol() streamInfo:protocol() Returns the string representation of :repo:`HTTP protocol ` -used by the current request. The possible values are: *HTTP/1.0*, *HTTP/1.1*, and *HTTP/2*. +used by the current request. The possible values are: ``HTTP/1.0``, ``HTTP/1.1``, ``HTTP/2`` and ``HTTP/3*``. downstreamLocalAddress() ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/root/configuration/observability/access_log/stats.rst b/docs/root/configuration/observability/access_log/stats.rst index 9ea5d26ccec0..632ebaf48283 100644 --- a/docs/root/configuration/observability/access_log/stats.rst +++ b/docs/root/configuration/observability/access_log/stats.rst @@ -15,7 +15,7 @@ The gRPC access log has statistics rooted at *access_logs.grpc_access_log.* with :widths: 1, 1, 2 logs_written, Counter, Total log entries sent to the logger which were not dropped. This does not imply the logs have been flushed to the gRPC endpoint yet. - logs_dropped, Counter, Total log entries dropped due to network or HTTP/2 back up. + logs_dropped, Counter, Total log entries dropped due to network or application level back up. File access log statistics diff --git a/docs/root/configuration/observability/access_log/usage.rst b/docs/root/configuration/observability/access_log/usage.rst index d7409a7b1a57..4c4029c24529 100644 --- a/docs/root/configuration/observability/access_log/usage.rst +++ b/docs/root/configuration/observability/access_log/usage.rst @@ -181,7 +181,7 @@ The following command operators are supported: %PROTOCOL% HTTP - Protocol. Currently either *HTTP/1.1* or *HTTP/2*. + Protocol. Currently either *HTTP/1.1* *HTTP/2* or *HTTP/3*. TCP Not implemented ("-"). diff --git a/docs/root/configuration/upstream/cluster_manager/cluster_runtime.rst b/docs/root/configuration/upstream/cluster_manager/cluster_runtime.rst index 9f6c8808d17e..1efe95bc7936 100644 --- a/docs/root/configuration/upstream/cluster_manager/cluster_runtime.rst +++ b/docs/root/configuration/upstream/cluster_manager/cluster_runtime.rst @@ -140,9 +140,14 @@ upstream.healthy_panic_threshold Defaults to 50%. upstream.use_http2 - Whether the cluster utilizes the *http2* if configured in `HttpProtocolOptions `. + Whether the cluster uses ``HTTP/2`` if configured in `HttpProtocolOptions `. Set to 0 to disable HTTP/2 even if the feature is configured. Defaults to enabled. +upstream.use_http3 + Whether the cluster uses ``HTTP/3`` if configured in `HttpProtocolOptions `. + Set to 0 to disable HTTP/3 even if the feature is configured. Defaults to enabled. + + .. _config_cluster_manager_cluster_runtime_zone_routing: Zone aware load balancing diff --git a/docs/root/configuration/upstream/cluster_manager/cluster_stats.rst b/docs/root/configuration/upstream/cluster_manager/cluster_stats.rst index dec6e20fb7d7..055240a77172 100644 --- a/docs/root/configuration/upstream/cluster_manager/cluster_stats.rst +++ b/docs/root/configuration/upstream/cluster_manager/cluster_stats.rst @@ -38,6 +38,7 @@ Every cluster has a statistics tree rooted at *cluster..* with the followi upstream_cx_active, Gauge, Total active connections upstream_cx_http1_total, Counter, Total HTTP/1.1 connections upstream_cx_http2_total, Counter, Total HTTP/2 connections + upstream_cx_http3_total, Counter, Total HTTP/3 connections upstream_cx_connect_fail, Counter, Total connection failures upstream_cx_connect_timeout, Counter, Total connection connect timeouts upstream_cx_idle_timeout, Counter, Total connection idle timeouts @@ -51,7 +52,7 @@ Every cluster has a statistics tree rooted at *cluster..* with the followi upstream_cx_destroy_with_active_rq, Counter, Total connections destroyed with 1+ active request upstream_cx_destroy_local_with_active_rq, Counter, Total connections destroyed locally with 1+ active request upstream_cx_destroy_remote_with_active_rq, Counter, Total connections destroyed remotely with 1+ active request - upstream_cx_close_notify, Counter, Total connections closed via HTTP/1.1 connection close header or HTTP/2 GOAWAY + upstream_cx_close_notify, Counter, Total connections closed via HTTP/1.1 connection close header or HTTP/2 or HTTP/3 GOAWAY upstream_cx_rx_bytes_total, Counter, Total received connection bytes upstream_cx_rx_bytes_buffered, Gauge, Received connection bytes currently buffered upstream_cx_tx_bytes_total, Counter, Total sent connection bytes @@ -63,7 +64,7 @@ Every cluster has a statistics tree rooted at *cluster..* with the followi upstream_rq_total, Counter, Total requests upstream_rq_active, Gauge, Total active requests upstream_rq_pending_total, Counter, Total requests pending a connection pool connection - upstream_rq_pending_overflow, Counter, Total requests that overflowed connection pool or requests (mainly for HTTP/2) circuit breaking and were failed + upstream_rq_pending_overflow, Counter, Total requests that overflowed connection pool or requests (mainly for HTTP/2 and above) circuit breaking and were failed upstream_rq_pending_failure_eject, Counter, Total requests that were failed due to a connection pool connection failure or remote connection termination upstream_rq_pending_active, Gauge, Total active requests pending a connection pool connection upstream_rq_cancelled, Counter, Total requests cancelled before obtaining a connection pool connection diff --git a/docs/root/faq/configuration/flow_control.rst b/docs/root/faq/configuration/flow_control.rst index 9bbce146a95e..6bc3ef3e0133 100644 --- a/docs/root/faq/configuration/flow_control.rst +++ b/docs/root/faq/configuration/flow_control.rst @@ -22,12 +22,12 @@ and downstream. The listener limits are also propogated to the HttpConnectionManager, and applied on a per-stream basis to HTTP/1.1 L7 buffers described below. As such they limit the size of HTTP/1 requests and -response bodies that can be buffered. For HTTP/2, as many streams can be multiplexed over one TCP +response bodies that can be buffered. For HTTP/2 and HTTP/3, as many streams can be multiplexed over one connection, the L7 and L4 buffer limits can be tuned separately, and the configuration option :ref:`http2 stream limits ` -is applied to all of the L7 buffers. Note that for both HTTP/1 and -HTTP/2 Envoy can and will proxy arbitrarily large bodies on routes where all L7 filters are -streaming, but many filters such as the transcoder or buffer filters require the full HTTP body to +is applied to all of the L7 buffers. Note that for all version of HTTP Envoy can and will proxy +arbitrarily large bodies on routes where all L7 filters are streaming, but many filters such as the transcoder +or buffer filters require the full HTTP body to be buffered, so limit the request and response size based on the listener limit. The cluster limits affect how much raw data will be read per read() call from upstream, as diff --git a/docs/root/faq/configuration/timeouts.rst b/docs/root/faq/configuration/timeouts.rst index 7ca390c45d06..fd530474ea34 100644 --- a/docs/root/faq/configuration/timeouts.rst +++ b/docs/root/faq/configuration/timeouts.rst @@ -60,7 +60,7 @@ context request/stream is interchangeable. 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 all requests (not just streaming requests/responses) as it additionally defends - against an HTTP/2 peer that does not open stream window once an entire response has been buffered + against a peer that does not open the stream window once an entire response has been buffered to be sent to a downstream client. * The HTTP protocol :ref:`max_stream_duration ` is defined in a generic message used by the HTTP connection manager. The max stream duration is the diff --git a/docs/root/faq/load_balancing/concurrency_lb.rst b/docs/root/faq/load_balancing/concurrency_lb.rst index 0c247da7a17a..682d9b1ef69a 100644 --- a/docs/root/faq/load_balancing/concurrency_lb.rst +++ b/docs/root/faq/load_balancing/concurrency_lb.rst @@ -7,5 +7,5 @@ load balancing policies such as :ref:`round robin ` are not shared between workers. diff --git a/docs/root/intro/arch_overview/http/http.rst b/docs/root/intro/arch_overview/http/http.rst index 33b7ebffa6fa..0877cf3e62db 100644 --- a/docs/root/intro/arch_overview/http/http.rst +++ b/docs/root/intro/arch_overview/http/http.rst @@ -7,5 +7,6 @@ HTTP http_connection_management http_filters http_routing + http3 upgrades http_proxy diff --git a/docs/root/intro/arch_overview/http/http3.rst b/docs/root/intro/arch_overview/http/http3.rst new file mode 100644 index 000000000000..8f10cc4b4b8c --- /dev/null +++ b/docs/root/intro/arch_overview/http/http3.rst @@ -0,0 +1,52 @@ +.. _arch_overview_http3: + +HTTP3 overview +============== + +.. warning:: + + HTTP/3 support is still in Alpha, and should be used with caution. + Outstanding issues required for HTTP/3 to go GA can be found + `here `_ + For example QUIC does not currently support in-place filter chain updates, so users + requiring dynamic config reload for QUIC should wait until + `#13115 `_ has been addressed. + + For general feature requests beyond production readiness, you can track + the `area-quic `_ tag. + +HTTP3 downstream +---------------- + +Downstream Envoy HTTP/3 support can be turned up via adding +:ref:`quic_options ` and +ensuring the downstream transport socket is a QuicDownstreamTransport. + +See example :repo:`downstream HTTP/3 configuration ` for example configuration. + +Note that the example configuration includes both a TCP and a UDP listener, and the TCP +listener is advertising http/3 support via an ``alt-svc header``. Advertising HTTP/3 is not necessary for +in-house deployments where HTTP/3 is explicitly configured, but is needed for internet facing deployments +where TCP is the default, and clients such as Chrome will only attempt HTTP/3 if it is explicitly advertised. + +By default the example configuration uses kernel UDP support, but for production performance use of +BPF is strongly advised if Envoy is running with multiple worker threads. Envoy will attepmt to +use BPF on Linux by default if multiple worker threads are configured, but may require root, or at least +sudo-with-permissions (e.g. sudo setcap cap_bpf+ep). If multiple worker threads are configured, Envoy will +log a warning on start-up if BPF is unsupported on the platform, or is attempted and fails. + +HTTP3 upstream +-------------- + +HTTP/3 upstream support is still in Alpha, and should be used with caution. +Outstanding issues required for HTTP/3 to go GA can be found +`here `_ + +Envoy HTTP/3 support can be turned up by turning up HTTP/3 support in +:ref:`http_protocol_options `, +Either configuring HTTP/3 explicitly on, or using the auto_http option to use HTTP/3 if it is supported. + +See :ref:`here ` for more information about HTTP/3 connection pooling, including +detailed information of where QUIC will be used, and how it fails over to TCP when QUIC use is configured to be optional. + +An example upstream HTTP/3 configuration file can be found :repo:`here . 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 575da12520c8..f25d721cc52e 100644 --- a/docs/root/intro/arch_overview/http/http_connection_management.rst +++ b/docs/root/intro/arch_overview/http/http_connection_management.rst @@ -19,14 +19,14 @@ HTTP connection manager :ref:`configuration `. HTTP protocols -------------- -Envoy’s HTTP connection manager has native support for HTTP/1.1, WebSockets, and HTTP/2. It does not support +Envoy’s HTTP connection manager has native support for HTTP/1.1, WebSockets, HTTP/2 and HTTP/3. It does not support SPDY. Envoy’s HTTP support was designed to first and foremost be an HTTP/2 multiplexing proxy. Internally, HTTP/2 terminology is used to describe system components. For example, an HTTP request and response take place on a *stream*. A codec API is used to translate from different wire protocols into a protocol agnostic form for streams, requests, responses, etc. In the case of HTTP/1.1, the codec translates the serial/pipelining capabilities of the protocol into something that looks like HTTP/2 to higher layers. This means that the majority of the code does not need to -understand whether a stream originated on an HTTP/1.1 or HTTP/2 connection. +understand whether a stream originated on an HTTP/1.1, HTTP/2, or HTTP/3 connection. HTTP header sanitizing ---------------------- diff --git a/docs/root/intro/arch_overview/http/upgrades.rst b/docs/root/intro/arch_overview/http/upgrades.rst index d9d0765eaddd..c2f8278c8417 100644 --- a/docs/root/intro/arch_overview/http/upgrades.rst +++ b/docs/root/intro/arch_overview/http/upgrades.rst @@ -40,30 +40,30 @@ Note that the statistics for upgrades are all bundled together so WebSocket and :ref:`statistics ` are tracked by stats such as downstream_cx_upgrades_total and downstream_cx_upgrades_active -Websocket over HTTP/2 hops -^^^^^^^^^^^^^^^^^^^^^^^^^^ +Websocket over HTTP/2 or HTTP/3 hops +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -While HTTP/2 support for WebSockets is off by default, Envoy does support tunneling WebSockets over -HTTP/2 streams for deployments that prefer a uniform HTTP/2 mesh throughout; this enables, for example, +While HTTP/2 and HTTP/3 support for WebSockets is off by default, Envoy does support tunneling WebSockets over +HTTP/2 and above for deployments that prefer a uniform HTTP/2+ mesh throughout; this enables, for example, a deployment of the form: [Client] ---- HTTP/1.1 ---- [Front Envoy] ---- HTTP/2 ---- [Sidecar Envoy ---- H1 ---- App] In this case, if a client is for example using WebSocket, we want the Websocket to arrive at the -upstream server functionally intact, which means it needs to traverse the HTTP/2 hop. +upstream server functionally intact, which means it needs to traverse the HTTP/2+ hop. This is accomplished via `Extended CONNECT (RFC8441) `_ support, turned on by setting :ref:`allow_connect ` true at the second layer Envoy. The -WebSocket request will be transformed into an HTTP/2 CONNECT stream, with :protocol header -indicating the original upgrade, traverse the HTTP/2 hop, and be downgraded back into an HTTP/1 +WebSocket request will be transformed into an HTTP/2+ CONNECT stream, with :protocol header +indicating the original upgrade, traverse the HTTP/2+ hop, and be downgraded back into an HTTP/1 WebSocket Upgrade. This same Upgrade-CONNECT-Upgrade transformation will be performed on any -HTTP/2 hop, with the documented flaw that the HTTP/1.1 method is always assumed to be GET. +HTTP/2+ hop, with the documented flaw that the HTTP/1.1 method is always assumed to be GET. Non-WebSocket upgrades are allowed to use any valid HTTP method (i.e. POST) and the current upgrade/downgrade mechanism will drop the original method and transform the Upgrade request to a GET method on the final Envoy-Upstream hop. -Note that the HTTP/2 upgrade path has very strict HTTP/1.1 compliance, so will not proxy WebSocket +Note that the HTTP/2+ upgrade path has very strict HTTP/1.1 compliance, so will not proxy WebSocket upgrade requests or responses with bodies. CONNECT support @@ -73,7 +73,7 @@ Envoy CONNECT support is off by default (Envoy will send an internally generated CONNECT requests). CONNECT support can be enabled via the upgrade options described above, setting the upgrade value to the special keyword "CONNECT". -While for HTTP/2, CONNECT request may have a path, in general and for HTTP/1.1 CONNECT requests do +While for HTTP/2 and above, CONNECT request may have a path, in general and for HTTP/1.1 CONNECT requests do not have a path, and can only be matched using a :ref:`connect_matcher `. Please also note that when doing non-wildcard domain matching for CONNECT requests, the CONNECT target is matched @@ -110,7 +110,7 @@ Tunneling TCP over HTTP Envoy also has support for tunneling raw TCP over HTTP CONNECT or HTTP POST requests. Find below some usage scenarios. -HTTP/2 CONNECT can be used to proxy multiplexed TCP over pre-warmed secure connections and amortize +HTTP/2+ CONNECT can be used to proxy multiplexed TCP over pre-warmed secure connections and amortize the cost of any TLS handshake. An example set up proxying SMTP would look something like this: @@ -124,7 +124,7 @@ supporting HTTP/2): Note that when using HTTP/1 CONNECT you will end up having a TCP connection between L1 and L2 Envoy for each TCP client connection, it is preferable to use -HTTP/2 when you have the choice. +HTTP/2 or above when you have the choice. HTTP POST can also be used to proxy multiplexed TCP when intermediate proxies that don't support CONNECT. An example set up proxying HTTP would look something like this: diff --git a/docs/root/intro/arch_overview/other_protocols/grpc.rst b/docs/root/intro/arch_overview/other_protocols/grpc.rst index 01275183b155..201af54d21c9 100644 --- a/docs/root/intro/arch_overview/other_protocols/grpc.rst +++ b/docs/root/intro/arch_overview/other_protocols/grpc.rst @@ -4,12 +4,12 @@ gRPC ==== `gRPC `_ is an RPC framework from Google. It uses protocol buffers as the -underlying serialization/IDL format. At the transport layer it uses HTTP/2 for request/response +underlying serialization/IDL format. At the transport layer it uses HTTP/2 or above for request/response multiplexing. Envoy has first class support for gRPC both at the transport layer as well as at the application layer: -* gRPC makes use of HTTP/2 trailers to convey request status. Envoy is one of very few HTTP proxies - that correctly supports HTTP/2 trailers and is thus one of the few proxies that can transport +* gRPC makes use of trailers to convey request status. Envoy is one of very few HTTP proxies + that correctly supports trailers and is thus one of the few proxies that can transport gRPC requests and responses. * The gRPC runtime for some languages is relatively immature. See :ref:`below ` for an overview of filters that can help bring gRPC to more languages. @@ -29,7 +29,7 @@ gRPC bridging Envoy supports two gRPC bridges: * :ref:`grpc_http1_bridge filter ` which allows gRPC requests to be sent to Envoy over - HTTP/1.1. Envoy then translates the requests to HTTP/2 for transport to the target server. The response is translated back to HTTP/1.1. + HTTP/1.1. Envoy then translates the requests to HTTP/2 or HTTP/3 for transport to the target server. The response is translated back to HTTP/1.1. When installed, the bridge filter gathers per RPC statistics in addition to the standard array of global HTTP statistics. * :ref:`grpc_http1_reverse_bridge filter ` which allows gRPC requests to be sent to Envoy and then translated to HTTP/1.1 when sent to the upstream. The response is then converted back into gRPC when sent to the downstream. @@ -52,7 +52,7 @@ When specifying gRPC services, it's necessary to specify the use of either the discuss the tradeoffs in this choice below. The Envoy gRPC client is a minimal custom implementation of gRPC that makes use -of Envoy's HTTP/2 upstream connection management. Services are specified as +of Envoy's HTTP/2 or HTTP/3 upstream connection management. Services are specified as regular Envoy :ref:`clusters `, with regular treatment of :ref:`timeouts, retries `, endpoint :ref:`discovery `/:ref:`load diff --git a/docs/root/intro/arch_overview/upstream/circuit_breaking.rst b/docs/root/intro/arch_overview/upstream/circuit_breaking.rst index 56dcd13bcd1c..9096c5641ff8 100644 --- a/docs/root/intro/arch_overview/upstream/circuit_breaking.rst +++ b/docs/root/intro/arch_overview/upstream/circuit_breaking.rst @@ -31,7 +31,7 @@ configure and code each application independently. Envoy supports various types configured, all requests will be multiplexed over the same connection so this circuit breaker will only be hit when no connection is already established. If this circuit breaker overflows the :ref:`upstream_rq_pending_overflow ` counter for the cluster will - increment. + increment. For HTTP/3 the equivalent to HTTP/2's :ref:`max concurrent streams ` is :ref:`max concurrent streams ` * **Cluster maximum requests**: The maximum number of requests that can be outstanding to all hosts in a cluster at any given time. If this circuit breaker overflows the :ref:`upstream_rq_pending_overflow ` counter for the cluster will increment. diff --git a/docs/root/intro/arch_overview/upstream/cluster_manager.rst b/docs/root/intro/arch_overview/upstream/cluster_manager.rst index 8550d3a0655b..fd367d4e959a 100644 --- a/docs/root/intro/arch_overview/upstream/cluster_manager.rst +++ b/docs/root/intro/arch_overview/upstream/cluster_manager.rst @@ -11,11 +11,11 @@ Upstream clusters and hosts are abstracted from the network/HTTP filter stack gi clusters and hosts may be used for any number of different proxy tasks. The cluster manager exposes APIs to the filter stack that allow filters to obtain a L3/L4 connection to an upstream cluster, or a handle to an abstract HTTP connection pool to an upstream cluster (whether the upstream host -supports HTTP/1.1 or HTTP/2 is hidden). A filter stage determines whether it needs an L3/L4 +supports HTTP/1.1, HTTP/2, or HTTP/3 is hidden). A filter stage determines whether it needs an L3/L4 connection or a new HTTP stream and the cluster manager handles all of the complexity of knowing which hosts are available and healthy, load balancing, thread local storage of upstream connection data (since most Envoy code is written to be single threaded), upstream connection type (TCP/IP, -UDS), upstream protocol where applicable (HTTP/1.1, HTTP/2), etc. +UDS), upstream protocol where applicable (HTTP/1.1, HTTP/2, HTTP/3), etc. Clusters known to the cluster manager can be configured either statically, or fetched dynamically via the cluster discovery service (CDS) API. Dynamic cluster fetches allow more configuration to diff --git a/docs/root/intro/arch_overview/upstream/connection_pooling.rst b/docs/root/intro/arch_overview/upstream/connection_pooling.rst index dc794404f630..0c1a26d79dca 100644 --- a/docs/root/intro/arch_overview/upstream/connection_pooling.rst +++ b/docs/root/intro/arch_overview/upstream/connection_pooling.rst @@ -4,7 +4,7 @@ Connection pooling ================== For HTTP traffic, Envoy supports abstract connection pools that are layered on top of the underlying -wire protocol (HTTP/1.1 or HTTP/2). The utilizing filter code does not need to be aware of whether +wire protocol (HTTP/1.1, HTTP/2, HTTP/3). The utilizing filter code does not need to be aware of whether the underlying protocol supports true multiplexing or not. In practice the underlying implementations have the following high level properties: @@ -32,17 +32,59 @@ pool will drain the affected connection. Once a connection reaches its :ref:`max stream limit `, it will be marked as busy until a stream is available. New connections are established anytime there is a pending request without a connection that can be dispatched to (up to circuit breaker limits for -connections). HTTP/2 is the preferred communication protocol, as connections rarely, if ever, get -severed. +connections). HTTP/2 is the preferred communication protocol when Envoy is operating as a reverse proxy, +as connections rarely, if ever, get severed. + +HTTP/3 +------ + +The HTTP/3 connection pool multiplexes multiple requests over a single connection, up to the limits +imposed by :ref:`max concurrent streams +` and :ref:`max +requests per connection `. +The HTTP/3 connection pool establishes as many connections as are needed to serve requests. With no +limits, this will be only a single connection. If a GOAWAY frame is received or if the connection +reaches the :ref:`maximum requests per connection +` limit, the connection +pool will drain the affected connection. Once a connection reaches its :ref:`maximum concurrent +stream limit `, it +will be marked as busy until a stream is available. New connections are established anytime there is +a pending request without a connection that can be dispatched to (up to circuit breaker limits for +connections). HTTP/3 upstream support is currently only usable in situations where HTTP/3 is guaranteed +to work, but automatic failover to TCP is coming soon!. + +Automatic protocol selection +---------------------------- + +For Envoy acting as a forward proxy, the preferred configuration is the +`AutoHttpConfig ` +, configued via +`http_protocol_options `. +By default it will use TCP and ALPN to select the best available protocol of HTTP/2 and HTTP/1.1. + +.. _arch_overview_http3_upstream: + +If HTTP/3 is configured in the automatic pool it will currently attempt an QUIC connection first, +then 300ms later, if a QUIC connection is not established, will also attempt to establish a TCP connection. +Whichever handshake succeeds will be used for the initial +stream, but if both TCP and QUIC connections are established, QUIC will eventually be preferred. + +Upcoming versions of HTTP/3 support will include only selecting HTTP/3 if the upstream advertises support +either via `HTTP Alternative Services `_, +`HTTPS DNS RR `_, or "QUIC hints" which +will be manually configured. This path is alpha and rapidly undergoing improvements with the goal of having +the default behavior result in optimal latency for internet environments, so please be patient and follow along with Envoy release notes +to stay aprised of the latest and greatest changes. + .. _arch_overview_conn_pool_how_many: Number of connection pools -------------------------- -Each host in each cluster will have one or more connection pools. If the cluster is HTTP/1 or HTTP/2 -only, then the host may have only a single connection pool. However, if the cluster supports multiple -upstream protocols, then at least one connection pool per protocol will be allocated. Separate +Each host in each cluster will have one or more connection pools. If the cluster has a single explicit +protocol configured, then the host may have only a single connection pool. However, if the cluster supports multiple +upstream protocols, then unless it is using ALPN, one connection pool per protocol may be allocated. Separate connection pools are also allocated for each of the following features: * :ref:`Routing priority ` diff --git a/docs/root/intro/deployment_types/double_proxy.rst b/docs/root/intro/deployment_types/double_proxy.rst index 84d882d2bb5a..cbf6cef40f4b 100644 --- a/docs/root/intro/deployment_types/double_proxy.rst +++ b/docs/root/intro/deployment_types/double_proxy.rst @@ -11,7 +11,7 @@ another Envoy cluster running as a *double proxy*. The idea behind the double pr more efficient to terminate TLS and client connections as close as possible to the user (shorter round trip times for the TLS 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. +or HTTP/3 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 TLS mutual authentication and pinned certificates. This allows diff --git a/docs/root/intro/deployment_types/front_proxy.rst b/docs/root/intro/deployment_types/front_proxy.rst index f335f7a05d00..a8a11d4177c9 100644 --- a/docs/root/intro/deployment_types/front_proxy.rst +++ b/docs/root/intro/deployment_types/front_proxy.rst @@ -10,7 +10,7 @@ configuration sitting behind an Envoy cluster used as an HTTP L7 edge reverse pr reverse proxy provides the following features: * Terminates TLS. -* Supports both HTTP/1.1 and HTTP/2. +* Supports HTTP/1.1, HTTP/2, and HTTP/3. * 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 diff --git a/docs/root/intro/deployment_types/service_to_service.rst b/docs/root/intro/deployment_types/service_to_service.rst index 73e785bda9e6..eb5dde1101d7 100644 --- a/docs/root/intro/deployment_types/service_to_service.rst +++ b/docs/root/intro/deployment_types/service_to_service.rst @@ -14,7 +14,7 @@ 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 +http://localhost:9001. HTTP and gRPC requests use the HTTP/1.1 *host* header or the HTTP/2 or HTTP/3 *: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 @@ -38,7 +38,7 @@ 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. +better performance than HTTP/1.1 via long lived connections and explicit reset notifications. .. image:: /_static/service_to_service_ingress_listener.svg :width: 55% diff --git a/docs/root/intro/what_is_envoy.rst b/docs/root/intro/what_is_envoy.rst index 9f89575877d6..84acb61ac087 100644 --- a/docs/root/intro/what_is_envoy.rst +++ b/docs/root/intro/what_is_envoy.rst @@ -46,13 +46,16 @@ clients and target servers can be bridged. The recommended service to service co HTTP/2 between all Envoys to create a mesh of persistent connections that requests and responses can be multiplexed over. +**HTTP/3 support (currently in alpha):** As of 1.19.0, Envoy now supports HTTP/3 upstream and downstream, +and translating between any combination of HTTP/1.1, HTTP/2 and HTTP/3 in either direction. + **HTTP L7 routing:** When operating in HTTP mode, Envoy supports a :ref:`routing ` subsystem that is capable of routing and redirecting requests based on path, authority, content type, :ref:`runtime ` values, etc. This functionality is most useful when using Envoy as a front/edge proxy but is also leveraged when building a service to service mesh. -**gRPC support:** `gRPC `_ is an RPC framework from Google that uses HTTP/2 +**gRPC support:** `gRPC `_ is an RPC framework from Google that uses HTTP/2 or above as the underlying multiplexed transport. Envoy :ref:`supports ` all of the HTTP/2 features required to be used as the routing and load balancing substrate for gRPC requests and responses. The two systems are very complementary. @@ -88,7 +91,7 @@ racing. **Front/edge proxy support:** There is substantial benefit in using the same software at the edge (observability, management, identical service discovery and load balancing algorithms, etc.). Envoy has a feature set that makes it well suited as an edge proxy for most modern web application use -cases. This includes :ref:`TLS ` termination, HTTP/1.1 and HTTP/2 :ref:`support +cases. This includes :ref:`TLS ` termination, HTTP/1.1 HTTP/2 and HTTP/3 :ref:`support `, as well as HTTP L7 :ref:`routing `. **Best in class observability:** As stated above, the primary goal of Envoy is to make the network diff --git a/docs/root/start/sandboxes/grpc_bridge.rst b/docs/root/start/sandboxes/grpc_bridge.rst index 90b98021729b..e3ce921141c0 100644 --- a/docs/root/start/sandboxes/grpc_bridge.rst +++ b/docs/root/start/sandboxes/grpc_bridge.rst @@ -13,7 +13,8 @@ The gRPC bridge sandbox is an example usage of Envoy's This is an example of a key-value store where an ``http``-based client CLI, written in ``Python``, updates a remote store, written in ``Go``, using the stubs generated for both languages. -The client send messages through a proxy that upgrades the HTTP requests from ``http/1.1`` to ``http/2``. +The client send messages through a proxy that upgrades the HTTP requests from ``http/1.1`` to ``http/2`` or +``http/3`` ``[client](http/1.1) -> [client-egress-proxy](http/2) -> [server-ingress-proxy](http/2) -> [server]`` diff --git a/docs/root/version_history/current.rst b/docs/root/version_history/current.rst index 76651aa7f917..d20206521ee0 100644 --- a/docs/root/version_history/current.rst +++ b/docs/root/version_history/current.rst @@ -49,6 +49,7 @@ Removed Config or Runtime New Features ------------ +* http: added upstream and downstream alpha HTTP/3 support! See :ref:`quic_options ` for downstream and the new http3_protocol_options in :ref:`http_protocol_options ` for upstream HTTP/3. * listener: added ability to change an existing listener's address. * metric service: added support for sending metric tags as labels. This can be enabled by setting the :ref:`emit_tags_as_labels ` field to true. * udp_proxy: added :ref:`key ` as another hash policy to support hash based routing on any given key. diff --git a/generated_api_shadow/envoy/config/core/v3/protocol.proto b/generated_api_shadow/envoy/config/core/v3/protocol.proto index 65bd64d863a2..2c0ee96803dc 100644 --- a/generated_api_shadow/envoy/config/core/v3/protocol.proto +++ b/generated_api_shadow/envoy/config/core/v3/protocol.proto @@ -438,8 +438,6 @@ message GrpcProtocolOptions { Http2ProtocolOptions http2_protocol_options = 1; } -// [#not-implemented-hide:] -// // A message which allows using HTTP/3. message Http3ProtocolOptions { QuicProtocolOptions quic_protocol_options = 1; diff --git a/generated_api_shadow/envoy/config/core/v4alpha/protocol.proto b/generated_api_shadow/envoy/config/core/v4alpha/protocol.proto index badf94fc995f..199503fce37b 100644 --- a/generated_api_shadow/envoy/config/core/v4alpha/protocol.proto +++ b/generated_api_shadow/envoy/config/core/v4alpha/protocol.proto @@ -444,8 +444,6 @@ message GrpcProtocolOptions { Http2ProtocolOptions http2_protocol_options = 1; } -// [#not-implemented-hide:] -// // A message which allows using HTTP/3. message Http3ProtocolOptions { option (udpa.annotations.versioning).previous_message_type = diff --git a/generated_api_shadow/envoy/config/listener/v3/udp_listener_config.proto b/generated_api_shadow/envoy/config/listener/v3/udp_listener_config.proto index 8c89ad0032ac..276e98153aeb 100644 --- a/generated_api_shadow/envoy/config/listener/v3/udp_listener_config.proto +++ b/generated_api_shadow/envoy/config/listener/v3/udp_listener_config.proto @@ -34,8 +34,10 @@ message UdpListenerConfig { // Configuration for QUIC protocol. If empty, QUIC will not be enabled on this listener. Set // to the default object to enable QUIC without modifying any additional options. - // [#not-implemented-hide:] - // [#comment:Unhide when QUIC alpha is announced with other docs.] + // + // .. warning:: + // QUIC support is currently alpha and should be used with caution. Please + // see :ref:`here ` for details. QuicProtocolOptions quic_options = 7; oneof config_type { diff --git a/generated_api_shadow/envoy/config/listener/v4alpha/udp_listener_config.proto b/generated_api_shadow/envoy/config/listener/v4alpha/udp_listener_config.proto index fc99b86dd420..3cd272de3172 100644 --- a/generated_api_shadow/envoy/config/listener/v4alpha/udp_listener_config.proto +++ b/generated_api_shadow/envoy/config/listener/v4alpha/udp_listener_config.proto @@ -33,8 +33,10 @@ message UdpListenerConfig { // Configuration for QUIC protocol. If empty, QUIC will not be enabled on this listener. Set // to the default object to enable QUIC without modifying any additional options. - // [#not-implemented-hide:] - // [#comment:Unhide when QUIC alpha is announced with other docs.] + // + // .. warning:: + // QUIC support is currently alpha and should be used with caution. Please + // see :ref:`here ` for details. QuicProtocolOptions quic_options = 7; } diff --git a/generated_api_shadow/envoy/extensions/upstreams/http/v3/http_protocol_options.proto b/generated_api_shadow/envoy/extensions/upstreams/http/v3/http_protocol_options.proto index 2ce22fe6c0a7..6f28a4f4b234 100644 --- a/generated_api_shadow/envoy/extensions/upstreams/http/v3/http_protocol_options.proto +++ b/generated_api_shadow/envoy/extensions/upstreams/http/v3/http_protocol_options.proto @@ -59,7 +59,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#next-free-field: 6] message HttpProtocolOptions { // If this is used, the cluster will only operate on one of the possible upstream protocols. - // Note that HTTP/2 should generally be used for upstream clusters doing gRPC. + // Note that HTTP/2 or above should generally be used for upstream gRPC clusters. message ExplicitHttpConfig { oneof protocol_config { option (validate.required) = true; @@ -68,7 +68,9 @@ message HttpProtocolOptions { config.core.v3.Http2ProtocolOptions http2_protocol_options = 2; - // [#not-implemented-hide:] + // .. warning:: + // QUIC support is currently alpha and should be used with caution. Please + // see :ref:`here ` for details. config.core.v3.Http3ProtocolOptions http3_protocol_options = 3; } } @@ -80,7 +82,9 @@ message HttpProtocolOptions { config.core.v3.Http2ProtocolOptions http2_protocol_options = 2; - // [#not-implemented-hide:] + // .. warning:: + // QUIC support is currently alpha and should be used with caution. Please + // see :ref:`here ` for details. config.core.v3.Http3ProtocolOptions http3_protocol_options = 3; } @@ -98,11 +102,17 @@ message HttpProtocolOptions { config.core.v3.Http2ProtocolOptions http2_protocol_options = 2; - // [#not-implemented-hide:] // Unlike HTTP/1 and HTTP/2, HTTP/3 will not be configured unless it is - // present. If HTTP/3 is present, attempts to connect will first be made - // via HTTP/3, and if the HTTP/3 connection fails, TCP (HTTP/1 or HTTP/2 - // based on ALPN) will be used instead. + // present, and (soon) only if there is an indication of server side + // support. + // See :ref:`here ` for more information on + // when HTTP/3 will be used, and when Envoy will fail over to TCP. + // + // .. warning:: + // QUIC support is currently alpha and should be used with caution. Please + // see :ref:`here ` for details. + // AutoHttpConfig config is undergoing especially rapid change and as it + // is alpha is not guaranteed to be API-stable. config.core.v3.Http3ProtocolOptions http3_protocol_options = 3; } diff --git a/generated_api_shadow/envoy/extensions/upstreams/http/v4alpha/http_protocol_options.proto b/generated_api_shadow/envoy/extensions/upstreams/http/v4alpha/http_protocol_options.proto index 2011abc5a5a7..8545b77c1f0b 100644 --- a/generated_api_shadow/envoy/extensions/upstreams/http/v4alpha/http_protocol_options.proto +++ b/generated_api_shadow/envoy/extensions/upstreams/http/v4alpha/http_protocol_options.proto @@ -63,7 +63,7 @@ message HttpProtocolOptions { "envoy.extensions.upstreams.http.v3.HttpProtocolOptions"; // If this is used, the cluster will only operate on one of the possible upstream protocols. - // Note that HTTP/2 should generally be used for upstream clusters doing gRPC. + // Note that HTTP/2 or above should generally be used for upstream gRPC clusters. message ExplicitHttpConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig"; @@ -75,7 +75,9 @@ message HttpProtocolOptions { config.core.v4alpha.Http2ProtocolOptions http2_protocol_options = 2; - // [#not-implemented-hide:] + // .. warning:: + // QUIC support is currently alpha and should be used with caution. Please + // see :ref:`here ` for details. config.core.v4alpha.Http3ProtocolOptions http3_protocol_options = 3; } } @@ -90,7 +92,9 @@ message HttpProtocolOptions { config.core.v4alpha.Http2ProtocolOptions http2_protocol_options = 2; - // [#not-implemented-hide:] + // .. warning:: + // QUIC support is currently alpha and should be used with caution. Please + // see :ref:`here ` for details. config.core.v4alpha.Http3ProtocolOptions http3_protocol_options = 3; } @@ -111,11 +115,17 @@ message HttpProtocolOptions { config.core.v4alpha.Http2ProtocolOptions http2_protocol_options = 2; - // [#not-implemented-hide:] // Unlike HTTP/1 and HTTP/2, HTTP/3 will not be configured unless it is - // present. If HTTP/3 is present, attempts to connect will first be made - // via HTTP/3, and if the HTTP/3 connection fails, TCP (HTTP/1 or HTTP/2 - // based on ALPN) will be used instead. + // present, and (soon) only if there is an indication of server side + // support. + // See :ref:`here ` for more information on + // when HTTP/3 will be used, and when Envoy will fail over to TCP. + // + // .. warning:: + // QUIC support is currently alpha and should be used with caution. Please + // see :ref:`here ` for details. + // AutoHttpConfig config is undergoing especially rapid change and as it + // is alpha is not guaranteed to be API-stable. config.core.v4alpha.Http3ProtocolOptions http3_protocol_options = 3; } diff --git a/tools/spelling/spelling_dictionary.txt b/tools/spelling/spelling_dictionary.txt index 878eeb1d81fe..44481c60f7af 100644 --- a/tools/spelling/spelling_dictionary.txt +++ b/tools/spelling/spelling_dictionary.txt @@ -1134,6 +1134,7 @@ subtypes subzone superclass superset +svc symlink symlinked symlinks