Configure upstream HTTP/2 through Service appProtocol

Learn how to configure NGINX Gateway Fabric to use HTTP/2 when proxying requests to upstream services using the Service port’s appProtocol field.

Overview

The appProtocol field on a Kubernetes Service port provides a way to specify an application protocol. Controllers such as NGINX Gateway Fabric may use this field to enable protocol-specific functionality for supported protocols. For more information, view the official Kubernetes Service Documentation.

When a Kubernetes Service port has appProtocol set to kubernetes.io/h2c, NGINX Gateway Fabric configures the corresponding NGINX location to use HTTP/2 for upstream connections by setting the proxy_http_version directive to 2 in the NGINX configuration.

Important Notes

• kubernetes.io/h2c is supported on HTTPRoutes and GRPCRoutes. It isn’t supported on TLSRoutes.
• When NGINX Gateway Fabric detects kubernetes.io/h2c, it also omits the proxy_set_header Upgrade and proxy_set_header Connection directives from the location block, because those headers are HTTP/1.1-specific and aren’t used in HTTP/2 connections.

Other supported appProtocols

In addition to the kubernetes.io/h2c appProtocol, NGINX Gateway Fabric recognizes kubernetes.io/ws and kubernetes.io/wss as described in RFC 6455.

These appProtocols reference WebSocket over cleartext and WebSocket over TLS respectively and are supported natively by our default NGINX configuration. kubernetes.io/ws is only supported on HTTPRoutes and kubernetes.io/wss is only supported on TLSRoutes or on HTTPRoutes with an associated BackendTLSPolicy.

If an appProtocol on a Service port is referenced by an unsupported Route type, that backendRef will be considered invalid and status will be written to the Route.

NGINX Gateway Fabric is conformant to the information in GEP-1911, which should be referenced for more detailed information.

Troubleshooting

• For NGINX to set proxy_http_version 2 for a location, all valid backend references in the routing rule must have appProtocol: kubernetes.io/h2c set on their Service ports. If any valid backend doesn’t use kubernetes.io/h2c, NGINX falls back to the default HTTP/1.1.

See also

• Backend Protocol: the Gateway API guide for the appProtocol field.
• GEP-1911: for more details on how NGINX Gateway Fabric interacts with appProtocols.
• proxy_http_version NGINX directive.