routes/ingress: add documentation for HTTP2 ALPN routes

Add some clarification/documentation around HTTP/2 enabled routes.

operator/v1/types_ingress.go

@@ -99,6 +99,13 @@ type IngressControllerSpec struct {
 	// the generated certificate's CA will be automatically integrated with the
 	// cluster's trust store.
 	//
+	// If a wildcard certificate is used and shared by multiple
+	// HTTP/2 enabled routes (which implies ALPN) then clients
+	// (i.e., notably browsers) are at liberty to reuse open
+	// connections. This means a client can reuse a connection to
+	// another route and that is likely to fail. This behaviour is
+	// generally known as connection coalescing.
+	//
 	// The in-use certificate (whether generated or user-specified) will be
 	// automatically integrated with OpenShift's built-in OAuth server.
 	//

route/v1/types.go

@@ -26,6 +26,14 @@ import (
 // return information to clients about the names and states of the route under each router.
 // If a client chooses a duplicate name, for instance, the route status conditions are used
 // to indicate the route cannot be chosen.
+//
+// To enable HTTP/2 ALPN on a route it requires a custom
+// (non-wildcard) certificate. This prevents connection coalescing by
+// clients, notably web browsers. We do not support HTTP/2 ALPN on
+// routes that use the default certificate because of the risk of
+// connection re-use/coalescing. Routes that do not have their own
+// custom certificate will not be HTTP/2 ALPN-enabled on either the
+// frontend or the backend.
 type Route struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`