Merge pull request #87980 from mletalie/OSDOCS-13240

[OSD-GCP] Update instructions for y-stream (minor version) upgrade of WIF-enabled clusters

Author: bmcelvee

modules/create-wif-cluster-cli.adoc

@@ -9,9 +9,16 @@
 
 You can create an {product-title} on {GCP} cluster with Workload Identity Federation (WIF) using the OpenShift Cluster Manager CLI (`ocm`) in interactive or non-interactive mode.
 
+[NOTE]
+====
+Download the latest version of the OpenShift Cluster Manager CLI (`ocm`) for your operating system from the link:https://console.redhat.com/openshift/downloads[Downloads] page on OpenShift Cluster Manager.
+====
+
 [IMPORTANT]
 ====
-To create a WIF-enabled cluster, the OpenShift Cluster Manager CLI (`ocm`) must be version 1.0.2 or greater.
+[subs="attributes+"]
+OpenShift Cluster Manager API command-line interface (`ocm`) is a Technology Preview feature only.
+For more information about the support scope of Red Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope].
 ====
 
 Before creating the cluster, you must first create a WIF configuration.
@@ -38,9 +45,11 @@ Alternatively, you can use the `manual` mode. In `manual` mode, you are provided
 ----
 $ ocm gcp create wif-config --name <wif_name> \ <1>
   --project <gcp_project_id> \ <2>
+  --version <osd_version> <3>
 ----
 <1> Replace `<wif_name>` with the name of your WIF configuration.
 <2> Replace `<gcp_project_id>` with the ID of the {GCP} project where the WIF configuration will be implemented.
+<3> Optional: Replace `<osd_version>` with the desired {product-title} version the wif-config will need to support. If you do not specify a version, the wif-config will support the latest {product-title} y-stream version as well as the last three supported {product-title} y-stream versions (beginning with version 4.17).
 +
 --
 .Example output
@@ -179,13 +188,18 @@ $ ocm create cluster <cluster_name> \ <1>
 <5> Replace `<gcp_region>` with the {GCP} region where the new cluster will be deployed.
 <6> Optional: The subscription billing model for the cluster.
 <7> Optional: If you provided a value of `marketplace-gcp` for the `subscription-type` parameter, `marketplace-gcp-terms` must be equal to `true`.
-<8> Optional: The desired OpenShift version.
+<8> Optional: The desired {product-title} version.
 <9> Optional: Deploy to multiple data centers.
 <10> Optional: Enable autoscaling of compute nodes.
 <11> Optional: Minimum number of compute nodes.
 <12> Optional: Maximum number of compute nodes.
 <13> Optional: Secure Boot enables the use of Shielded VMs in the Google Cloud Platform.
 
+[IMPORTANT]
+====
+If an {product-title} version is specified, the version must also be supported by the assigned WIF configuration. If a version is specified that is not supported by the assigned WIF configuration, cluster creation will fail.  If this occurs, update the assigned WIF configuration to the desired version or create a new WIF configuration with the desired version in the --version <osd_version> field.
+====
+
 [id="ocm-cli-list-wif-commands_{context}"]
 == Listing WIF clusters
 
@@ -209,17 +223,17 @@ $ ocm list clusters --parameter search="gcp.authentication.wif_config_id = '<wif
 ====
 Updating a WIF configuration is only applicable for y-stream updates. For an overview of the update process, including details regarding version semantics, see link:https://www.redhat.com/en/blog/the-ultimate-guide-to-openshift-release-and-upgrade-process-for-cluster-administrators#:~:text=Ongoing%20security%20patches%20and%20bug,is%20the%20dark%20green%20bar.[The Ultimate Guide to OpenShift Release and Upgrade Process for Cluster Administrators].
 ====
-Before updating a WIF-enabled {product-title} cluster to a newer version, you must update the wif-config to that version as well. If you do not update the wif-config version before attempting to update the cluster version, the cluster version update will fail.
+Before upgrading a WIF-enabled {product-title} cluster to a newer version, you must update the wif-config to that version as well. If you do not update the wif-config version before attempting to upgrade the cluster version, the cluster version upgrade will fail.
 
 You can update a wif-config to a specific {product-title} version by running the following command:
 
 [source,terminal]
 ----
-ocm gcp update wif-config --version <version> \ <1>
---name <wif_name> <2>
+ocm gcp update wif-config <wif_name> \ <1>
+--version <version> <2>
 ----
-<1> Replace `<version>` with the {product-title} y-stream version you plan to update the cluster to.
-<2> Replace `<wif_name>` with the name of the WIF configuration you want to update.
+<1> Replace `<wif_name>` with the name of the WIF configuration you want to update.
+<2> Optional: Replace `<version>` with the {product-title} y-stream version you plan to update the cluster to. If you do not specify a version, the wif-config will be updated to support the latest {product-title} y-stream version as well as the last three {product-title} supported y-stream versions (beginning with version 4.17).
 
 [id="ocm-cli-verify-wif-commands_{context}"]
 == Verifying a WIF configuration

modules/upgrade-auto.adoc

@@ -20,7 +20,12 @@ You can use {cluster-manager} to schedule recurring, automatic upgrades for z-st
 . To schedule recurring upgrades, select *Recurring updates*.
 
 . Provide an administrator’s acknowledgment and click *Approve and continue*. {cluster-manager} does not start scheduled y-stream updates for minor versions without receiving an administrator’s acknowledgment.
