docs: unhiding HTTP/3 and adding docs #15926

alyssawilk · 2021-04-12T16:10:25Z

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>

repokitteh-read-only · 2021-04-12T16:10:33Z

CC @envoyproxy/api-shepherds: Your approval is needed for changes made to api/envoy/.
envoyproxy/api-shepherds assignee is @mattklein123
CC @envoyproxy/api-watchers: FYI only for changes made to api/envoy/.

🐱

Caused by: #15926 was opened by alyssawilk.

see: more, trace.

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

mattklein123 · 2021-04-12T18:26:12Z

Thanks in general this looks amazing! So excited to see this land, especially with example configs and maybe even a sandbox? (cc @moderation @phlax)

api/envoy/config/listener/v3/udp_listener_config.proto

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

danzh2010

Wow, that's a lot of text! Thanks for drafting it!

danzh2010 · 2021-04-12T21:14:05Z

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``


HTTP/3 does not support the HTTP Upgrade mechanism https://tools.ietf.org/id/draft-ietf-quic-http-23.html#http-upgrade

Yeah, maybe we need better phrasing here overall, but basically you use Upgrade for http/1 and CONNECT for H2 and H2 (as soon as david adds support)

phlax · 2021-04-13T11:18:19Z

docs build is here https://storage.googleapis.com/envoy-pr/15926/docs/index.html

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

repokitteh-read-only · 2021-04-29T15:38:33Z

CC @envoyproxy/api-shepherds: Your approval is needed for changes made to (api/envoy[\w/]*/(v1alpha\d?|v1|v2alpha\d?|v2))|(api/envoy/type/(matcher/)?\w+.proto).

🐱

Caused by: #15926 was synchronize by alyssawilk.

see: more, trace.

alyssawilk · 2021-04-29T15:38:55Z

oops, pushed early, /wait

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

RyanTheOptimist

Wow, this is fantastic! Thanks for writing all this up. One or two questions but mostly some minor nits.

RyanTheOptimist · 2021-04-29T17:25:54Z

api/envoy/config/listener/v3/udp_listener_config.proto

+  //   QUIC support is currently alpha and should be used with caution.
+  //
+  //   For known outstanding issues before Envoy QUIC support is GA, you can
+  //   track https://github.com/envoyproxy/envoy/labels/quic-mvp for example


I think that "For example" is the start of a new sentence? If so, perhaps a period and then Capitalize "for". If it's not the start of a new sentence, perhaps it can be rephrased for clarity?

RyanTheOptimist · 2021-04-29T17:28:38Z

api/envoy/config/listener/v3/udp_listener_config.proto

+  //
+  //   For known outstanding issues before Envoy QUIC support is GA, you can
+  //   track https://github.com/envoyproxy/envoy/labels/quic-mvp for example
+  //   QUIC does not currently support in place filter chain updates, so users


nit: I feel like 'in-place' is how I am accustomed to seeing this phrase in the context of software. (As opposed to, say, "having everything in place"). Maybe? WDYT?

RyanTheOptimist · 2021-04-29T17:28:57Z

api/envoy/config/listener/v3/udp_listener_config.proto

+  //   requiring dynamic config reload for QUIC should wait until
+  //   https://github.com/envoyproxy/envoy/issues/13115 has been addressed.
+  //
+  //   For general feature requets beyond production readiness, you can track


nit: "requets" => "requests"

RyanTheOptimist · 2021-04-29T17:32:12Z

api/envoy/extensions/upstreams/http/v3/http_protocol_options.proto

-    // 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 will eventually rely on server-side alt-svc advertisement to try HTTP/3.


For Alt-Svc, I'd be inclined to say "HTTP Alternative Services" and I might also reference the spec https://tools.ietf.org/html/rfc7838

