Merge pull request #93327 from jldohmann/OSDOCS-13326

OSDOCS-13326: add management succession procedure

Author: jldohmann

modules/nw-ingress-gateway-api-manage-succession.adoc

@@ -0,0 +1,62 @@
+// 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-manage-succession_{context}"]
+= Preparing for Gateway API management succession by the Ingress Operator
+
+Starting in {product-title} 4.19, the Ingress Operator manages the lifecycle of any Gateway API custom resource definitions (CRDs). Updating from a version before 4.19 of {product-title} where this management was not present requires you to replace or remove any Gateway API CRDs that already exist in the cluster so that they conform to the specific {product-title} specification required by the Ingress Operator. {product-title} version 4.19 requires Gateway API Standard version 1.2.0 CRDs.
+
+[WARNING]
+====
+Updating or deleting Gateway API resources can result in downtime and loss of service or data. Be sure you understand how this will affect your cluster before performing the steps in this procedure. If necessary, back up any Gateway API objects in YAML format in order to restore it later.
+====
+
+.Prerequisites
+* You have installed the OpenShift CLI (`oc`).
+* You have access to an {product-title} account with cluster administrator access.
+* Optional: You have backed up any necessary Gateway API objects.
+
+.Procedure
+
+. List all the Gateway API CRDs that you need to remove by running the following command:
++
+[source,terminal]
+----
+$ oc get crd | grep "gateway.networking"
+----
++
+.Example output
++
+[source,terminal]
+----
+gatewayclasses.gateway.networking.k8s.io
+gateways.gateway.networking.k8s.io
+grpcroutes.gateway.networking.k8s.io
+httproutes.gateway.networking.k8s.io
+referencegrants.gateway.networking.k8s.io
+----
+
+. Delete the Gateway API CRDs from the previous step by running the following command:
++
+[source,terminal]
+----
+$ oc delete crd gatewayclasses.networking.k8s.io && \
+oc delete crd gateways.networking.k8s.io && \
+oc delete crd grpcroutes.gateway.networking.k8s.io && \
+oc delete crd httproutes.gateway.networking.k8s.io && \
+oc delete crd referencesgrants.gateway.networking.k8s.io
+----
++
+[IMPORTANT]
+====
+Any controller that was previously managing the lifecycle of the Gateway API CRDs will fail to operate properly. Attempting to force its use in conjunction with the Ingress Operator to manage Gateway API CRDs might prevent the cluster update from succeeding.
+====
+
+. Get the supported Gateway API CRDs by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml
+----

updating/preparing_for_updates/updating-cluster-prepare-past-4-18.adoc

@@ -6,7 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-Before you update from {product-title} 4.18 to a newer version, learn about some of the specific concerns around {op-system-base-full} compute machines.
+Before you update from {product-title} 4.18 to a newer version, learn about some of the specific concerns around {op-system-base-full} compute machines and Gateway API networking resources.
 
 [id="migrating-workloads-to-different-nodes_{context}"]
 == Migrating workloads off of package-based {op-system-base} worker nodes
@@ -121,3 +121,5 @@ If you need additional compute nodes for your workloads, you can provision new o
 * xref:../../machine_management/user_infra/adding-compute-user-infra-general.adoc#adding-compute-user-infra-general[Adding compute machines to clusters with user-provisioned infrastructure manually]
 
 For installer-provisioned infrastructure installations, automatic scaling adds {op-system} nodes by default. For user-provisioned infrastructure installations on bare metal platforms, you can manually xref:../../post_installation_configuration/node-tasks.adoc#post-install-config-adding-fcos-compute[add {op-system} compute nodes to your cluster].
+
+include::modules/nw-ingress-gateway-api-manage-succession.adoc[leveloffset=+1]