-
++
+[IMPORTANT]
+====
+Before upgrading a Workload Identity Federation (WIF)-enabled {product-title} on {GCP} cluster, you must update the wif-config. For more information, see "Cluster upgrades with Workload Identity Federation (WIF)".
+====
++
 . Specify the day of the week and the time you want your cluster to upgrade.
 
 . Click *Save*.

modules/upgrade-manual.adoc

@@ -26,7 +26,12 @@ You can use {cluster-manager} to manually upgrade your {product-title} cluster o
 . Select the version you want to upgrade your cluster to. Recommended cluster upgrades appear in the UI. To learn more about each available upgrade version, click *View release notes*.
 
 . If you select an update version that requires approval, provide an administrator’s acknowledgment and click *Approve and continue*.
-
++
+[IMPORTANT]
+====
+Before upgrading a Workload Identity Federation (WIF)-enabled {product-title} on {GCP} cluster, you must update the wif-config. For more information, see "Cluster upgrades with Workload Identity Federation (WIF)".
+====
++
 . Click *Next*.
 
 . To schedule your upgrade:

modules/upgrade.adoc

@@ -9,6 +9,11 @@
 
 When upgrades are made available for your {product-title} cluster, you can upgrade to the newest version through {cluster-manager-first} or {cluster-manager} CLI. You can set your upgrade policies on existing clusters or during cluster creation, and upgrades can be scheduled to occur automatically or manually.
 
+[IMPORTANT]
+====
+Before upgrading a Workload Identity Federation (WIF)-enabled {product-title} on {GCP} cluster, you must update the wif-config. For more information, see "Cluster upgrades with Workload Identity Federation (WIF)".
+====
+
 Red Hat Site Reliability Engineers (SRE) will provide a curated list of available versions for your {product-title} clusters. For each cluster you will be able to review the full list of available releases, as well as the corresponding release notes. {cluster-manager} will enable installation of clusters at the latest supported versions, and upgrades can be canceled at any time.
 
 You can also set a grace period for how long `PodDisruptionBudget` protected workloads are respected during upgrades. After this grace period, any workloads protected by  `PodDisruptionBudget` that have not been successfully drained from a node, will be forcibly deleted.
@@ -62,3 +67,13 @@ For recurring upgrades, you will also receive email notifications before the upg
 * 1 week notice
 * 1 day notice
 ====
+
+[id="wif-upgrades_{context}"]
+== Cluster upgrades with Workload Identity Federation (WIF)
+Before upgrading an {product-title} on {GCP} cluster with WIF authentication type to a newer y-stream version, you must update the WIF configuration to that version as well. Failure to do so before attempting to upgrade the cluster version will result in an error.
+For more information on how to update a WIF configuration, see the  _Additional resources_ section.
+
+[NOTE]
+====
+The update path to a brand new release of {product-title} is not available in the stable channel until 45 to 90 days after the initial GA of a newer y-stream version.
+====

osd_whats_new/osd-whats-new.adoc

@@ -21,6 +21,8 @@ With its foundation in Kubernetes, {product-title} is a complete {OCP} cluster p
 * **New version of {product-title} available.** {product-title} on {gcp} and {product-title} on {aws} versions 4.18 are now available. For more information about upgrading to this latest version, see xref:../upgrading/osd-upgrades.adoc#osd-upgrades[Red Hat OpenShift Dedicated cluster upgrades].
 * **Support for assigning newly created machine pools to specific availability zones within a Multi-AZ cluster.**
 {product-title} on {GCP} users can now assign machine pools to specific availability zones using the {cluster-manager} CLI (`ocm`). For more information, see xref:../osd_cluster_admin/osd_nodes/osd-nodes-machinepools-about.adoc#deploying-a-machine-pool-in-a-single-availability-zone-within-a-multi-az-cluster[Deploying a machine pool in a single availability zone within a Multi-AZ cluster].
+* ** Support for specifying {product-title} versions when creating or updating a Workload Identity Federation (WIF) configuration.**
+{product-title} on {GCP} users can now specify minor versions when creating or updating a WIF configuration. For more information, see xref:../osd_gcp_clusters/creating-a-gcp-cluster-with-workload-identity-federation.adoc#create-wif-cluster-cli_osd-creating-a-cluster-on-gcp-with-workload-identity-federation[Creating a Workload Identity Federation cluster using the OCM CLI].
 
 * **Cluster node limit update.** {product-title} clusters versions 4.14.14 and greater can now scale to 249 worker nodes. This is an increase from the previous limit of 180 nodes. For more information, see xref:../osd_planning/osd-limits-scalability.adoc#osd-limits-scalability[limits and scalability].
 // * **{product-title} SDN network plugin blocks future major upgrades**

upgrading/osd-upgrades.adoc

@@ -18,5 +18,7 @@ include::modules/upgrade.adoc[leveloffset=+1]
 
 * For more information about the service log and adding cluster notification contacts, see xref:../osd_cluster_admin/osd-cluster-notifications.adoc#managed-cluster-notification-view-hcc_osd-cluster-notifications[Accessing cluster notifications in {hybrid-console}].
 
+* For more information on how to update a WIF configuration, see xref:../osd_gcp_clusters/creating-a-gcp-cluster-with-workload-identity-federation.adoc#wif-configuration-update_osd-creating-a-cluster-on-gcp-with-workload-identity-federation[Updating a WIF configuration].
+
 include::modules/upgrade-auto.adoc[leveloffset=+1]
 include::modules/upgrade-manual.adoc[leveloffset=+1]