Configure downstream HTTP/3

HTTP/3 is the latest version of HTTP and runs over QUIC (UDP). Compared to HTTP/2, it reduces connection setup time and avoids transport-level head-of-line blocking, which improves performance on lossy networks like mobile and Wi-Fi. This chapter explains how to enable HTTP/3 in real-world deployments.

Prerequisites

HTTP/3 requires TLS 1.3
Ensure your Gateway negotiates TLS 1.3, otherwise clients will fall back to HTTP/2 or HTTP/1.1. You can also enforce TLS 1.3 on the Gateway by disallowing earlier TLS versions. In that case, only clients that support TLS 1.3 will be able to connect.
TLS certificates issued by a public CA
Most modern browsers support HTTP/3. They use the alt-svc response header to discover whether a site is available over HTTP/3. However, this mechanism only works if the server certificate of that website is signed by a certificate authority (CA) that is trusted by the browser's built-in trust store. If the certificate is self-signed or issued by a private CA, browsers refuse to use HTTP/3, even if you manually import the CA into the browser's trust store. To avoid these issues, use a certificate issued by a publicly trusted CA such as Let’s Encrypt. See Configuring the HTTP-01 Gateway API solver for details.
Notice
What doesn't work
- Self-signed TLS certificates
- TLS certificates issued by a private CA (even if the CA certificate is imported into the browser trust store)

Configuration

Configure the Gateway

To enable HTTP/3 for downstream connections, set listeners.protocol to microgateway.airlock.com/http3. HTTP/3 requires TLS 1.3, so you must configure listeners.tls with a valid and publicly signed certificate. To offer HTTP/3 as an opt-in for clients that support TLS 1.3 and HTTP/3, you can allow older TLS versions in the listeners.tls.options settings (like in the example below). In that case, clients that do not support TLS 1.3 will fall back to HTTP/2 or HTTP/1.1.

Example

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gateway-example
  namespace: example-backend-gw
spec:
  gatewayClassName: airlock-microgateway
  listeners:
    - name: http
      hostname: "*.example.com"       
      port: 80
      protocol: HTTP
    - name: https
      hostname: "*.example.com"   
      port: 443
      protocol: microgateway.airlock.com/http3
      tls:
        mode: Terminate
        certificateRefs:
          - name: downstream-server-certificate
        options:  
          microgateway.airlock.com/minimumVersion: TLSv1_2 
          microgateway.airlock.com/maximumVersion: TLSv1_3

For North-South traffic

To use HTTP/3 from outside the cluster you can use a Service of type LoadBalancer. Some cloud providers do not support mixed protocols (UDP and TCP) on the same Service. Depending on the cloud provider you must therefore manually create two Services of type LoadBalancer to expose the Airlock Microgateway as Ingress with HTTP/3 support. In the example below we create two Services, one for TCP and one for UDP.

Example

apiVersion: v1
kind: Service
metadata:
  name: gateway-example-tcp
  namespace: example-backend-gw
spec:
  type: LoadBalancer
  ports:
    - appProtocol: http
      name: http
      port: 80
      protocol: TCP
      targetPort: 10080
    - appProtocol: https
      name: https
      port: 443
      protocol: TCP
      targetPort: 10443
  selector:
    gateway.networking.k8s.io/gateway-name: gateway-example
  externalTrafficPolicy: Local
---
apiVersion: v1
kind: Service
metadata:
  name: gateway-example-udp
  namespace: example-backend-gw
spec:
  type: LoadBalancer
  ports:
    - appProtocol: https
      name: https
      port: 443
      protocol: UDP
      targetPort: 10443
  selector:
    gateway.networking.k8s.io/gateway-name: gateway-example
  externalTrafficPolicy: Local

Notice

Cloud provider–specific annotations and configuration are omitted in this example. Refer to your cloud provider’s documentation to configure the Service appropriately for your environment.

Explanation

The selector uses the label gateway.networking.k8s.io/gateway-name which is automatically added with the name of the Gateway CR to the Deployment and Service of the Airlock Microgateway.

We set externalTrafficPolicy to Local to preserve the source IP address. Local will leave the routing decision/load balancing to the load balancer.

Some load balancers like Google Cloud's External Load Balancer may need sessionAffinity: ClientIP depending on the load balancer settings to track QUIC (HTTP/3) connections correctly. Please refer to your load balancers documentation to check if this is needed.

For East-West traffic

Since Kubernetes supports mixed-protocol Services, the default Service created for Microgateway already works for east-west traffic. Therefore, no Service-specific configuration is required (only the Gateway configuration mentioned above).

Limitations

Please note that HTTP/3 is supported for downstream connections only, and the following limitations apply to the current implementation.

QUIC connection migration.
Exposing Microgateway with a Service of type nodePort will break the advertisement of HTTP/3 via the alt-svc header because the port announced in the header may not match the assigned nodePort.