5 min • read

HTTP/3 in Emissary-ingress

HTTP/3 is the third version of the Hypertext Transfer Protocol (HTTP). It is built on the QUIC network protocol rather than Transmission Control Protocol (TCP) like previous versions.

The changes and challenges of HTTP/3

Since the QUIC network protocol is built on UDP, most clients will require Emissary-ingress to advertise its support for HTTP/3 using the alt-svc response header. This header is added to the response of the HTTP/2 and HTTP/1.1 connections. When the client sees the alt-svc it can choose to upgrade to HTTP/3 and connect to Emissary-ingress using the QUIC protocol.

QUIC requires Transport Layer Security (TLS) version 1.3 to communicate. Otherwise, Emissary-ingress will fall back to HTTP/2 or HTTP/1.1, both of which support other TLS versions if client does not support TLS v1.3. Due to this restriction, some clients also require valid certificatesand will not upgrade to HTTP/3 traffic with self-signed certificates.

Because HTTP/3 adoption is still growing and and changing, the Emissary-ingress team will continue update this documentation as features change and mature.

Setting up HTTP/3 with Emissary-ingress

To configure Emissary-ingress for HTTP/3 you need to do the following:

  1. Configure Listener resources.
  2. Configure a Host.
  3. Have a valid certificate.
  4. Setup an external load balancer.

Configuring the Listener resources

To make Emissary-ingress listen for HTTP/3 connections over the QUIC network protocol, you need to configure a Listener with TLS, HTTP, and UDP configured within protocolStack.

The Listener configured for HTTP/3 can be bound to the same address and port (0.0.0.0:8443) as the Listener that supports HTTP/2 and HTTP/1.1. This is not required, but it allows Emissary-ingress to inject the default alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400 header into the responses returned over the TCP connection with no additional configuration needed. Most clients such as browsers require the alt-svc header to upgrade to HTTP/3.

Configuring the Host resource

Because the QUIC network requires TLS, the certificate needs to be valid so the client can upgrade a connection to HTTP/3. See the Host documentation for more information on how to configure TLS for a Host.

Certificate verification

Clients can only upgrade to an HTTP/3 connection with a valid certificate. If the client won’t upgrade to HTTP/3, verify that you have a valid TLS certificate and that your client can speak TLS v1.3. Your Host resource should be configured similar to the following:

External load balancers

The two most common service types to expose traffic outside of a Kubernetes cluster are:

  • LoadBalancer: A load balancer controller generates and manages the cloud provider-specific external load balancer.
  • NodePort: The platform administrator has to manually set up things like the external load balancer, firewall rules, and health checks.

LoadBalancer setup

The ideal setup would be to configure a single service of type LoadBalancer, but this comes with some current restrictions:

  • You need version 1.24 or later of Kubernetes with the MixedProtocolLBService feature enabled.
  • Your cloud service provider needs to support the creation of an external load balancer with mixed protocol types (TCP/UDP), port reuse, and port forwarding. Support for Kubernetes feature flags may vary between cloud service providers. Refer to your provider’s documentation to see if they support this scenario.

An example LoadBalancer configuration that fits the criteria listed above:

Cloud service provider setup

Once you've completed the steps above, you need to configure HTTP/3 support through your cloud service provider. The configuration processes for each provider can be found here: