openshift · bscott-rh · May 26, 2026 · May 13, 2026
diff --git a/installing/installing_bare_metal/bare-metal-expanding-the-cluster.adoc b/installing/installing_bare_metal/bare-metal-expanding-the-cluster.adoc
@@ -6,6 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 After deploying a bare-metal cluster, you can use the following procedures to expand the number of worker nodes. Ensure that each prospective worker node meets the prerequisites.
 
 [NOTE]
@@ -18,8 +19,9 @@ include::modules/ipi-install-preparing-the-bare-metal-node.adoc[leveloffset=+1]
 [role="_additional-resources"]
 .Additional resources
 
-* See xref:../../installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc#configuring-host-network-interfaces-in-the-install-config-yaml-file_ipi-install-installation-workflow[Optional: Configuring host network interfaces in the install-config.yaml file] for details on configuring the NMState syntax.
-* See xref:../../scalability_and_performance/managing-bare-metal-hosts.adoc#automatically-scaling-machines-to-available-bare-metal-hosts_managing-bare-metal-hosts[Automatically scaling machines to the number of available bare-metal hosts] for details on automatically scaling machines.
+* xref:../../installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc#configuring-host-network-interfaces-in-the-install-config-yaml-file_ipi-install-installation-workflow[Optional: Configuring host network interfaces in the install-config.yaml file]
+* xref:../../scalability_and_performance/managing-bare-metal-hosts.adoc#automatically-scaling-machines-to-available-bare-metal-hosts_managing-bare-metal-hosts[Automatically scaling machines to the number of available bare-metal hosts]
+* xref:../../updating/updating_a_cluster/migrating-to-multi-payload.adoc#migrating-to-multi-payload[Migrating to a cluster with multi-architecture compute machines]
 
 include::modules/ipi-install-replacing-a-bare-metal-control-plane-node.adoc[leveloffset=+1]
 