Is it worth mention the HTTPS DNS RR here as well, since we intend to implement this? (and the spec https://datatracker.ietf.org/doc/html/draft-ietf-dnsop-svcb-https-04)

RyanTheOptimist · 2021-04-29T17:38:06Z

api/envoy/extensions/upstreams/http/v3/http_protocol_options.proto

-    // 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 will eventually rely on server-side alt-svc advertisement to try HTTP/3.
+    // If HTTP/3 is configured via HTTP/3, and if the HTTP/3 connection fails (currently controlled by a


nit: I wonder if we can improve on the phrase "If HTTP/3 is configured via HTTP/3". How bout something like:

When HTTP/3 is configured, HTTP/3 connections will be attempted. However, the connection may fail over to TCP (HTTP/1 or HTTP/2 based on ALPN) instead. If the HTTP/3 connection fails explicitly because of a protocol error, a TCP connection will be attempted instead. In addition, if the HTTP/3 connection has not succeeded after a (currently) fixed timeout, a TCP connection will be started in a parallel. The connection the succeeds first will be used.

Actually, having written all that... I think that's only true when H1, H2 and H3 are all enabled. If only H3 is enabled then there's no fallback and not alt-svc checking, right? Should we mention this? (Wow this gets complex in a hurry!)

Ah, for auto, remember that H2 and H1 are on by default, so you can't not configure it.

RyanTheOptimist · 2021-04-29T17:47:18Z

docs/root/intro/arch_overview/http/http3.rst

+HTTP3 upstream
+===============
+
+HTTP/3 downstream support is still in Alpha, and should be used with caution.


nit: "downstream" => "upstream"

RyanTheOptimist · 2021-04-29T17:47:50Z

docs/root/intro/arch_overview/http/http3.rst

+See example :repo:`downstream HTTP/3 configuration </configs/envoyproxy_io_proxy_http3_downstream.template.yaml1>` 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 alt-svc header. Advertising HTTP/3 is not necessary for


nit: "via alt-svc header" => "via an alt-svc header"

RyanTheOptimist · 2021-04-29T17:50:32Z

docs/root/intro/arch_overview/http/http_connection_management.rst

-Envoy’s HTTP connection manager has native support for HTTP/1.1, WebSockets, and HTTP/2. It does not support
-SPDY. Envoy’s HTTP support was designed to first and foremost be an HTTP/2 multiplexing proxy.
+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.


I think it's fine to keep this as "HTTP/2" since when Envoy was designed HTTP/3 was not yet a thing. Your call though.

RyanTheOptimist · 2021-04-29T17:52:23Z

docs/root/intro/arch_overview/upstream/connection_pooling.rst

+.. _arch_overview_http3_upstream:
+
+If HTTP/3 is configured in the automatic pool, it will currently attempt an QUIC connection first,
+then 300ms later, attempt a TCP connection. Whichever handshake succeeds will be used for the initial


Maybe this doesn't need to be mentioned, but TCP is only attempted after the timeout if the QUIC connection has not already succeeded, right?

RyanTheOptimist · 2021-04-29T17:52:46Z

docs/root/intro/arch_overview/upstream/connection_pooling.rst

+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 server advertises support
+via alt-svc headers, and "QUIC hints" where attempting QUIC but failing over can be hard-coded. This code


Should we mention the HTTPS DNS RR?

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

alyssawilk · 2021-04-29T19:30:36Z

I moved most of the details to the docs, where they'd been half in docs and half in APIs.
still torn about having upstream H3 details in the connection pool doc or the H3 doc - thoughts appreciated!

alyssawilk · 2021-05-03T14:09:33Z

cc @moderation if you have any tips on how I can make docs more clear now that you've played around, please add suggestions here!

RyanTheOptimist · 2021-05-03T17:08:37Z

docs/root/intro/arch_overview/upstream/connection_pooling.rst

-optimal latency for internet environments, so please be patient and follow along with Envoy release notes
+Upcoming versions of HTTP/3 support will include only selecting HTTP/3 if the upstream advertises support
+either via `HTTP Alternative Services <https://tools.ietf.org/html/rfc7838>`_,
+`HTTPS DNS RR <https://datatracker.ietf.org/doc/html/draft-ietf-dnsop-svcb-https-04>`_, "QUIC hints" which


nit: "or" before QUIC hints, I think

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

phlax

@alyssawilk looks good generally

ive left a few nits inline - quite a few are backticks - some i think are probably more important than others, but feel free to ignore some

api/envoy/config/core/v3/protocol.proto

api/envoy/extensions/upstreams/http/v3/http_protocol_options.proto

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

phlax · 2021-05-05T18:00:28Z

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 *http2* if configured in `HttpProtocolOptions <envoy_v3_msg_config.upstreams.http.v3.HttpProtocolOptions>`.


this one also i think should be double-backtick

docs/root/faq/configuration/timeouts.rst

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

docs/root/intro/arch_overview/http/http3.rst

docs/root/intro/deployment_types/service_to_service.rst

phlax · 2021-05-05T18:08:42Z

tools/spelling/spelling_dictionary.txt

@@ -1134,6 +1134,7 @@ subtypes
 subzone
 superclass
 superset
+svc


probs dont needs this ifwe make use inline literal for alt-svc

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

adisuissa · 2021-05-06T03:10:51Z

/lgtm api

Adding an informative log since I ended up confused when trying to sort out envoyproxy#15845 and needed to fix envoyproxy#15926 accordingly. Risk Level: n/a (adding info log) Testing: manual Signed-off-by: Alyssa Wilk <alyssar@chromium.org> Signed-off-by: Gokul Nair <gnair@twitter.com>

alyssawilk · 2021-05-06T12:18:09Z

@RyanTheOptimist / @phlax I miss anything / any other requests, or is this good to go once #16320 lands?

phlax · 2021-05-06T12:28:42Z

docs/root/intro/arch_overview/http/http3.rst

@@ -1,7 +1,10 @@
 .. _arch_overview_http3:

+HTTP3 overview
+==============
+


whatever we keep in the api docs - i think a warning is warranted here too

configs/envoyproxy_io_proxy_http3_downstream.template.yaml

phlax · 2021-05-06T12:56:28Z

docs/root/intro/arch_overview/http/http3.rst

+See example :repo:`downstream HTTP/3 configuration </configs/envoyproxy_io_proxy_http3_downstream.template.yaml1>` 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


i think the backticks should just be around alt-svc as that is the literal part - my rule of thumb ~is "should it be translated" if we were translating the docs

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

configs/envoyproxy_io_proxy_http3_downstream.yaml

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

danzh2010 · 2021-05-06T16:10:48Z

docs/root/intro/arch_overview/http/http3.rst

+By default the example configuration uses kernel UDP support, but for production performance on Linux, use of
+BPF is strongly advised if Envoy is running with multiple worker threads. Envoy will attepmt to
+use BPF 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). Envoy will log a warning on start-up if BPF is attempted and fails.


