From acac47936c22ea01544c0eac42f5d1b8f3b7682b Mon Sep 17 00:00:00 2001 From: Michael Burke Date: Fri, 27 Mar 2026 13:40:53 -0400 Subject: [PATCH 1/5] OSDOCS Document how to perform boot image updates on marketplace clusters bare metal --- .../mco-update-boot-images-manual.adoc | 2 + ...mco-update-boot-images-ibm-bare-metal.adoc | 122 ++++++++++++++++++ 2 files changed, 124 insertions(+) create mode 100644 modules/mco-update-boot-images-ibm-bare-metal.adoc diff --git a/machine_configuration/mco-update-boot-images-manual.adoc b/machine_configuration/mco-update-boot-images-manual.adoc index 6277a056220b..c80369c457cd 100644 --- a/machine_configuration/mco-update-boot-images-manual.adoc +++ b/machine_configuration/mco-update-boot-images-manual.adoc @@ -14,6 +14,8 @@ For {product-title} platforms that do not support automatic boot image updating Red{nbsp}Hat does not support manually updating the boot image in control plane nodes. ==== +include::modules/mco-update-boot-images-ibm-bare-metal.adoc[leveloffset=+1] + include::modules/mco-update-boot-images-ibm-cloud.adoc[leveloffset=+1] include::modules/mco-update-boot-images-nutanix.adoc[leveloffset=+1] diff --git a/modules/mco-update-boot-images-ibm-bare-metal.adoc b/modules/mco-update-boot-images-ibm-bare-metal.adoc new file mode 100644 index 000000000000..51c18595e039 --- /dev/null +++ b/modules/mco-update-boot-images-ibm-bare-metal.adoc @@ -0,0 +1,122 @@ +// Module included in the following assemblies: +// +// * machine_configuration/mco-update-boot-images-manual.adoc + +:_mod-docs-content-type: PROCEDURE +[id="mco-update-boot-images-ibm-bare-metal_{context}"] += Manually updating the boot image on a bare-metal cluster + +[role="_abstract"] +For a bare-metal cluster, you can manually update the boot image for your cluster by configuring your machine sets to use the latest {product-title} image as the boot image to help ensure any new nodes can scale up properly. + +[NOTE] +==== +The standard boot image management feature is not supported for bare-metal clusters. +==== + +If your bare-metal cluster is running a {product-title} version 4.10 or later, boot images are kept current by the Cluster Version Operator (CVO) and are not at risk of skew. Skew enforcement is disabled for this cluster by default. You do not need to manually update the boot image. No further action on your part is required to maintain the boot image versioning. + +If your bare-metal cluster is running a {product-title} version 4.9 or earlier, the cluster is still using the legacy qcow2-based provisioning path. Boot images in clusters on this path are not managed by the CVO and could be significantly out of date. Follow the steps below to migrate the cluster to the `machine-os-images` provisioning path, which was introduced in {product-title} 4.10. This migration also updates the boot image to the latest {op-system-first} version. + +The following procedure enables the `install_coreos` deployment method and disables the qcow2 image cache. With these changes, the Cluster Baremetal Operator (CBO) will use the `machine-os-images` container from the release payload for new node provisioning. The cluster will have no skew risk, the same as a cluster at version 4.10 or later. Skew enforcement is automatically disabled after the migration is complete. + +[NOTE] +==== +Boot image updates are not required for Agent-based Installer clusters. The boot image for Agent-based Installer nodes is generated from the current release payload through the `oc adm node-image create` command and does not have skew issues. +==== + +.Prerequisites + +* You have completed the general boot image prerequisites as described in the "Prerequisites" section of the link:https://access.redhat.com/articles/7053165#prerequisites-2[{product-title} Boot Image Updates knowledgebase article]. + +* You have the {oc-first} installed. + +* A `BareMetalHost` object is present in the `openshift-machine-api` namespace. A new physical host must be registered and in `available` state so that you can scale a new machine to verify the procedure. + +.Procedure + +. Determine if the boot image in your cluster needs to be updated: + +.. Check whether your cluster is using the legacy boot image provisioning path by running the following command: ++ +[source,terminal] +---- +$ oc get provisioning provisioning-configuration \ + -o jsonpath='{.spec.provisioningOSDownloadURL}' +---- ++ +* If the output is non-empty, your cluster is running a {product-title} version 4.9 or earlier. Boot images are not managed by the the Cluster Version Operator (CVO) and could be significantly out of date. Follow the steps below to migrate to the current provisioning path. ++ +* If the output is empty, your cluster is running a {product-title} version 4.10 or later. Boot images are kept current by the Cluster Version Operator (CVO) and are not at risk of skew. Skew enforcement should be disabled for this cluster. No further action on your part is required to maintain the boot image versioning. + +. Clear the legacy image fields and enable the `install_coreos` deployment method: + +.. Migrate each machine set to the `machine-os-images` provisioning path by running the follwing command: ++ +[source,terminal] +---- +$ oc patch machineset -n openshift-machine-api --type merge \ + -p '{"spec":{"template":{"spec":{"providerSpec":{"value":{"customDeploy":{"method":"install_coreos"},"image":{"url":"","checksum":""}}}}}}}' +---- ++ +Replace `` with the name of your machine set. + +.. Clear the legacy download URL by running the following command: ++ +[source,terminal] +---- +$ oc patch provisioning provisioning-configuration --type=merge -p '{"spec":{"provisioningOSDownloadURL":""}}' +---- + +.Verification + +. Scale up a machine set to check that the new node is using the new boot image: + +.. Increase the machine set replicas by one to trigger a new machine by running the following command: ++ +[source,terminal] +---- +$ oc scale --replicas= machineset -n openshift-machine-api +---- +where: + +``:: Specifies the total number of replicas, including any existing replicas, that you want for this machine set. +``:: Specifies the name of the machine set to scale. + +.. Optional: View the status of the machine set as it provisions by running the following command: ++ +[source,terminal] +---- +$ oc get machines.machine.openshift.io -n openshift-machine-api -w +---- ++ +It can take several minutes for the machine set to achieve the `Running` state. + +.. Verify that the new node has been created and is in the `Ready` state by running the following command: ++ +[source,terminal] +---- +$ oc get nodes +---- + +. Verify that the new node is using the new boot image by running the following command: ++ +[source,terminal] +---- +$ oc debug node/ -- chroot /host cat /sysroot/.coreos-aleph-version.json +---- ++ +Replace `` with the name of your new node. ++ +.Example output +[source,terminal] +---- +{ +# ... + "ref": "docker://ostree-image-signed:oci-archive:/rhcos-9.6.20251212-1-ostree.x86_64.ociarchive", + "version": "9.6.20251212-1" +} +---- +where: + +`version`:: Specifies the boot image version. From 18bcddbeb2d06599ef32e2e94c746534171882e4 Mon Sep 17 00:00:00 2001 From: Michael Burke Date: Fri, 27 Mar 2026 16:06:19 -0400 Subject: [PATCH 2/5] edits --- modules/mco-update-boot-images-ibm-bare-metal.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modules/mco-update-boot-images-ibm-bare-metal.adoc b/modules/mco-update-boot-images-ibm-bare-metal.adoc index 51c18595e039..65bd661b42ee 100644 --- a/modules/mco-update-boot-images-ibm-bare-metal.adoc +++ b/modules/mco-update-boot-images-ibm-bare-metal.adoc @@ -31,7 +31,7 @@ Boot image updates are not required for Agent-based Installer clusters. The boot * You have the {oc-first} installed. -* A `BareMetalHost` object is present in the `openshift-machine-api` namespace. A new physical host must be registered and in `available` state so that you can scale a new machine to verify the procedure. +* A new physical host must be registered and in the `available` state and an associated `BareMetalHost` object must be present in the `openshift-machine-api` namespace so that you can scale a new machine to verify the procedure. .Procedure @@ -67,6 +67,8 @@ Replace `` with the name of your machine set. ---- $ oc patch provisioning provisioning-configuration --type=merge -p '{"spec":{"provisioningOSDownloadURL":""}}' ---- ++ + .Verification From 2707d4173e3f282d3e1338a0d79f292508ea37f8 Mon Sep 17 00:00:00 2001 From: Michael Burke Date: Fri, 27 Mar 2026 16:59:36 -0400 Subject: [PATCH 3/5] proofread --- modules/mco-update-boot-images-ibm-bare-metal.adoc | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/modules/mco-update-boot-images-ibm-bare-metal.adoc b/modules/mco-update-boot-images-ibm-bare-metal.adoc index 65bd661b42ee..d3e05a226338 100644 --- a/modules/mco-update-boot-images-ibm-bare-metal.adoc +++ b/modules/mco-update-boot-images-ibm-bare-metal.adoc @@ -35,9 +35,7 @@ Boot image updates are not required for Agent-based Installer clusters. The boot .Procedure -. Determine if the boot image in your cluster needs to be updated: - -.. Check whether your cluster is using the legacy boot image provisioning path by running the following command: +. Check whether your cluster is using the legacy boot image provisioning path by running the following command: + [source,terminal] ---- @@ -45,9 +43,9 @@ $ oc get provisioning provisioning-configuration \ -o jsonpath='{.spec.provisioningOSDownloadURL}' ---- + -* If the output is non-empty, your cluster is running a {product-title} version 4.9 or earlier. Boot images are not managed by the the Cluster Version Operator (CVO) and could be significantly out of date. Follow the steps below to migrate to the current provisioning path. +* If the output is non-empty, your cluster is running an {product-title} version 4.9 or earlier. Boot images are not managed by the the Cluster Version Operator (CVO) and could be significantly out of date. Follow the steps in this procedure to migrate to the current provisioning path. + -* If the output is empty, your cluster is running a {product-title} version 4.10 or later. Boot images are kept current by the Cluster Version Operator (CVO) and are not at risk of skew. Skew enforcement should be disabled for this cluster. No further action on your part is required to maintain the boot image versioning. +* If the output is empty, your cluster is running an {product-title} version 4.10 or later. Boot images are kept current by the Cluster Version Operator (CVO) and are not at risk of skew. Skew enforcement should be disabled for this cluster. No further action on your part is required to maintain the boot image versioning. . Clear the legacy image fields and enable the `install_coreos` deployment method: @@ -68,7 +66,7 @@ Replace `` with the name of your machine set. $ oc patch provisioning provisioning-configuration --type=merge -p '{"spec":{"provisioningOSDownloadURL":""}}' ---- + - +This process updates the boot image to match the current cluster version. .Verification From 07db11a12e70f95a337d5fd358e0ff853efef77d Mon Sep 17 00:00:00 2001 From: Michael Burke Date: Mon, 30 Mar 2026 14:55:48 -0400 Subject: [PATCH 4/5] edits per djoshy --- modules/mco-update-boot-images-ibm-bare-metal.adoc | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/modules/mco-update-boot-images-ibm-bare-metal.adoc b/modules/mco-update-boot-images-ibm-bare-metal.adoc index d3e05a226338..4a6719b0cfa9 100644 --- a/modules/mco-update-boot-images-ibm-bare-metal.adoc +++ b/modules/mco-update-boot-images-ibm-bare-metal.adoc @@ -7,16 +7,16 @@ = Manually updating the boot image on a bare-metal cluster [role="_abstract"] -For a bare-metal cluster, you can manually update the boot image for your cluster by configuring your machine sets to use the latest {product-title} image as the boot image to help ensure any new nodes can scale up properly. +For a bare-metal cluster that was installed with {product-title} version 4.9 or earlier, you need to configure how the cluster provisions new nodes in order to update the boot images used with those nodes. Using an up-to-date boot image ensures that any new nodes can scale up properly. [NOTE] ==== The standard boot image management feature is not supported for bare-metal clusters. ==== -If your bare-metal cluster is running a {product-title} version 4.10 or later, boot images are kept current by the Cluster Version Operator (CVO) and are not at risk of skew. Skew enforcement is disabled for this cluster by default. You do not need to manually update the boot image. No further action on your part is required to maintain the boot image versioning. +If your bare-metal cluster was installed with {product-title} version 4.10 or later, boot images are kept current by the Cluster Version Operator (CVO) and are not at risk of skew. Skew enforcement is disabled for the cluster by default. No further action on your part is required to maintain the boot image versioning. -If your bare-metal cluster is running a {product-title} version 4.9 or earlier, the cluster is still using the legacy qcow2-based provisioning path. Boot images in clusters on this path are not managed by the CVO and could be significantly out of date. Follow the steps below to migrate the cluster to the `machine-os-images` provisioning path, which was introduced in {product-title} 4.10. This migration also updates the boot image to the latest {op-system-first} version. +If your bare-metal cluster was installed with {product-title} version 4.9 or earlier, the cluster is using the legacy qcow2-based provisioning method. Boot images in these clusters are not managed by the CVO and could be significantly out of date. Follow the steps below to migrate the cluster to use the `machine-os-images` provisioning method, which was introduced in {product-title} 4.10. This migration ensures that the cluster always uses the release version as the boot image when a scale-up is taking place. The following procedure enables the `install_coreos` deployment method and disables the qcow2 image cache. With these changes, the Cluster Baremetal Operator (CBO) will use the `machine-os-images` container from the release payload for new node provisioning. The cluster will have no skew risk, the same as a cluster at version 4.10 or later. Skew enforcement is automatically disabled after the migration is complete. @@ -43,9 +43,9 @@ $ oc get provisioning provisioning-configuration \ -o jsonpath='{.spec.provisioningOSDownloadURL}' ---- + -* If the output is non-empty, your cluster is running an {product-title} version 4.9 or earlier. Boot images are not managed by the the Cluster Version Operator (CVO) and could be significantly out of date. Follow the steps in this procedure to migrate to the current provisioning path. +* If the output is non-empty, your cluster was installed with {product-title} version 4.9 or earlier. Boot images are not managed by the the Cluster Version Operator (CVO) and could be significantly out of date. Follow the steps in this procedure to migrate to the current provisioning path. + -* If the output is empty, your cluster is running an {product-title} version 4.10 or later. Boot images are kept current by the Cluster Version Operator (CVO) and are not at risk of skew. Skew enforcement should be disabled for this cluster. No further action on your part is required to maintain the boot image versioning. +* If the output is empty, your cluster was installed with {product-title} version 4.10 or later. Boot images are kept current by the Cluster Version Operator (CVO) and are not at risk of skew. Skew enforcement should be disabled for this cluster. No further action on your part is required to maintain the boot image versioning. . Clear the legacy image fields and enable the `install_coreos` deployment method: @@ -66,7 +66,9 @@ Replace `` with the name of your machine set. $ oc patch provisioning provisioning-configuration --type=merge -p '{"spec":{"provisioningOSDownloadURL":""}}' ---- + -This process updates the boot image to match the current cluster version. +This process migrates the cluster to the `machine-os-images` provisioning method, which ensure that the latest boot image is used for scaling nodes. + + .Verification From 866fd663c9726a888644da44c43eee7f3c467c69 Mon Sep 17 00:00:00 2001 From: Michael Burke Date: Mon, 30 Mar 2026 15:01:09 -0400 Subject: [PATCH 5/5] edits per djoshy --- modules/mco-update-boot-images-ibm-bare-metal.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/mco-update-boot-images-ibm-bare-metal.adoc b/modules/mco-update-boot-images-ibm-bare-metal.adoc index 4a6719b0cfa9..381bae4bcc84 100644 --- a/modules/mco-update-boot-images-ibm-bare-metal.adoc +++ b/modules/mco-update-boot-images-ibm-bare-metal.adoc @@ -7,7 +7,7 @@ = Manually updating the boot image on a bare-metal cluster [role="_abstract"] -For a bare-metal cluster that was installed with {product-title} version 4.9 or earlier, you need to configure how the cluster provisions new nodes in order to update the boot images used with those nodes. Using an up-to-date boot image ensures that any new nodes can scale up properly. +For a bare-metal cluster that was installed with {product-title} version 4.9 or earlier, you need to change how the cluster provisions new nodes in order to update the boot image used with those nodes. Using an up-to-date boot image ensures that any new nodes can scale up properly. [NOTE] ====