// Module included in the following assemblies:
//
// * hosted_control_planes/hcp-manage/hcp-manage-aws.adoc

:_mod-docs-content-type: PROCEDURE
[id="hcp-migrate-aws-single-to-multiarch_{context}"]
= Transitioning a hosted cluster from single-architecture to multi-architecture

[role="_abstract"]
You can transition your single-architecture 64-bit AMD hosted cluster to a multi-architecture hosted cluster on {aws-first} to reduce the cost of running workloads on your cluster.

For example, you can run existing workloads on 64-bit AMD while transitioning to 64-bit ARM and you can manage these workloads from a central Kubernetes cluster.

A single-architecture hosted cluster can manage node pools of only one particular CPU architecture. However, a multi-architecture hosted cluster can manage node pools with different CPU architectures. On {aws-short}, a multi-architecture hosted cluster can manage both 64-bit AMD and 64-bit ARM node pools.

.Prerequisites

* You installed an {product-title} management cluster for {aws-short} with the {mce}.
* You have an existing single-architecture hosted cluster that uses 64-bit AMD variant of the {product-title} release payload.
* You have an existing node pool that uses the same 64-bit AMD variant of the {product-title} release payload and is managed by an existing hosted cluster.
* You installed the following command-line tools:

** `oc`
** `kubectl`
** `hcp`
** `skopeo`

.Procedure

. Review an existing {product-title} release image of the single-architecture hosted cluster by running the following command:
+
[source,terminal]
----
$ oc get hostedcluster/<hosted_cluster_name> \
  -o jsonpath='{.spec.release.image}'
----
+
Replace `<hosted_cluster_name>` with your hosted cluster name.
+
.Example output
[source,terminal]
----
quay.io/openshift-release-dev/ocp-release:4.20.0-x86_64
----

. In your {product-title} release image, if you use the digest instead of a tag, find the multi-architecture tag version of your release image:

.. Set the `OCP_VERSION` environment variable for the {product-title} version by running the following command:
+
[source,terminal]
----
$ OCP_VERSION=$(oc image info quay.io/openshift-release-dev/ocp-release@sha256:ac78ebf77f95ab8ff52847ecd22592b545415e1ff6c7ff7f66bf81f158ae4f5e \
  -o jsonpath='{.config.config.Labels["io.openshift.release"]}')
----

.. Set the `MULTI_ARCH_TAG` environment variable for the multi-architecture tag version of your release image by running the following command:
+
[source,terminal]
----
$ MULTI_ARCH_TAG=$(skopeo inspect docker://quay.io/openshift-release-dev/ocp-release@sha256:ac78ebf77f95ab8ff52847ecd22592b545415e1ff6c7ff7f66bf81f158ae4f5e \
  | jq -r '.RepoTags' | sed 's/"//g' | sed 's/,//g' \
  | grep -w "$OCP_VERSION-multi$" | xargs)
----

.. Set the `IMAGE` environment variable for the multi-architecture release image name by running the following command:
+
[source,terminal]
----
$ IMAGE=quay.io/openshift-release-dev/ocp-release:$MULTI_ARCH_TAG
----

.. To see the list of multi-architecture image digests, run the following command:
+
[source,terminal]
----
$ oc image info $IMAGE
----
+
.Example output
[source,terminal]
----
OS            DIGEST
linux/amd64   sha256:b4c7a91802c09a5a748fe19ddd99a8ffab52d8a31db3a081a956a87f22a22ff8
linux/ppc64le sha256:66fda2ff6bd7704f1ba72be8bfe3e399c323de92262f594f8e482d110ec37388
linux/s390x   sha256:b1c1072dc639aaa2b50ec99b530012e3ceac19ddc28adcbcdc9643f2dfd14f34
linux/arm64   sha256:7b046404572ac96202d82b6cb029b421dddd40e88c73bbf35f602ffc13017f21
----

. Transition the hosted cluster from single-architecture to multi-architecture:

.. Set the multi-architecture {product-title} release image for the hosted cluster by ensuring that you use the same {product-title} version as the hosted cluster. Run the following command:
+
[source,terminal]
----
$ oc patch -n clusters hostedclusters/<hosted_cluster_name> -p \
  '{"spec":{"release":{"image":"quay.io/openshift-release-dev/ocp-release:<4.x.y>-multi"}}}' \
  --type=merge
----
+
Replace `<4.y.z>` with the supported {product-title} version that you use.

.. Confirm that the multi-architecture image is set in your hosted cluster by running the following command:
+
[source,terminal]
----
$ oc get hostedcluster/<hosted_cluster_name> \
  -o jsonpath='{.spec.release.image}'
----

. Check that the status of the `HostedControlPlane` resource is `Progressing` by running the following command:
+
[source,terminal]
----
$ oc get hostedcontrolplane -n <hosted_control_plane_namespace> -oyaml
----
+
.Example output
[source,yaml]
----
#...
  - lastTransitionTime: "2024-07-28T13:07:18Z"
    message: HostedCluster is deploying, upgrading, or reconfiguring
    observedGeneration: 5
    reason: Progressing
    status: "True"
    type: Progressing
#...
----

. Check that the status of the `HostedCluster` resource is `Progressing` by running the following command:
+
[source,terminal]
----
$ oc get hostedcluster <hosted_cluster_name> \
  -n <hosted_cluster_namespace> -oyaml
----

.Verification

* Verify that a node pool is using the multi-architecture release image in your `HostedControlPlane` resource by running the following command:
+
[source,terminal]
----
$ oc get hostedcontrolplane -n clusters-example -oyaml
----
+
.Example output
[source,yaml]
----
#...
version:
    availableUpdates: null
    desired:
      image: quay.io/openshift-release-dev/ocp-release:4.20.0-multi
      url: https://access.redhat.com/errata/RHBA-2024:4855
      version: 4.20.0
    history:
    - completionTime: "2024-07-28T13:10:58Z"
      image: quay.io/openshift-release-dev/ocp-release:4.20.0-multi
      startedTime: "2024-07-28T13:10:27Z"
      state: Completed
      verified: false
      version: 4.20.0
----

+
[NOTE]
====
The multi-architecture {product-title} release image is updated in your `HostedCluster`, `HostedControlPlane` resources, and hosted control plane pods. However, your existing node pools do not transition with the multi-architecture image automatically, because the release image transition is decoupled between the hosted cluster and node pools. You must create new node pools on your new multi-architecture hosted cluster.
====

.Next steps

* Create node pools on the multi-architecture hosted cluster.