Maybe also worth to mention that if BPF is not supported by the platform and multiple worker threads are configured, Envoy will route packets across workers by itself and log a warning of performance degrading, or something similar.

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

RyanTheOptimist

Hm. I could have sworn I approved several days ago, but github disagrees. LGTM

phlax

lgtm, thanks @alyssawilk

danzh2010 · 2021-05-06T20:47:25Z

docs/root/intro/arch_overview/http/http3.rst

+
+Downstream Envoy HTTP/3 support can be turned up via adding
+:ref:`quic_options <envoy_v3_api_field_config.listener.v3.UdpListenerConfig.quic_options>` and
+ensuring the downstream transport socket is a QuicDownstreamTransport.


The HCM config needs to specify codec type to be Http3 as well.

Yeah, at the point you configure a listener, the rest should be auto-validated also shown by the sample config.
happy to add the detail in a follow-up but I think i'm going to land this version today :-)

adisuissa · 2021-05-07T12:01:32Z

/lgtm api

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

docs: unhiding HTTP/3 and adding docs

4f190b3

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

alyssawilk assigned mattklein123 and danzh2010 Apr 12, 2021

repokitteh-read-only bot added the api label Apr 12, 2021

alyssawilk added 2 commits April 12, 2021 12:45

spacing

bb5e934

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

