docs/root/intro/arch_overview/http/http3.rst
.. _arch_overview_http3:
.. warning::
While HTTP/3 downstream support is deemed ready for production use, improvements are ongoing,
tracked in the area-quic <https://github.com/envoyproxy/envoy/labels/area%2Fquic>_ tag.
HTTP/3 upstream support is alpha - key features are implemented but have not been tested at scale.
.. _arch_overview_http3_downstream:
Downstream Envoy HTTP/3 support can be turned up via adding
:ref:quic_options <envoy_v3_api_field_config.listener.v3.UdpListenerConfig.quic_options>,
ensuring the downstream transport socket is a
:ref:QuicDownstreamTransport <envoy_v3_api_msg_extensions.transport_sockets.quic.v3.QuicDownstreamTransport>,
and setting the codec to HTTP/3.
.. note:: Hot restart is not gracefully handled for HTTP/3 yet.
.. tip::
See :repo:downstream HTTP/3 configuration </configs/envoyproxy_io_proxy_http3_downstream.yaml>
for example configuration.
This example configuration includes both a TCP and a UDP listener, and the TCP
listener is advertising HTTP/3 support via an alt-svc header.
By default the example configuration uses kernel UDP support, but for production performance use of
:ref:BPF <arch_overview_http3_downstream_bpf> is strongly advised if Envoy is running with multiple worker threads.
.. _arch_overview_http3_downstream_advertisement:
HTTP/3 advertisement
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.
.. _arch_overview_http3_downstream_bpf:
BPF usage
~~~~~~~~~
Envoy will attempt 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 and BPF is unsupported on the platform, or is attempted and fails,
Envoy will log a warning on start-up.
.. _arch_overview_http3_downstream_stats:
Downstream stats
~~~~~~~~~~~~~~~~
It is recommanded to monitor some UDP listener and QUIC connection stats:
:ref:`UDP listener downstream_rx_datagram_dropped <config_listener_stats_udp>`
Non-zero means kernel's UDP listen socket's receive buffer isn't large enough. In Linux,
it can be configured via listener :ref:`socket_options <envoy_v3_api_field_config.listener.v3.Listener.socket_options>`
by setting prebinding socket option ``SO_RCVBUF`` at ``SOL_SOCKET`` level.
:repo:`QUIC connection error codes and stream reset error codes <config_http_conn_man_stats_per_listener_http3>`
Refer to `quic_error_codes.h <https://github.com/google/quiche/blob/main/quiche/quic/core/quic_error_codes.h>`_
for the meaning of each error code.
.. _arch_overview_http3_upstream:
HTTP/3 upstream
---------------
HTTP/3 upstream support is implemented, with support both for explicit HTTP/3 (for data center use) and
automatic HTTP/3 (for internet use).
If you are in a controlled environment where UDP is unlikely to be blocked, you can configure it as the
explicit protocol in :ref:`http_protocol_options <envoy_v3_api_msg_extensions.upstreams.http.v3.HttpProtocolOptions>`.
For internet use, configuring :ref:`auto_config <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.auto_config>`
with :ref:`http3_protocol_options <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig.http3_protocol_options>`
will result in Envoy attempting to use HTTP/3 for endpoints which have explicitly advertised HTTP/3 support
via an ``alt-svc`` header.
When using :ref:`auto_config <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.auto_config>`
with :ref:`http3_protocol_options <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig.http3_protocol_options>`,
Envoy will attempt to create a QUIC connection, then if the QUIC handshake is not complete after a short delay,
will kick off a TCP connection, and will use whichever is established first.
.. tip::
See :ref:`here <arch_overview_http3_pooling_upstream>` 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 </configs/google_com_http3_upstream_proxy.yaml>`.