OpenShift Container Platform

Transitioning a hosted cluster from single-architecture to multi-architecture

You can transition your single-architecture 64-bit AMD hosted cluster to a multi-architecture hosted cluster on Amazon Web Services (AWS) 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, a multi-architecture hosted cluster can manage both 64-bit AMD and 64-bit ARM node pools.

Prerequisites

You installed an OpenShift Container Platform management cluster for AWS with the multicluster engine for Kubernetes Operator.
You have an existing single-architecture hosted cluster that uses 64-bit AMD variant of the OpenShift Container Platform release payload.
You have an existing node pool that uses the same 64-bit AMD variant of the OpenShift Container Platform 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 OpenShift Container Platform release image of the single-architecture hosted cluster by running the following command:
```
$ oc get hostedcluster/<hosted_cluster_name> \
  -o jsonpath='{.spec.release.image}'
```
Replace <hosted_cluster_name> with your hosted cluster name.
Example output
```
quay.io/openshift-release-dev/ocp-release:4.20.0-x86_64
```

In your OpenShift Container Platform 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 OpenShift Container Platform version by running the following command:

$ 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:

$ 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:
```
$ IMAGE=quay.io/openshift-release-dev/ocp-release:$MULTI_ARCH_TAG
```

To see the list of multi-architecture image digests, run the following command:

$ oc image info $IMAGE

Example output

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:
1. Set the multi-architecture OpenShift Container Platform release image for the hosted cluster by ensuring that you use the same OpenShift Container Platform version as the hosted cluster. Run the following command:
  $ 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 OpenShift Container Platform version that you use.
2. Confirm that the multi-architecture image is set in your hosted cluster by running the following command:
  $ 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:

$ oc get hostedcontrolplane -n <hosted_control_plane_namespace> -oyaml

Example output

#...
  - 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:
```
$ 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:

$ oc get hostedcontrolplane -n clusters-example -oyaml

Example output

#...
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

The multi-architecture OpenShift Container Platform 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.