Merge pull request #87145 from dfitzmau/OSDOCS-12906

OSDOCS-12906: Linked HTTP/2 doc in route config guide

Author: dfitzmau

modules/nw-creating-a-route.adoc

@@ -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]

modules/nw-enabling-hsts-per-route.adoc

@@ -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

modules/nw-http2-haproxy.adoc

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

networking/networking_operators/ingress-operator.adoc

@@ -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]

networking/routes/route-configuration.adoc

@@ -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]