@@ -30,7 +32,7 @@ include::modules/ipi-install-replacing-a-bare-metal-control-plane-node.adoc[leve
 
 * xref:../../backup_and_restore/control_plane_backup_and_restore/backing-up-etcd.adoc#backing-up-etcd-data_backup-etcd[Backing up etcd]
 
-* xref:../../installing/installing_bare_metal/bare-metal-postinstallation-configuration.adoc#bmo-config-using-bare-metal-operator_bare-metal-postinstallation-configuration[Configuration using the Bare Metal Operator]                                                                      
+* xref:../../installing/installing_bare_metal/bare-metal-postinstallation-configuration.adoc#bmo-config-using-bare-metal-operator_bare-metal-postinstallation-configuration[Configuration using the Bare Metal Operator]
 
 * xref:../../installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc#bmc-addressing_ipi-install-installation-workflow[BMC addressing]
 

diff --git a/modules/bmo-about-the-baremetalhost-resource.adoc b/modules/bmo-about-the-baremetalhost-resource.adoc
@@ -31,6 +31,9 @@ The `spec` section of the `BareMetalHost` resource defines the desired state of
 |====
 |Parameters |Description
 
+| `architecture`
+| Specifies the CPU architecture of the underlying machine. Supported values are `aarch64` and `x86_64`. If this value is not specified, it will default to the architecture of the control plane. You can add `aarch64` machines to a cluster with `x86_64` control plane machines, but you cannot add `x86_64` machines to a cluster with `aarch64` control plane machines.
+
 | `automatedCleaningMode`
 | An interface to enable or disable automated cleaning during provisioning and de-provisioning. When set to `disabled`, it skips automated cleaning. When set to `metadata`, automated cleaning is enabled. The default setting is `metadata`.
 

diff --git a/modules/ipi-install-preparing-the-bare-metal-node.adoc b/modules/ipi-install-preparing-the-bare-metal-node.adoc
@@ -6,9 +6,9 @@
 [id='preparing-the-bare-metal-node_{context}']
 = Preparing the bare metal node
 
+[role="_abstract"]
 To expand your cluster, you must provide the node with the relevant IP address. This can be done with a static configuration, or with a DHCP (Dynamic Host Configuration protocol) server. When expanding the cluster using a DHCP server, each node must have a DHCP reservation.
 
-
 [IMPORTANT]
 .Reserving IP addresses so they become static IP addresses
 ====
@@ -17,19 +17,15 @@ Some administrators prefer to use static IP addresses so that each node's IP add
 
 Preparing the bare metal node requires executing the following procedure from the provisioner node.
 
-.Procedure
+.Prerequisites
 
-. Get the `oc` binary:
-+
-[source,terminal]
-----
-$ curl -s https://mirror.openshift.com/pub/openshift-v4/clients/ocp/$VERSION/openshift-client-linux-$VERSION.tar.gz | tar zxvf - oc
-----
-+
-[source,terminal]
-----
-$ sudo cp oc /usr/local/bin
-----
+* You have downloaded the `oc` binary.
+* You have installed a bare-metal cluster.
+* If you intend to use DHCP to provide the new machine's IP address, you have a DHCP server on your network.
+* If you intend to use PXE to provide the boot image, you have a PXE server on your network.
+* If you intend to install a machine of a different architecture than the control plane, your cluster uses the multi-architecture release image.
+
+.Procedure
 
 . Power off the bare metal node by using the baseboard management controller (BMC), and ensure it is off.
 
@@ -110,6 +106,7 @@ spec:
   rootDeviceHints:
     deviceName: <root_device_hint> <11>
   preprovisioningNetworkDataName: openshift-worker-<num>-network-config-secret <12>
+  architecture: <architecture> <13>
 ----
 +
 --
@@ -138,6 +135,7 @@ spec:
 <10> Replace `<bmc_username>` and `<bmc_password>` with the string of the BMC user name and password.
 <11> Optional: Replace `<root_device_hint>` with a device path if you specify a root device hint.
 <12> Optional: If you have configured the network interface for the newly created node, provide the network configuration secret name in the `preprovisioningNetworkDataName` of the BareMetalHost CR.
+<13> Optional: If you want to deploy a machine of a different architecture than the control plane architecture, specify it here. Supported values are `aarch64` or `x86_64`.
 --
 
 * *DHCP configuration* `bmh.yaml`:
@@ -172,6 +170,7 @@ spec:
   rootDeviceHints:
     deviceName: <root_device_hint> <7>
   preprovisioningNetworkDataName: openshift-worker-<num>-network-config-secret <8>
+  architecture: <architecture> <9>
 ----
 +
 <1> Replace `<num>` for the worker number of the bare metal node in the `name` fields, the `credentialsName` field, and the `preprovisioningNetworkDataName` field.
@@ -189,6 +188,8 @@ spec:
 <7> Optional: Replace `<root_device_hint>` with a device path if you specify a root device hint.
 +
 <8> Optional: If you have configured the network interface for the newly created node, provide the network configuration secret name in the `preprovisioningNetworkDataName` of the BareMetalHost CR.
++
+<9> Optional: If you want to deploy a machine of a different architecture than the control plane architecture, specify it here. Supported values are `aarch64` or `x86_64`.
 
 +
 [NOTE]
@@ -228,8 +229,8 @@ Where `<num>` is the worker node number.
 NAME                    STATE       CONSUMER   ONLINE   ERROR
 openshift-worker-<num>  available              true
 ----
-+
-[NOTE]
-====
-To allow the worker node to join the cluster, scale the `machineset` object to the number of the `BareMetalHost` objects. You can scale nodes either manually or automatically. To scale nodes automatically, use the `metal3.io/autoscale-to-hosts` annotation for `machineset`.
-====
+
+. Add the new machine to the cluster by scaling the machine set.
+
+.. To manually scale the machine set, follow the procedure titled _Provisioning the bare metal node_.
+.. To automatically scale the machine set, follow the procedure titled _Automatically scaling machines to the number of available bare-metal hosts_ in the _Scalability and Performance_ section.