format, proto, format, proto, format?

28a6ea6

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

phlax reviewed Apr 12, 2021

View reviewed changes

api/envoy/config/listener/v3/udp_listener_config.proto Outdated Show resolved Hide resolved

docs build?

f20546f

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

danzh2010 reviewed Apr 12, 2021

View reviewed changes

alyssawilk added the no stalebot Disables stalebot from closing an issue label Apr 15, 2021

mattklein123 added the waiting label Apr 16, 2021

alyssawilk mentioned this pull request Apr 26, 2021

grid: Add a new class for tracking HTTP/3 status #16067

Merged

alyssawilk added 2 commits April 29, 2021 10:31

Merge branch 'main' into h3_docs

5257f2f

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

more detail

0bad720

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

repokitteh-read-only bot added v2-freeze and removed waiting labels Apr 29, 2021

configs

8ccb35a

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

alyssawilk assigned RyanTheOptimist Apr 29, 2021

alyssawilk marked this pull request as ready for review April 29, 2021 15:52

format

1702e4c

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

RyanTheOptimist reviewed Apr 29, 2021

View reviewed changes

comments

7c9c5fa

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

RyanTheOptimist reviewed May 3, 2021

View reviewed changes

alyssawilk added 3 commits May 5, 2021 10:28

fix links

58aa631

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

docs fix

d2ad3ab

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

format

aa1f4ef

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

phlax requested changes May 5, 2021

View reviewed changes

alyssawilk added 2 commits May 5, 2021 14:33

comments

4fa9c31

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

Merge branch 'main' into h3_docs

323f151

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

repokitteh-read-only bot removed the api label May 6, 2021

phlax reviewed May 6, 2021

View reviewed changes

configs/envoyproxy_io_proxy_http3_downstream.template.yaml Show resolved Hide resolved

phlax reviewed May 6, 2021

View reviewed changes

alyssawilk added 2 commits May 6, 2021 09:14

Merge branch 'main' into h3_docs

56e08a6

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

comments

bdb245f

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

repokitteh-read-only bot added the api label May 6, 2021

phlax reviewed May 6, 2021

View reviewed changes

configs/envoyproxy_io_proxy_http3_downstream.yaml Outdated Show resolved Hide resolved

config cleanup

752afc7

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

danzh2010 reviewed May 6, 2021

View reviewed changes

bpf

e2ee7a9

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

RyanTheOptimist approved these changes May 6, 2021

View reviewed changes

phlax approved these changes May 6, 2021

View reviewed changes

danzh2010 reviewed May 6, 2021

View reviewed changes

repokitteh-read-only bot removed the api label May 7, 2021

alyssawilk merged commit 73ade9a into envoyproxy:main May 7, 2021

alyssawilk added a commit to alyssawilk/envoy that referenced this pull request May 10, 2021

docs: follow up to envoyproxy#15926

a38c844

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

alyssawilk added a commit that referenced this pull request May 12, 2021

docs: follow up to #15926 (#16421)

06c8d41

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

alyssawilk deleted the h3_docs branch August 18, 2021 13:59

docs: unhiding HTTP/3 and adding docs #15926

docs: unhiding HTTP/3 and adding docs #15926

Conversation

alyssawilk commented Apr 12, 2021 • edited Loading

repokitteh-read-only bot commented Apr 12, 2021

mattklein123 commented Apr 12, 2021

danzh2010 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

phlax commented Apr 13, 2021

repokitteh-read-only bot commented Apr 29, 2021

alyssawilk commented Apr 29, 2021

RyanTheOptimist left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alyssawilk commented Apr 29, 2021

alyssawilk commented May 3, 2021

Choose a reason for hiding this comment

phlax left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adisuissa commented May 6, 2021

alyssawilk commented May 6, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

RyanTheOptimist left a comment

Choose a reason for hiding this comment

phlax left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adisuissa commented May 7, 2021

alyssawilk commented Apr 12, 2021 •

edited

Loading