docs: unhiding HTTP/3 and adding docs (#15926)

Unhiding HTTP/3 upstream and downstream configuration, linking to example configs, and updating docs for HTTP/3 alpha.

Risk Level: n/a
Testing: n/a
Docs Changes: yes
Release Notes: inline
#14829 #2557 #15845
Fixes #12923

Co-Authored-By: Michael Payne michael@sooper.org
Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

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;

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 <arch_overview_http3>` for details.
   QuicProtocolOptions quic_options = 7;
 }
 

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 <arch_overview_http3>` 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 <arch_overview_http3>` 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 <arch_overview_http3_upstream>` 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 <arch_overview_http3>` 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;
   }
 

configs/envoyproxy_io_proxy_http3_downstream.template.yaml → 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:

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 <config_http_conn_man_header_sanitizing>`
   for details),
 * :ref:`connection and stream timeouts <faq_configuration_timeouts>`,
-* :ref:`HTTP/2 maximum concurrent streams limit <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.max_concurrent_streams>` to 100,
+* :ref:`HTTP/2 maximum concurrent streams limit <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.max_concurrent_streams>` and :ref:`HTTP/3 maximum concurrent streams limit <envoy_v3_api_field_config.core.v3.QuicProtocolOptions.max_concurrent_streams>` to 100
 * :ref:`HTTP/2 initial stream window size limit <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.initial_stream_window_size>` to 64 KiB,
 * :ref:`HTTP/2 initial connection window size limit <envoy_v3_api_field_config.core.v3.Http2ProtocolOptions.initial_connection_window_size>` to 1 MiB.
 * :ref:`headers_with_underscores_action setting <envoy_v3_api_field_config.core.v3.HttpProtocolOptions.headers_with_underscores_action>` to REJECT_REQUEST, to protect upstream services that treat '_' and '-' as interchangeable.

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 <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.stream_error_on_invalid_http_message>`
 **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’

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.<name>.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

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.
 

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 <https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md>`_.
 

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:
 

docs/root/configuration/http/http_filters/lua_filter.rst

@@ -659,7 +659,7 @@ protocol()
   streamInfo:protocol()
 
 Returns the string representation of :repo:`HTTP protocol <include/envoy/http/protocol.h>`
-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()
 ^^^^^^^^^^^^^^^^^^^^^^^^

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

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 ("-").

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 <envoy_v3_msg_config.upstreams.http.v3.HttpProtocolOptions>`.
+  Whether the cluster uses ``HTTP/2`` if configured in `HttpProtocolOptions <envoy_v3_msg_config.upstreams.http.v3.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 <envoy_v3_msg_config.upstreams.http.v3.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

docs/root/configuration/upstream/cluster_manager/cluster_stats.rst

@@ -38,6 +38,7 @@ Every cluster has a statistics tree rooted at *cluster.<name>.* 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.<name>.* 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.<name>.* 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