osdocs16528 Gateway API OSSM v2x Subscription Conflict

Author: Daniel Chadwick

modules/nw-ingress-gateway-api-enable.adoc

@@ -8,6 +8,17 @@
 
 When you create a GatewayClass as shown in the first step, it configures Gateway API for use on your cluster.
 
+[IMPORTANT]
+====
+The {product-title} Gateway API implementation relies on the Cluster Ingress Operator (CIO) to install and manage a specific version of OpenShift Service Mesh (OSSM v3.x) in the `openshift-ingress` namespace.
+
+A conflict occurs if your cluster already has an active OpenShift Service Mesh (OSSM v2.x) subscription in any namespace. OSSM v2.x and OSSM v3.x cannot coexist on the same cluster.
+
+If a conflicting OSSM v2.x subscription is present when you create a GatewayClass resource, the Cluster Ingress Operator attempts to install the required OSSM v3.x components but fails this installation operation. As a result, Gateway API resources ,such as Gateway or HTTPRoute, have no effect and no proxy gets configured to route traffic. In {product-title} 4.19, this failure is silent; In {product-title} 4.20 and later, this conflict causes the ingress ClusterOperator to report a Degraded status.
+
+Before enabling Gateway API by creating a `GatewayClass`, verify that you do not have an active OSSM v2.x subscription on the cluster.
+====
+
 .Procedure
 
 . Create a `GatewayClass` object: