Merge pull request #40888 from sagidlow/OSDOCS-3147-410

OSDCOCS-3147: Adding EUS to EUS upgrade for 4.10

_topic_maps/_topic_map.yml

@@ -423,7 +423,9 @@ Topics:
 - Name: Installing and configuring the OpenShift Update Service
   File: installing-update-service
 - Name: Understanding upgrade channels
-  File: understanding-upgrade-channels-release  
+  File: understanding-upgrade-channels-release
+- Name: Preparing to perform an EUS to EUS upgrade
+  File: preparing-eus-eus-upgrade  
 - Name: Updating a cluster within a minor version using the web console
   File: updating-cluster-within-minor
 - Name: Updating a cluster within a minor version using the CLI

modules/updating-eus-to-eus-upgrade.adoc

@@ -0,0 +1,138 @@
+// Module included in the following assemblies:
+//
+// * updating/preparing-eus-eus-upgrade.adoc
+
+[id="updating-eus-to-eus-upgrade_{context}"]
+= EUS to EUS upgrade
+
+The following procedure pauses all non-master MachineConfigPools and performs upgrades from {product-title} 4.8 to 4.9 to 4.10, then unpauses the previously paused MachineConfigPools.
+Following this procedure reduces the total upgrade duration and the number of times worker nodes are restarted.
+
+.Prerequisites
+
+* Review the release notes for {product-title} 4.9 and 4.10
+* Review the release notes and product lifecycles for any layered products and OLM Operators. Some may require updates either before or during an EUS to EUS upgrade.
+* Ensure that you are familiar with version-specific prerequisites, such as link:https://docs.openshift.com/container-platform/4.9/updating/updating-cluster-prepare.html#update-preparing-migrate_updating-cluster-prepare[administrator acknowledgement] that is required prior to upgrading from {product-title} 4.8 to 4.9.
+* Verify that your cluster is not running a version earlier than {product-title} 4.8.14.
+If your cluster is running a version than {product-title} 4.8.14, you must upgrade to a later 4.8.z version prior to upgrading to 4.9.
+The upgrade to 4.8.14 or later is necessary to fulfill the minimum version requirements that must be performed without pausing MachineConfigPools.
+* Verify that MachineConfigPools is unpaused.
+
+.Procedure
+
+. Upgrade any OLM Operators to versions that are compatible with both versions you are upgrading to.
+
+. Verify that all MachineConfigPools display a status of `UPDATED` and no MachineConfigPools display a status of `UPDATING`.
+To view the status of all MachineConfigPools, run the following command:
++
+[source,terminal]
+----
+$ oc get mcp
+----
++
+.Example output
++
+Output is trimmed for clarity:
++
+[source,terminal]
+----
+NAME     CONFIG                                         	UPDATED   UPDATING
+master   rendered-master-ecbb9582781c1091e1c9f19d50cf836c       True  	  False
+worker   rendered-worker-00a3f0c68ae94e747193156b491553d5       True  	  False
+----
+
+. To pause the MachineConfigPools you wish to skip reboots on, run the following commands:
++
+[NOTE]
+====
+You cannot pause the master pool.
+====
++
+[source,terminal]
+----
+$ oc patch mcp/worker --type merge --patch '{"spec":{"paused":true}}'
+----
+
+. To change to the `eus-4.10` channel and upgrade to 4.9, run the following commands:
++
+[source,terminal]
+----
+$ oc adm upgrade channel eus-4.10
+$ oc adm upgrade --to-latest
+----
++
+.Example output
++
+[source,terminal]
+----
+Updating to latest version 4.9.18
+----
+
+. To ensure the 4.9 upgrades are completed successfully retrieve the cluster version, run the following command:
++
+[source,terminal]
+----
+$ oc get clusterversion
+----
++
+.Example output
++
+[source,terminal]
+----
+NAME  	  VERSION  AVAILABLE  PROGRESSING   SINCE   STATUS
+version   4.9.18   True       False         6m29s   Cluster version is 4.9.18
+----
+
+. If necessary, upgrade OLM operators using the Administrator perspective on the web console.
+
+. To upgrade to 4.10, run the following command:
++
+[source,terminal]
+----
+$ oc adm upgrade --to-latest
+----
+
+. To ensure the 4.10 upgrade is completed successfully retrieve the cluster version, run the following command:
++
+[source,terminal]
+----
+$ oc get clusterversion
+----
++
+.Example output
++
+[source,terminal]
+----
+NAME  	  VERSION  AVAILABLE  PROGRESSING   SINCE   STATUS
+version   4.10.1   True       False         6m29s   Cluster version is 4.10.1
+----
+
+. To unpause all previously paused MachineConfigPools, run the following command:
++
+[source,terminal]
+----
+$ oc patch mcp/worker --type merge --patch '{"spec":{"paused":false}}'
+----
++
+[NOTE]
+====
+If pools are not unpaused, the cluster is not permitted to upgrade to any future minors and maintenance tasks such as certificate rotation are inhibited. This puts the cluster at risk for future degradation.
+====
+
+. To verify that your previously paused pools have updated and your cluster completed the upgrade to 4.10, run the following command:
++
+[source,terminal]
+----
+$ oc get mcp
+----
++
+.Example output
++
+Output is trimmed for clarity:
++
+[source,terminal]
+----
+NAME 	   CONFIG                                            UPDATED     UPDATING
+master   rendered-master-52da4d2760807cb2b96a3402179a9a4c    True  	 False
+worker   rendered-worker-4756f60eccae96fb9dcb4c392c69d497    True 	 False
+----

updating/preparing-eus-eus-upgrade.adoc

@@ -0,0 +1,22 @@
+[id="preparing-eus-eus-upgrade"]
+= Performing to perform an EUS to EUS upgrade
+include::modules/common-attributes.adoc[]
+:context: eus-to-eus-upgrade
+
+toc::[]
+
+Due to fundamental Kubernetes design, all {product-title} upgrades between minor versions must be serialized.
+You must upgrade from {product-title} 4.8 to 4.9 and then to 4.10. You cannot upgrade from {product-title} 4.8 to 4.10 directly.
+However, beginning with the upgrade from {product-title} 4.8 to 4.9 to 4.10, administrators who wish to upgrade between two Extended Update Support (EUS) versions can do so incurring only a single reboot of non-master hosts.
+
+There are a number of caveats to consider when attempting an EUS to EUS upgrade.
+
+* EUS to EUS upgrades are only offered after upgrades between all versions involved have been made available in `stable` channels.
+* If you encounter issues during or after upgrading to the odd-numbered minor version but before upgrading to the next even-numbered version, then remediation of those issues may require that non-master hosts complete the upgrade to the odd-numbered version before moving forward.
+* You can complete the upgrade process during multiple maintenance windows by pausing at intermediate steps. However, plan to complete the entire upgrade within 60 days. This is critical to ensure that normal cluster automation processes are completed including those associated with certificate rotation.
+* You must be running at least {product-title} 4.8.14 before starting the EUS-to-EUS upgrade procedure. If you do not meet this minimum requirement, upgrade to a later 4.8.z before attempting the EUS-to-EUS upgrade.
+* Support for RHEL7 workers was removed in {product-title} 4.10 and replaced with RHEL8 workers, therefore EUS to EUS upgrades are not available for clusters with RHEL7 workers.
+* Node components are not updated to {product-title} 4.9. Do not expect all features and bugs fixed in {product-title} 4.9 to be made available until you complete the upgrade to {product-title} 4.10 and enable all MachineConfigPools to update.
+
+
+include::modules/updating-eus-to-eus-upgrade.adoc[leveloffset=+1]