From 485b9ea6f0f01e0d0664a1cfd6e06bd677768b5c Mon Sep 17 00:00:00 2001 From: Ben Jee Date: Tue, 2 Jun 2026 22:46:38 -0700 Subject: [PATCH 1/5] Add document for upstream http2 --- .../upstream-http2-appprotocol.md | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 content/ngf/traffic-management/upstream-http2-appprotocol.md diff --git a/content/ngf/traffic-management/upstream-http2-appprotocol.md b/content/ngf/traffic-management/upstream-http2-appprotocol.md new file mode 100644 index 0000000000..6ba63fa657 --- /dev/null +++ b/content/ngf/traffic-management/upstream-http2-appprotocol.md @@ -0,0 +1,196 @@ +--- +title: Configure upstream HTTP/2 through Service appProtocol +toc: true +weight: 1600 +f5-content-type: how-to +f5-product: FABRIC +f5-docs: DOCS-0000 +description: Configure NGINX Gateway Fabric to use HTTP/2 for upstream connections by setting appProtocol to kubernetes.io/h2c on a Kubernetes Service port. +f5-keywords: NGINX Gateway Fabric, HTTP/2, upstream HTTP/2, appProtocol, kubernetes.io/h2c, proxy_http_version, h2c, upstream connections, Service appProtocol, Gateway API, HTTPRoute, GRPCRoute +f5-summary: This guide shows you how to configure NGINX Gateway Fabric to proxy requests to upstream services over HTTP/2 by setting appProtocol to kubernetes.io/h2c on a Kubernetes Service port. Using HTTP/2 for upstream connections enables multiplexing and reduces latency for services that support it. This guide is for operators and developers who have NGINX Gateway Fabric installed and are familiar with Kubernetes Services and the Gateway API. +--- + +Learn how to configure NGINX Gateway Fabric to use HTTP/2 when proxying requests to upstream services using the Service `appProtocol`. + +## Overview + +The `appProtocol` field on a Kubernetes Service provides a way to specify an application protocol for each Service port. Implementations of a controller such as NGINX Gateway Fabric use this field to offer richer behavior for protocols that are understood. For more information, view the official [Kubernetes Service Documentation](https://kubernetes.io/docs/concepts/services-networking/service/#application-protocol). + +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`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_http_version) directive to `2` in the NGINX configuration. + +## Before you begin + +- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric. + +## Set up + +Create the **coffee** application in Kubernetes by copying and pasting the following block into your terminal: + +```yaml +kubectl apply -f - < 80/TCP 10s +``` + +## Create the Gateway API resources + +Create the **cafe** Gateway: + +```yaml +kubectl apply -f - < Date: Fri, 5 Jun 2026 21:21:31 -0700 Subject: [PATCH 2/5] Add note on hostile multi-tenant clusters --- content/ngf/reference/permissions.md | 6 ++++++ .../ngf/traffic-management/upstream-http2-appprotocol.md | 6 +++--- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/content/ngf/reference/permissions.md b/content/ngf/reference/permissions.md index e68bf333dd..df42085eb1 100644 --- a/content/ngf/reference/permissions.md +++ b/content/ngf/reference/permissions.md @@ -65,6 +65,12 @@ NGINX containers managed by the control plane. No RBAC permissions needed since - **EmptyDir**: Read-write (required for NGINX operation) - **Secret/ConfigMap/Projected**: Read-only +{{< call-out "note" >}} + +Kubernetes isn’t normally safe for hostile multi-tenant environments and NGINX is designed to treat upstreams as trusted. If you need a dataplane that doesn't treat all upstreams as trusted, you may want to explore alternative solutions. + +{{< /call-out >}} + ## Certificate Generator Kubernetes Job that creates initial TLS certificates. diff --git a/content/ngf/traffic-management/upstream-http2-appprotocol.md b/content/ngf/traffic-management/upstream-http2-appprotocol.md index 6ba63fa657..f452397f9f 100644 --- a/content/ngf/traffic-management/upstream-http2-appprotocol.md +++ b/content/ngf/traffic-management/upstream-http2-appprotocol.md @@ -10,11 +10,11 @@ f5-keywords: NGINX Gateway Fabric, HTTP/2, upstream HTTP/2, appProtocol, kuberne f5-summary: This guide shows you how to configure NGINX Gateway Fabric to proxy requests to upstream services over HTTP/2 by setting appProtocol to kubernetes.io/h2c on a Kubernetes Service port. Using HTTP/2 for upstream connections enables multiplexing and reduces latency for services that support it. This guide is for operators and developers who have NGINX Gateway Fabric installed and are familiar with Kubernetes Services and the Gateway API. --- -Learn how to configure NGINX Gateway Fabric to use HTTP/2 when proxying requests to upstream services using the 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 provides a way to specify an application protocol for each Service port. Implementations of a controller such as NGINX Gateway Fabric use this field to offer richer behavior for protocols that are understood. For more information, view the official [Kubernetes Service Documentation](https://kubernetes.io/docs/concepts/services-networking/service/#application-protocol). +The `appProtocol` field on a Kubernetes Service port provides a way to specify an application protocol. Implementations of a controller such as NGINX Gateway Fabric use this field to offer richer behavior for protocols that are understood. For more information, view the official [Kubernetes Service Documentation](https://kubernetes.io/docs/concepts/services-networking/service/#application-protocol). 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`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_http_version) directive to `2` in the NGINX configuration. @@ -185,7 +185,7 @@ In addition to the `kubernetes.io/h2c` `appProtocol`, NGINX Gateway Fabric recog 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 is referenced by an unsupported Route type, that backendRef will be considered invalid and status will be written to the Route. +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](https://gateway-api.sigs.k8s.io/geps/gep-1911/), which should be referenced for more detailed information. From 2c4885d5039214fd8e9147bf8b71031baf952933 Mon Sep 17 00:00:00 2001 From: Ben Jee Date: Fri, 5 Jun 2026 21:23:48 -0700 Subject: [PATCH 3/5] Adjust wording on callout note --- content/ngf/reference/permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ngf/reference/permissions.md b/content/ngf/reference/permissions.md index df42085eb1..797f0be95c 100644 --- a/content/ngf/reference/permissions.md +++ b/content/ngf/reference/permissions.md @@ -67,7 +67,7 @@ NGINX containers managed by the control plane. No RBAC permissions needed since {{< call-out "note" >}} -Kubernetes isn’t normally safe for hostile multi-tenant environments and NGINX is designed to treat upstreams as trusted. If you need a dataplane that doesn't treat all upstreams as trusted, you may want to explore alternative solutions. +Kubernetes is generally not recommended for hostile multi-tenant environments and NGINX is designed to treat upstreams as trusted. If you need a dataplane that doesn't treat upstreams as trusted, you may want to explore alternative solutions. {{< /call-out >}} From 87185c06a412a569d9ec002b0bdd9ddaa5dc455b Mon Sep 17 00:00:00 2001 From: Ben Jee Date: Tue, 30 Jun 2026 11:33:54 -0700 Subject: [PATCH 4/5] Add review feedback --- content/ngf/reference/permissions.md | 6 ------ .../ngf/traffic-management/upstream-http2-appprotocol.md | 4 ++-- 2 files changed, 2 insertions(+), 8 deletions(-) diff --git a/content/ngf/reference/permissions.md b/content/ngf/reference/permissions.md index 797f0be95c..e68bf333dd 100644 --- a/content/ngf/reference/permissions.md +++ b/content/ngf/reference/permissions.md @@ -65,12 +65,6 @@ NGINX containers managed by the control plane. No RBAC permissions needed since - **EmptyDir**: Read-write (required for NGINX operation) - **Secret/ConfigMap/Projected**: Read-only -{{< call-out "note" >}} - -Kubernetes is generally not recommended for hostile multi-tenant environments and NGINX is designed to treat upstreams as trusted. If you need a dataplane that doesn't treat upstreams as trusted, you may want to explore alternative solutions. - -{{< /call-out >}} - ## Certificate Generator Kubernetes Job that creates initial TLS certificates. diff --git a/content/ngf/traffic-management/upstream-http2-appprotocol.md b/content/ngf/traffic-management/upstream-http2-appprotocol.md index f452397f9f..51c9e08d51 100644 --- a/content/ngf/traffic-management/upstream-http2-appprotocol.md +++ b/content/ngf/traffic-management/upstream-http2-appprotocol.md @@ -7,14 +7,14 @@ f5-product: FABRIC f5-docs: DOCS-0000 description: Configure NGINX Gateway Fabric to use HTTP/2 for upstream connections by setting appProtocol to kubernetes.io/h2c on a Kubernetes Service port. f5-keywords: NGINX Gateway Fabric, HTTP/2, upstream HTTP/2, appProtocol, kubernetes.io/h2c, proxy_http_version, h2c, upstream connections, Service appProtocol, Gateway API, HTTPRoute, GRPCRoute -f5-summary: This guide shows you how to configure NGINX Gateway Fabric to proxy requests to upstream services over HTTP/2 by setting appProtocol to kubernetes.io/h2c on a Kubernetes Service port. Using HTTP/2 for upstream connections enables multiplexing and reduces latency for services that support it. This guide is for operators and developers who have NGINX Gateway Fabric installed and are familiar with Kubernetes Services and the Gateway API. +f5-summary: This guide describes how to configure NGINX Gateway Fabric to proxy requests to upstream services over HTTP/2 by setting appProtocol to kubernetes.io/h2c on a Kubernetes Service port. Using HTTP/2 for upstream connections enables multiplexing and reduces latency for services that support it. This guide is for operators and developers who have NGINX Gateway Fabric installed and are familiar with Kubernetes Services and the Gateway API. --- 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. Implementations of a controller such as NGINX Gateway Fabric use this field to offer richer behavior for protocols that are understood. For more information, view the official [Kubernetes Service Documentation](https://kubernetes.io/docs/concepts/services-networking/service/#application-protocol). +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](https://kubernetes.io/docs/concepts/services-networking/service/#application-protocol). 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`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_http_version) directive to `2` in the NGINX configuration. From 43a1ab52dbffdd6fb5c79bba781d29018fdca785 Mon Sep 17 00:00:00 2001 From: Ben Jee Date: Tue, 30 Jun 2026 12:39:37 -0700 Subject: [PATCH 5/5] Update gateway name --- content/ngf/traffic-management/upstream-http2-appprotocol.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/ngf/traffic-management/upstream-http2-appprotocol.md b/content/ngf/traffic-management/upstream-http2-appprotocol.md index 51c9e08d51..bb48839e4e 100644 --- a/content/ngf/traffic-management/upstream-http2-appprotocol.md +++ b/content/ngf/traffic-management/upstream-http2-appprotocol.md @@ -84,7 +84,7 @@ service/coffee ClusterIP 10.96.30.58 80/TCP 10s ## Create the Gateway API resources -Create the **cafe** Gateway: +Create a Gateway: ```yaml kubectl apply -f - <