NGF: Add document for upstream http2 by bjee19 · Pull Request #2021 · nginx/documentation

bjee19 · 2026-06-03T05:48:59Z

Proposed changes

Add document on supporting http2 to upstream through the appProtocol field on a Service.

Checklist

Before sharing this pull request, I completed the following checklist:

I read the Contributing guidelines
My branch adheres to the Git conventions
My content changes adhere to the F5 Technical Writing Style Guide
If my changes involve potentially sensitive information¹, I have assessed the possible impact
I have waited to ensure my changes pass tests, and addressed any discovered issues

Potentially sensitive information includes personally identify information (PII), authentication credentials, and live URLs. Refer to the style guide for guidance about placeholder content. ↩

bjee19 · 2026-06-03T05:49:52Z

This is a shorter guide which is technically covering a Kubernetes concept (Service's appProtocol), however I couldn't find a suitable document to include this information in. So I decided to write a standalone document for it.

salonichf5 · 2026-06-03T16:16:19Z

+```nginx
+location /coffee {
+    ...
+    proxy_http_version 2;
+    proxy_pass http://default_coffee_80;
+    ...
+}
+```
+


so the curl doesn't return the protocol? or a different response to identify a http2 connection?

The upstream application in this example doesn't respond back with http2 responses/ "doesn't speak http2" so it won't really work with a curl request. I don't really feel the need to show a response with a working http2-available backend, so I felt that just showing the nginx conf would suffice.

If you feel like its necessary to show a curl request, basically checking if the nginx conf proxy_http_version 2; works, then we can consider that, but I don't feel the need.

A user guide implies end-to-end coverage. If this doesn't do that, it should be scoped down to a section within a larger doc, this feels incomplete to me.

could this be part of data plane configuration section as part of how to?

we could do a small section to enable HTTP2 on a service section

salonichf5 · 2026-06-03T16:16:52Z

+## Important Notes
+
+- `kubernetes.io/h2c` is supported on HTTPRoutes and GRPCRoutes. It isn't supported on TLSRoutes.
+- 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.


i think this could be in the troubleshooting section

Would that be in a different file? I feel like this is relevant enough to this feature that I would want it all contained in this single file. I can put it in a different section in the file if you think that would be better

no, just after other supported protocols section

bjee19 · 2026-06-06T04:25:19Z

+{{< 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 >}}


added this note here for the request by the user @salonichf5, do you have any thoughts? Should this even go in our docs here or maybe should it just live in our github docs somewhere? I don't really feel the need of highlighting this statement, and am on the border of if its necessary at all and might do more harm than good.

can we just remove this part "If you need a dataplane that doesn't treat upstreams as trusted, you may want to explore alternative solutions."

we shouldn't be recommending that I feel. The short callout is fine by me.

JTorreG · 2026-06-25T10:17:48Z

hi @bjee19 can you please resolve the suggestions and re-request reviews in slack?

JTorreG · 2026-06-25T10:44:48Z


+{{< 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.


Suggested change

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.

We don't recommend Kubernetes for hostile multi-tenant environments, and NGINX is designed to treat upstreams as trusted. If you need a data plane that doesn't treat upstreams as trusted, you may want to explore alternative solutions.

If we keep this statement, make it less vague. And "data plane" two words as per our style guide.

msatholaa · 2026-06-25T10:54:03Z

+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.


Suggested change

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.

msatholaa · 2026-06-25T11:00:57Z

+
+## 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).


Consider rephrasing.

The appProtocol field on a Kubernetes Service port provides a way to specify an application protocol. Controllers such as NGINX Gateway Fabric use this field to enable protocol-specific functionality for supported protocols.

Add document for upstream http2

9ce52c5

bjee19 requested a review from a team as a code owner June 3, 2026 05:49

github-actions Bot added documentation Improvements or additions to documentation product/ngf Issues related to NGINX Gateway Fabric labels Jun 3, 2026

bjee19 requested a review from a team June 3, 2026 05:49

salonichf5 reviewed Jun 3, 2026

View reviewed changes

bjee19 added 2 commits June 5, 2026 21:21

Add note on hostile multi-tenant clusters

7d6559a

Adjust wording on callout note

d8721c8

bjee19 commented Jun 6, 2026

View reviewed changes

bjee19 requested a review from a team June 16, 2026 16:34

Merge branch 'ngf-release-2.7' into ngf/http2-appProtocol

4d1d001

JTorreG reviewed Jun 25, 2026

View reviewed changes

msatholaa reviewed Jun 25, 2026

View reviewed changes

msatholaa approved these changes Jun 25, 2026

View reviewed changes


		{{< 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.

	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.
	We don't recommend Kubernetes for hostile multi-tenant environments, and NGINX is designed to treat upstreams as trusted. If you need a data plane that doesn't treat upstreams as trusted, you may want to explore alternative solutions.


		## 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).

Uh oh!

Conversation

bjee19 commented Jun 3, 2026

Proposed changes

Checklist

Footnotes

Uh oh!

bjee19 commented Jun 3, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

salonichf5 Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JTorreG commented Jun 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

salonichf5 Jun 16, 2026 •

edited

Loading