From b9e198b974504780b20490485a361cf37fdf3276 Mon Sep 17 00:00:00 2001 From: xenolinux Date: Fri, 27 Dec 2024 16:10:28 +0530 Subject: [PATCH] OSDOCS#11510: HCP: single-architecture to multi-architecture migration --- .../hcp-manage/hcp-manage-aws.adoc | 4 + .../hcp-migrate-aws-multiarch-nodepools.adoc | 68 +++++++ .../hcp-migrate-aws-single-to-multiarch.adoc | 168 ++++++++++++++++++ 3 files changed, 240 insertions(+) create mode 100644 modules/hcp-migrate-aws-multiarch-nodepools.adoc create mode 100644 modules/hcp-migrate-aws-single-to-multiarch.adoc diff --git a/hosted_control_planes/hcp-manage/hcp-manage-aws.adoc b/hosted_control_planes/hcp-manage/hcp-manage-aws.adoc index 79728f84ea13..6f2d04d4035e 100644 --- a/hosted_control_planes/hcp-manage/hcp-manage-aws.adoc +++ b/hosted_control_planes/hcp-manage/hcp-manage-aws.adoc @@ -32,3 +32,7 @@ include::modules/hcp-managed-aws-infra-separate.adoc[leveloffset=+2] include::modules/hcp-managed-aws-iam-separate.adoc[leveloffset=+2] include::modules/hcp-managed-aws-hc-separate.adoc[leveloffset=+2] + +include::modules/hcp-migrate-aws-single-to-multiarch.adoc[leveloffset=+1] + +include::modules/hcp-migrate-aws-multiarch-nodepools.adoc[leveloffset=+1] diff --git a/modules/hcp-migrate-aws-multiarch-nodepools.adoc b/modules/hcp-migrate-aws-multiarch-nodepools.adoc new file mode 100644 index 000000000000..4568515b014c --- /dev/null +++ b/modules/hcp-migrate-aws-multiarch-nodepools.adoc @@ -0,0 +1,68 @@ +// Module included in the following assemblies: +// +// * hosted_control_planes/hcp-manage/hcp-manage-aws.adoc + +:_mod-docs-content-type: PROCEDURE +[id="hcp-migrate-aws-multiarch-nodepools_{context}"] += Creating node pools on the multi-architecture hosted cluster + +After transitioning your hosted cluster from single-architecture to multi-architecture, you must create node pools manually. You can create node pools on compute machines based on 64-bit AMD and 64-bit ARM architectures. + +.Procedure + +. Create node pools based on 64-bit ARM architecture by entering the following command: ++ +[source,terminal] +---- +$ hcp create nodepool aws \ +--cluster-name \// <1> +--name \// <2> +--node-count= \// <3> +--arch arm64 +---- +<1> Replace `` with your hosted cluster name. +<2> Replace `` with your node pool name. +<3> Replace `` with integer for your node count, for example, `2`. + +. Create node pools based on 64-bit AMD architecture by entering the following command: ++ +[source,terminal] +---- +$ hcp create nodepool aws \ +--cluster-name \// <1> +--name \// +--node-count= \// +--arch amd64 +---- + +.Verification + +* Verify that the multi-architecture {product-title} release image is updated for your node pools by entering the following command: ++ +[source,terminal] +---- +$ oc get nodepool/ -oyaml +---- ++ +.Example output for 64-bit AMD node pools +[source,yaml] +---- +... +spec: + arch: amd64 +... + release: + image: quay.io/openshift-release-dev/ocp-release:<4.x.y>-multi <1> +---- +<1> Replace `<4.y.z>` with the supported {product-title} version that you use. ++ +.Example output for 64-bit ARM node pools +[source,yaml] +---- +... +spec: + arch: arm64 +... + release: + image: quay.io/openshift-release-dev/ocp-release:<4.x.y>-multi +---- diff --git a/modules/hcp-migrate-aws-single-to-multiarch.adoc b/modules/hcp-migrate-aws-single-to-multiarch.adoc new file mode 100644 index 000000000000..5fa0ca040d69 --- /dev/null +++ b/modules/hcp-migrate-aws-single-to-multiarch.adoc @@ -0,0 +1,168 @@ +// 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 + +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 your workloads. For example, you run your existing workloads on 64-bit AMD while transitioning it to 64-bit ARM. You can manage your 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 + +Before transitioning a hosted cluster from single-architecture to multi-architecture, review the following requirements: + +* You have installed an {product-title} management cluster for {aws-short} on {rh-rhacm-first} with the {mce}. +* You have an existing single-architecture hosted cluster that uses 64-bit AMD variant of the {product-title} release payload. +* An existing node pool that uses the same 64-bit AMD variant of the {product-title} release payload and is managed by the existing hosted cluster. +* Ensure that you installed the following command-line tools: + +** `oc` +** `kubectl` +** `hcp` +** `skopeo` + +.Procedure + +. Review the existing {product-title} release image of the single-architecture hosted cluster by running the following command: ++ +[source,terminal] +---- +$ oc get hostedcluster/ -o jsonpath='{.spec.release.image}' +---- ++ +.Example output +[source,terminal] +---- +quay.io/openshift-release-dev/ocp-release:4.16.5-x86_64 +---- + +. In your {product-title} release image, if you use the digest instead of the tag, find the multi-architecture tag version of your release image: + +.. Get the {product-title} version and save it in the `OCP_VERSION` variable 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"]}') +---- + +.. Get the multi-architecture tag version of your release image and save it in the `MULTI_ARCH_TAG` variable 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) +---- + +.. Save the multi-architecture release image name in the `IMAGE` variable by running the following command: ++ +[source,terminal] +---- +IMAGE=quay.io/openshift-release-dev/ocp-release:$MULTI_ARCH_TAG +---- + +.. Get the list of the multi-architecture image digests, by running 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 `multiArch` flag to `true` on your hosted cluster so that the hosted cluster can create and manage both 64-bit AMD and 64-bit ARM node pools. Run the following command: ++ +[source,terminal] +---- +$ oc patch -n clusters hostedclusters/ -p '{"spec":{"platform":{"aws":{"multiArch":true}}}}' --type=merge +---- + +.. Set the multi-architecture {product-title} release image for the hosted cluster. Ensure that you use the same {product-title} version as the hosted cluster. Run the following command: ++ +[source,terminal] +---- +$ oc patch -n clusters hostedclusters/ -p '{"spec":{"release":{"image":"quay.io/openshift-release-dev/ocp-release:<4.x.y>-multi"}}}' --type=merge <1> +---- +<1> Replace `<4.y.z>` with the supported {product-title} version that you use. + +.. Confirm that the multi-architecture image is set in the hosted cluster by running the following command: ++ +[source,terminal] +---- +$ oc get hostedcluster/ -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 -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 -n -oyaml +---- + +.Verification + +* Verify that the multi-architecture {product-title} release image is updated 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.x.y>-multi <1> + url: https://access.redhat.com/errata/RHBA-2024:4855 + version: 4.16.5 + history: + - completionTime: "2024-07-28T13:10:58Z" + image: quay.io/openshift-release-dev/ocp-release:<4.x.y>-multi + startedTime: "2024-07-28T13:10:27Z" + state: Completed + verified: false + version: <4.x.y> +---- +<1> Replace `<4.y.z>` with the supported {product-title} version that you use. + +[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 hosted cluster, hosted control plane, and node pool. You must create new node pools on your new multi-architecture hosted cluster. +==== + +.Next steps + +* Creating node pools on the multi-architecture hosted cluster