Merge pull request #100951 from DCChadwick/osdocs16529

OSDOCS-16529: Ingress Operator is Degraded due to Gateway API and OSSM conflict

Author: dfitzmau

modules/nw-ingress-gateway-api-troubleshooting-degraded.adoc

@@ -0,0 +1,57 @@
+// Modules included in the following assemblies:
+//
+// * networking/configuring_ingress_cluster_traffic/ingress-gateway-api.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="nw-ingress-gateway-api-troubleshooting-degraded_{context}"]
+= Ingress Operator is Degraded due to Gateway API and OSSM conflict
+
+In {product-title} 4.20 and later, if you create a `GatewayClass` resource while a conflicting OpenShift Service Mesh (OSSM) v2.x subscription exists, the `ingress` Cluster Operator (CIO) reports a `Degraded` status. This procedure details how to verify and resolve this conflict.
+
+The conflict occurs because the Gateway API implementation requires OSSM v3.x, which cannot coexist with OSSM v2.x. The CIO detects this conflict, stops the Gateway API provisioning, and reports the `Degraded` status to alert administrators. 
+
+.Prerequisites
+
+Your Cluster Operator reports a status of `True` and a type of `Degraded` with a reason of `GatewayAPIOSSMConflict`. Verify by running the following command: 
+
+[source,terminal]
+----
+$ oc get clusteroperator ingress -o yaml
+----
+
+In the `status` section of the output, look for a `Degraded` condition with `status: "True"` and `reason: GatewayAPIOSSMConflict`.
+
+[source,yaml]
+----
+status:
+  conditions:
+
+    lastTransitionTime: "2025-10-22T17:00:00Z"
+
+    message: 'Failed to install OpenShift Service Mesh 3.x for Gateway API: A
+      conflicting OpenShift Service Mesh 2.x subscription was found. Remove the
+      GatewayClass resource or the conflicting OSSM 2.x subscription to resolve.'
+    reason: GatewayAPIOSSMConflict
+    status: "True"
+    type: Degraded
+----
+
+You can resolve this issue and clear the `Degraded` status either by removing the `GatewayClass` resource or by using Openshift Gateway API to remove the conflicting OpenShift Service Mesh v2.x subscription from the cluster.
+
+.Procedure
+
+* If you do not intend to use the OpenShift Gateway API, remove the `GatewayClass` resource. This signals to the Ingress Operator to stop attempting to provision Gateway API.
++
+[source,terminal]
+----
+$ oc delete gatewayclass <gatewayclass-name>
+----
+
+* If you do intend to use the OpenShift Gateway API, you must remove the conflicting OpenShift Service Mesh v2.x subscription from the cluster. 
++
+[source,terminal]
+----
+$ oc -n openshift-operators delete subscription <OSSM v2.x subscription name>
+----
++
+After the v2.x subscription is removed, the Ingress Operator automatically retries the installation of OSSM v3.x and completes the Gateway API provisioning.

networking/ingress_load_balancing/configuring_ingress_cluster_traffic/ingress-gateway-api.adoc

@@ -21,5 +21,7 @@ include::modules/nw-ingress-gateway-api-enable.adoc[leveloffset=+1]
 
 include::modules/nw-ingress-gateway-api-deployment-topologies.adoc[leveloffset=+1]
 
+include::modules/nw-ingress-gateway-api-troubleshooting-degraded.adoc[leveloffset=+1]
+
 .Additional resources
 * xref:configuring-ingress-cluster-traffic-ingress-controller.adoc#nw-ingress-sharding-concept_configuring-ingress-cluster-traffic-ingress-controller[Ingress Controller sharding].