openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00
Code Issues Releases Activity

Merge pull request #89596 from openshift-cherrypick-robot/cherry-pick-87145-to-enterprise-4.19

Browse Source 
[enterprise-4.19] OSDOCS-12906: Linked HTTP/2 doc in route config guide
This commit is contained in:
Darragh Fitzmaurice
2025-03-05 10:33:32 +00:00
committed by GitHub
parent 3fd5ec28c9 59b0e8e931
commit 71dbe84e2d
5 changed files with 29 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
modules/nw-creating-a-route.adoc
View File

@@ -6,7 +6,7 @@
[id="nw-creating-a-route_{context}"]
= Creating an HTTP-based route
A route allows you to host your application at a public URL. It can either be secure or unsecured, depending on the network security configuration of your application. An HTTP-based route is an unsecured route that uses the basic HTTP routing protocol and exposes a service on an unsecured application port.
Create a route to host your application at a public URL. The route can either be secure or unsecured, depending on the network security configuration of your application. An HTTP-based route is an unsecured route that uses the basic HTTP routing protocol and exposes a service on an unsecured application port.
The following procedure describes how to create a simple HTTP-based route to a web application, using the `hello-openshift` application as an example.
//link:https://github.com/openshift/origin/tree/master/examples/hello-openshift[hello-openshift]

14
modules/nw-enabling-hsts-per-route.adoc
View File

@@ -19,19 +19,14 @@ endif::microshift[]
.Procedure
* To enable HSTS on a route, add the `haproxy.router.openshift.io/hsts_header` value to the edge-terminated or re-encrypt route. You can use the `oc annotate` tool to do this by running the following command:
* To enable HSTS on a route, add the `haproxy.router.openshift.io/hsts_header` value to the edge-terminated or re-encrypt route. You can use the `oc annotate` tool to do this by running the following command. To properly run the command, ensure that the semicolon (`;`) in the `haproxy.router.openshift.io/hsts_header` route annotation is also surrounded by double quotation marks (`""`).
+
.Example `annotate` command that sets the maximum age to `31536000` ms (approximetly 8.5 hours)
[source,terminal]
----
$ oc annotate route <route_name> -n <namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000;\ <1>
$ oc annotate route <route_name> -n <namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header=max-age=31536000;\
includeSubDomains;preload"
----
<1> In this example, the maximum age is set to `31536000` ms, which is approximately 8.5 hours.
+
[NOTE]
====
In this example, the equal sign (`=`) is in quotes. This is required to properly execute the annotate command.
====
+
.Example route configured with an annotation
[source,yaml]
@@ -41,13 +36,14 @@ kind: Route
metadata:
annotations:
haproxy.router.openshift.io/hsts_header: max-age=31536000;includeSubDomains;preload <1> <2> <3>
...
# ...
spec:
host: def.abc.com
tls:
termination: "reencrypt"
...
wildcardPolicy: "Subdomain"
# ...
----
<1> Required. `max-age` measures the length of time, in seconds, that the HSTS policy is in effect. If set to `0`, it negates the policy.
<2> Optional. When included, `includeSubDomains` tells the client

27
modules/nw-http2-haproxy.adoc
View File

