Merge pull request #94220 from jldohmann/gwapi-pt2

additional gwapi information on management succession

Author: jldohmann

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

@@ -6,7 +6,9 @@
 [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.
+Starting in {product-title} 4.19, the Ingress Operator manages the lifecycle of any Gateway API custom resource definitions (CRDs). This means that you will be denied access to creating, updating, and deleting any CRDs within the API groups that are grouped under Gateway API.
+
+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.1 CRDs.
 
 [WARNING]
 ====
@@ -17,14 +19,19 @@ Updating or deleting Gateway API resources can result in downtime and loss of se
 * 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.
++
+[WARNING]
+====
+Backup and restore can fail or result in data loss for any CRD fields that were present in the old definitions but are absent in the new definitions.
+====
 
 .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"
+$ oc get crd | grep -F -e gateway.networking.k8s.io -e gateway.networking.x-k8s.io
 ----
 +
 .Example output
@@ -51,12 +58,21 @@ 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.
+Deleting CRDs removes every custom resource that relies on them and can result in data loss. Back up any necessary data before deleting the Gateway API CRDs. 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
+$ oc apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/standard-install.yaml
 ----
++
+[WARNING]
+====
+You can perform this step without deleting your CRDs. If your update to a CRD removes a field that is used by a custom resource, you can lose data. Updating a CRD a second time, to a version that re-adds a field, can cause any previously deleted data to reappear. Any third-party controller that depends on a specific Gateway API CRD version that is not supported in {product-title} {product-version} will break upon updating that CRD to one supported by Red{nbsp}Hat.
+
+For more information on the {product-title} implementation and the dead fields issue, see _Gateway API implementation for {product-title}_.
+====
+
+

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 and Gateway API networking resources.
+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.
 
 [id="migrating-workloads-to-different-nodes_{context}"]
 == Migrating workloads off of package-based {op-system-base} worker nodes
@@ -121,5 +121,3 @@ 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]

updating/preparing_for_updates/updating-cluster-prepare.adoc

@@ -63,6 +63,14 @@ include::modules/update-etcd-backup.adoc[leveloffset=+1]
 
 * xref:../../backup_and_restore/control_plane_backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[Restoring to a previous cluster state]
 
+// Gateway API management succession
+include::modules/nw-ingress-gateway-api-manage-succession.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../networking/configuring_ingress_cluster_traffic/ingress-gateway-api.adoc#nw-ingress-gateway-api-implementation[Gateway API implementation for {product-title}]
+
 // Best practices for cluster updates
 include::modules/update-best-practices.adoc[leveloffset=+1]