Configure a QUIC listener for an ALB Ingress to support HTTP/3 - Container Service for Kubernetes

For unstable networks (such as mobile networks) or latency-sensitive applications (such as online games and streaming), add a QUIC listener to your Application Load Balancer (ALB) Ingress to enable HTTP/3 support and reduce communication overhead.

How it works

QUIC is a UDP-based transport protocol and the foundation of HTTP/3. Compared to HTTP/2, which runs TLS over TCP, QUIC reduces latency and packet retransmissions through multiplexing, 0-RTT handshakes, efficient congestion control, and seamless connection migration. For details, see the QUIC specification (RFC 9000).

You can deploy a QUIC listener in two modes:

Mode	Protocol support	When to use
QUIC + HTTPS	HTTP/1.1, HTTP/2, HTTP/3	Some clients do not support HTTP/3
QUIC only	HTTP/3 only	All clients support HTTP/3

QUIC + HTTPS mode: Both listeners monitor port 443 and share the same forwarding rules. When a request arrives, ALB checks whether the client supports HTTP/3. If it does, the QUIC listener handles the request. If not, the HTTPS listener handles it. This is why both listeners must exist: the HTTPS listener provides the fallback path for clients that cannot negotiate HTTP/3.

Use a QUIC listener with an HTTPS listener

Prerequisites

Before you begin, make sure that you have:

An HTTPS certificate configured. For more information, see Configure an HTTPS certificate for encrypted communication.
kubectl connected to the cluster. For more information, see Obtain the kubeconfig file of a cluster and use kubectl to connect to the cluster.

Step 1: Create a QUIC listener in the AlbConfig

Edit the AlbConfig:
```
kubectl edit albconfig <ALBCONFIG_NAME>
```

Add a QUIC listener entry and a quicConfig block to the HTTPS listener. Both listeners must use the same certificate. This lets the client verify the same server identity when it upgrades from HTTPS to HTTP/3.

Important

The example above specifies a certificate directly in the AlbConfig. QUIC listeners also support auto-discovered certificates and Secret certificates. For more information, see Configure an HTTPS certificate for encrypted communication.

Field	Description	Initial value
`quicListenerId`	The ID of the QUIC listener to associate with this HTTPS listener.	`""` (set in Step 3)
`quicUpgradeEnabled`	Whether ALB routes HTTP/3-capable clients to the QUIC listener.	`false` (set to `true` in Step 3)

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: #...
spec:
  config:
    #...
  listeners:
    - port: 443
      protocol: HTTPS
      certificates:
      - CertificateId: 756****-cn-hangzhou # CertIdentifier of the certificate
        IsDefault: true
      quicConfig:
        quicListenerId: ""    # Leave blank for now. Set this in Step 3.
        quicUpgradeEnabled: false # Set to true after the listeners are associated.
    - port: 443
      protocol: QUIC
      certificates:
      - CertificateId: 756****-cn-hangzhou # Same certificate as the HTTPS listener.
        IsDefault: true

The quicConfig fields on the HTTPS listener control the association:

Step 2: Add an annotation to the Ingress

Add an annotation to make the Ingress apply to both listeners.

Edit the Ingress:
```
kubectl edit ingress <INGRESS_NAME>
```

Add the following annotation:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: #...
  annotations:
    alb.ingress.kubernetes.io/listen-ports: '[{"QUIC": 443},{"HTTPS": 443}]'
spec:
  #...

Step 3: Associate the listeners

After ALB creates the QUIC listener, link it to the HTTPS listener so ALB knows to route HTTP/3-capable clients to QUIC.

Log on to the ALB console.
On the Instances page, click the ID of the target ALB instance. On the Listener tab, find the listener with Listener Protocol/Port set to QUIC:443 and record its ID.

Update the AlbConfig with the QUIC listener ID:

Edit the AlbConfig:
```
kubectl edit albconfig <ALBCONFIG_NAME>
```

Set quicListenerId to the ID from the previous step and set quicUpgradeEnabled to true:

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: #...
spec:
  config:
    #...
  listeners:
    - port: 443
      protocol: HTTPS
      certificates:
      - CertificateId: 756****-cn-hangzhou
        IsDefault: true
      quicConfig:
        quicListenerId: lsn-tnz740dr8p5h65**** # The QUIC listener ID.
        quicUpgradeEnabled: true
    - port: 443
      protocol: QUIC
      certificates:
      - CertificateId: 756****-cn-hangzhou
        IsDefault: true

Confirm the association in the console: on the Instances page, click the target instance ID, then click the Listeners tab. Click the HTTPS listener name and check the Listener Details tab to see the associated QUIC listener.

Step 4: Verify the configuration

