diff --git a/modules/nw-creating-a-route.adoc b/modules/nw-creating-a-route.adoc index 8fc90bbfc9..50b512a15c 100644 --- a/modules/nw-creating-a-route.adoc +++ b/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] diff --git a/modules/nw-enabling-hsts-per-route.adoc b/modules/nw-enabling-hsts-per-route.adoc index ba9d069ce8..d84ff73429 100644 --- a/modules/nw-enabling-hsts-per-route.adoc +++ b/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 -n --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000;\ <1> +$ oc annotate route -n --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 diff --git a/modules/nw-http2-haproxy.adoc b/modules/nw-http2-haproxy.adoc index 80c569c364..f0015e3b84 100644 --- a/modules/nw-http2-haproxy.adoc +++ b/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. -==== \ No newline at end of file +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. +==== diff --git a/networking/networking_operators/ingress-operator.adoc b/networking/networking_operators/ingress-operator.adoc index 1eab471946..8badd69a5f 100644 --- a/networking/networking_operators/ingress-operator.adoc +++ b/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] diff --git a/networking/routes/route-configuration.adoc b/networking/routes/route-configuration.adoc index b73971b871..991f129446 100644 --- a/networking/routes/route-configuration.adoc +++ b/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]