OSDOCS#5665: Adding steps to migrate clusters to multi-arch cli

_topic_maps/_topic_map.yml

@@ -598,7 +598,9 @@ Topics:
 - Name: Updating a cluster using the web console
   File: updating-cluster-within-minor
 - Name: Updating a cluster using the CLI
-  File: updating-cluster-cli
+  File: updating-cluster-cli 
+- Name: Migrating to a cluster with multi-architecture compute machines
+  File: migrating-to-multi-payload
 - Name: Performing update using canary rollout strategy
   File: update-using-custom-machine-config-pools
 - Name: Updating a cluster that includes RHEL compute machines

modules/migrating-to-multi-arch-cli.adoc

@@ -0,0 +1,85 @@
+// Module included in the following assemblies:
+//
+// * updating/migrating-to-multi-payload.adoc
+
+:_content-type: PROCEDURE
+[id="migrating-to-multi-arch-cli_{context}"]
+= Migrating to a cluster with multi-architecture compute machines using the CLI
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` role.
+* Your {product-title} version is up to date to at least version 4.13.0. 
++
+For more information on how to update your cluster version, see _Updating a cluster using the web console_ or _Updating a cluster using the CLI_.
+* You have installed the OpenShift CLI (`oc`) that matches the version for your current cluster.
+* Your `oc` client is updated to at least verion 4.13.0. 
+* Your {product-title} cluster is installed on either the AWS or Azure platform. 
++
+For more information on selecting a supported platform for your cluster installation, see _Selecting a cluster installation type_.
+
+
+.Procedure
+. Verify that the `RetrievedUpdates` condition is `True` in the Cluster Version Operator (CVO) by running the following command:
++
+[source,terminal]
+----
+$ oc get clusterversion/version -o=jsonpath="{.status.conditions[?(.type=='RetrievedUpdates')].status}"
+----
++
+If the `RetrievedUpates` condition is `False`, you can find supplemental information regarding the failure by using the following command:
++
+[source,terminal]
+----
+$ oc adm upgrade
+----
++ 
+For more information about cluster version condition types, see _Understanding cluster version condition types_.
+
+. If the condition `RetrievedUpdates` is `False`, change the channel to `stable-<4.y>` or `fast-<4.y>` with the following command: 
++
+[source,terminal]
+----
+$ oc adm upgrade channel <channel>
+----
++
+After setting the channel, verify if `RetrievedUpdates` is `True`. 
++
+For more information about channels, see _Understanding update channels and releases_.
+
+. Migrate to the multi-architecture payload with following command:
++
+[source,terminal]
+----
+$ oc adm upgrade --to-multi-arch
+----
+
+.Verification 
+
+* You can monitor the migration by running the following command:
++
+[source,terminal]
+----
+$ oc adm upgrade
+----
++
+[IMPORTANT]
+====
+Machine launches may fail as the cluster settles into the new state. To notice and recover when machines fail to launch, we recommend deploying machine health checks. For more information about machine health checks and how to deploy them, see _About machine health checks_.
+====
++
+//commenting this section out until https://issues.redhat.com/browse/OCPBUGS-8256 is resolved:
+//For `oc get co`, expect `AVAILABLE=True`, `PROGRESSING=False`, and `DEGRADED=False` on all cluster Operators. 
++
+//For `oc get mcp`, expect `UPDATED=True`, `UPDATING=False`, and `DEGRADED=False` on all machine config pools. 
++
+//For `oc adm upgrade`, here is an example of a response: 
++
+//[source,terminal]
+//----
+//working towards ${VERSION}: 106 of 841 done (12% complete), waiting on etcd, kube-apiserver
+//----
++
+The migrations must be complete and all the cluster operators must be stable before you can add compute machine sets with different architectures to your cluster.
+
+

updating/migrating-to-multi-payload.adoc

@@ -0,0 +1,28 @@
+:_content-type: ASSEMBLY
+[id="migrating-clusters-to-multi-payload"]
+= Migrating to a cluster with multi-architecture compute machines
+include::_attributes/common-attributes.adoc[]
+:context: updating-clusters-overview
+
+toc::[]
+
+You can migrate your current cluster with single-architecture compute machines to a cluster with multi-architecture compute machines by updating to a multi-architecture, manifest-listed payload. This allows you to add mixed architecture compute nodes to your cluster. 
+
+For information about configuring your multi-architecture compute machines, see _Configuring multi-architecture compute machines on an {product-title} cluster_.
+
+[IMPORTANT]
+====
+Migration from a multi-architecture payload to a single-architecture payload is not supported. Once a cluster has transitioned to using a multi-architecture payload, it can no longer accept a single-architecture upgrade payload. 
+====
+
+include::modules/migrating-to-multi-arch-cli.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../post_installation_configuration/multi-architecture-configuration.adoc#multi-architecture-creating-arm64-bootimage_multi-architecture-configuration[Configuring multi-architecture compute machines on an {product-title} cluster]
+* xref:../updating/updating-cluster-within-minor.adoc#updating-cluster-within-minor[Updating a cluster using the web console]
+* xref:../updating/updating-cluster-cli.adoc#updating-cluster-cli[Updating a cluster using the CLI]
+* xref:../updating/index.adoc#understanding-clusterversion-conditiontypes_updating-clusters-overview[Understanding cluster version condition types]
+* xref:../updating/understanding-upgrade-channels-release.adoc#understanding-upgrade-channels-releases[Understanding upgrade channels and releases]
+* xref:../installing/installing-preparing.adoc#installing-preparing-install-manage[Selecting a cluster installation type]
+* xref:../machine_management/deploying-machine-health-checks.adoc#machine-health-checks-about_deploying-machine-health-checks[About machine health checks]