Get the Ingress hostname and ALB address:

kubectl get ingress

Expected output:

NAME            CLASS                HOSTS                  ADDRESS                         PORTS     AGE
https-ingress   https-ingressclass   demo.alb.ingress.top   alb-********.alb.aliyuncs.com   80, 443   83m

Note the values in the HOSTS and ADDRESS columns.

Send test requests over HTTP/3 and HTTPS, replacing demo.alb.ingress.top and alb-********.alb.aliyuncs.com with the values from the previous step:

Some curl builds do not support HTTP/3. Make sure your curl version supports the --http3 flag.
```
curl --http3 -H HOST:demo.alb.ingress.top -k https://alb-********.alb.aliyuncs.com
curl -H HOST:demo.alb.ingress.top -k https://alb-********.alb.aliyuncs.com
```
If both commands return old, the listeners are associated and serving both HTTP/3 and HTTPS traffic.

(Optional) Step 5: Dissociate the listeners

Edit the AlbConfig:
```
kubectl edit albconfig <ALBCONFIG_NAME>
```

Clear quicListenerId and set quicUpgradeEnabled to false:

# ... (Omitted)
    port: 443
    protocol: HTTPS
    quicConfig:
      quicListenerId: ""
      quicUpgradeEnabled: false
    requestTimeout: 0
# ... (Omitted)

Use a QUIC listener alone

Use this mode when all clients support HTTP/3. The QUIC listener does not fall back to HTTP/2 or HTTP/1.1.

Prerequisites

Before you begin, make sure that you have:

An AlbConfig resource created. For more information, see Use an ALB Ingress to expose a service.
kubectl connected to the cluster. For more information, see Obtain the kubeconfig file of a cluster and use kubectl to connect to the cluster.

Step 1: Create a QUIC listener in the AlbConfig

Edit the AlbConfig:
```
kubectl edit albconfig <ALBCONFIG_NAME>
```

Add a QUIC listener:

Important

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: #...
spec:
  config:
    #...
  listeners:
    - port: 443
      protocol: QUIC
      certificates:
      - CertificateId: 756****-cn-hangzhou # CertIdentifier of the certificate
        IsDefault: true

Step 2: Create sample resources

Create a file named https-quickstart.yaml with the following content:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: https-ingressclass
spec:
  controller: ingress.k8s.alibabacloud/alb
  parameters:
    apiGroup: alibabacloud.com
    kind: AlbConfig
    name: alb # Replace with the name of your AlbConfig resource.
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: https-ingress
spec:
  ingressClassName: https-ingressclass
  rules:
  - host: demo.alb.ingress.top # Replace with the domain name associated with your certificate.
    http:
      paths:
      - backend:
          service:
            name: https-svc
            port:
              number: 443
        path: /
        pathType: Prefix
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: https-deploy
spec:
  replicas: 1
  selector:
    matchLabels:
      app: https-deploy
  template:
    metadata:
      labels:
        app: https-deploy
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/acs-sample/old-nginx:latest
          imagePullPolicy: IfNotPresent
          name: https-deploy
          ports:
            - containerPort: 80
              protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
  name: https-svc
spec:
  ports:
    - name: port1
      port: 443
      protocol: TCP
      targetPort: 80
  selector:
    app: https-deploy
  sessionAffinity: None
  type: ClusterIP

Apply the resources:
```
kubectl apply -f https-quickstart.yaml
```

Step 3: Add an annotation to the Ingress

Edit the Ingress:
```
kubectl edit ingress https-ingress
```

Add the following annotation to route traffic through the QUIC listener:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: #...
  annotations:
    alb.ingress.kubernetes.io/listen-ports: '[{"QUIC": 443}]'
spec:
  #...

Step 4: Verify the configuration

Get the Ingress hostname and ALB address:

kubectl get ingress

Expected output:

NAME            CLASS                HOSTS                  ADDRESS                         PORTS     AGE
https-ingress   https-ingressclass   demo.alb.ingress.top   alb-********.alb.aliyuncs.com   80, 443   83m

Send a test request over HTTP/3, replacing demo.alb.ingress.top and alb-********.alb.aliyuncs.com with the values from the previous step:

Some curl builds do not support HTTP/3. Make sure your curl version supports the --http3 flag.
```
curl --http3 -H HOST:demo.alb.ingress.top -k https://alb-********.alb.aliyuncs.com
```
If the command returns old, the QUIC listener is configured successfully.

What's next

To protect your service against web attacks, use an enhanced edition of an ALB Web Application Firewall (WAF) instance. For more information, see Use an enhanced edition of an ALB WAF instance to protect services.
For additional listener configurations, see Configure an ALB listener using an AlbConfig.