@@ -2,24 +2,31 @@
//
// * networking/ingress-operator.adoc
:_mod-docs-content-type: PROCEDURE
:_mod-docs-content-type: CONCEPT
[id="nw-http2-haproxy_{context}"]
= Enabling and disabling HTTP/2 on Ingress Controllers
= Enable or disable HTTP/2 on Ingress Controllers
You can enable or disable transparent end-to-end HTTP/2 connectivity in HAProxy. This allows application owners to make use of HTTP/2 protocol capabilities, including single connection, header compression, binary streams, and more.
You can enable or disable transparent end-to-end HTTP/2 connectivity in HAProxy. Application owners can use HTTP/2 protocol capabilities, including single connection, header compression, binary streams, and more.
You can enable or disable HTTP/2 connectivity for an individual Ingress Controller or for the entire cluster.
To enable the use of HTTP/2 for the connection from the client to HAProxy, a route must specify a custom certificate. A route that uses the default certificate cannot use HTTP/2. This restriction is necessary to avoid problems from connection coalescing, where the client re-uses a connection for different routes that use the same certificate.
The connection from HAProxy to the application pod can use HTTP/2 only for re-encrypt routes and not for edge-terminated or insecure routes. This restriction is because HAProxy uses Application-Level Protocol Negotiation (ALPN), which is a TLS extension, to negotiate the use of HTTP/2 with the back-end. The implication is that end-to-end HTTP/2 is possible with passthrough and re-encrypt and not with edge-terminated routes.
[NOTE]
====
You can use HTTP/2 with an insecure route whether the Ingress Controller has HTTP/2 enabled or disabled.
If you enable or disable HTTP/2 connectivity for an individual Ingress Controller and for the entire cluster, the HTTP/2 configuration for the Ingress Controller takes precedence over the HTTP/2 configuration for the cluster.
====
To enable the use of HTTP/2 for a connection from the client to an HAProxy instance, a route must specify a custom certificate. A route that uses the default certificate cannot use HTTP/2. This restriction is necessary to avoid problems from connection coalescing, where the client re-uses a connection for different routes that use the same certificate.
Consider the following use cases for an HTTP/2 connection for each route type:
* For a re-encrypt route, the connection from HAProxy to the application pod can use HTTP/2 if the application supports using Application-Level Protocol Negotiation (ALPN) to negotiate HTTP/2 with HAProxy. You cannot use HTTP/2 with a re-encrypt route unless the Ingress Controller has HTTP/2 enabled.
* For a passthrough route, the connection can use HTTP/2 if the application supports using ALPN to negotiate HTTP/2 with the client. You can use HTTP/2 with a passthrough route if the Ingress Controller has HTTP/2 enabled or disabled.
* For an edge-terminated secure route, the connection uses HTTP/2 if the service specifies only `appProtocol: kubernetes.io/h2c`. You can use HTTP/2 with an edge-terminated secure route if the Ingress Controller has HTTP/2 enabled or disabled.
* For an insecure route, the connection uses HTTP/2 if the service specifies only `appProtocol: kubernetes.io/h2c`. You can use HTTP/2 with an insecure route if the Ingress Controller has HTTP/2 enabled or disabled.
[IMPORTANT]
====
For non-passthrough routes, the Ingress Controller negotiates its connection to the application independently of the connection from the client. This means a client may connect to the Ingress Controller and negotiate HTTP/1.1, and the Ingress Controller might then connect to the application, negotiate HTTP/2, and forward the request from the client HTTP/1.1 connection using the HTTP/2 connection to the application. This poses a problem if the client subsequently tries to upgrade its connection from HTTP/1.1 to the WebSocket protocol, because the Ingress Controller cannot forward WebSocket to HTTP/2 and cannot upgrade its HTTP/2 connection to WebSocket. Consequently, if you have an application that is intended to accept WebSocket connections, it must not allow negotiating the HTTP/2 protocol or else clients will fail to upgrade to the WebSocket protocol.
====
For non-passthrough routes, the Ingress Controller negotiates its connection to the application independently of the connection from the client. This means a client might connect to the Ingress Controller and negotiate HTTP/1.1. The Ingress Controller might then connect to the application, negotiate HTTP/2, and forward the request from the client HTTP/1.1 connection by using the HTTP/2 connection to the application.
This sequence of events causes an issue if the client subsequently tries to upgrade its connection from HTTP/1.1 to the WebSocket protocol. Consider that if you have an application that is intending to accept WebSocket connections, and the application attempts to allow for HTTP/2 protocol negotiation, the client fails any attempt to upgrade to the WebSocket protocol.
====

1
networking/networking_operators/ingress-operator.adoc
View File

@@ -97,6 +97,7 @@ include::modules/nw-ingress-set-or-delete-http-headers.adoc[leveloffset=+2]
include::modules/nw-using-ingress-forwarded.adoc[leveloffset=+2]
// Enable or disable HTTP/2 on Ingress Controllers
include::modules/nw-http2-haproxy.adoc[leveloffset=+2]
include::modules/nw-enable-http2.adoc[leveloffset=+3]

5
networking/routes/route-configuration.adoc
View File

@@ -26,6 +26,11 @@ include::modules/nw-enabling-hsts.adoc[leveloffset=+1]
//Enabling HTTP strict transport security per-route
include::modules/nw-enabling-hsts-per-route.adoc[leveloffset=+2]
[role="_additional-resources"]
.Additional resources
* xref:../../networking/networking_operators/ingress-operator.adoc#nw-http2-haproxy_configuring-ingress[Enabling HTTP/2 Ingress connectivity]
//Disabling HTTP strict transport security per-route
include::modules/nw-disabling-hsts.adoc[leveloffset=+2]