openshift · dfitzmau · Jul 9, 2026
diff --git a/modules/installation-approve-csrs.adoc b/modules/installation-approve-csrs.adoc
@@ -75,7 +75,7 @@ The output lists all of the machines that you created.
 +
 [NOTE]
 ====
-The preceding output might not include the compute nodes, also known as worker nodes, until some CSRs are approved.
+The preceding output might not include the compute nodes, also known as compute nodes, until some CSRs are approved.
 ====
 
 . Review the pending CSRs and ensure that you see the client requests with the `Pending` or `Approved` status for each machine that you added to the cluster:
@@ -116,7 +116,7 @@ endif::ibm-z,ibm-z-kvm[]
 +
 [NOTE]
 ====
-You must approve your CSRs within an hour of adding the machines to the cluster. If you do not approve them within an hour, the certificates will rotate, and more than two certificates will be present for each node. You must approve all of these certificates. After the client CSR is approved, the Kubelet creates a secondary CSR for the serving certificate, which requires manual approval. Then, subsequent serving certificate renewal requests are automatically approved by the `machine-approver` if the Kubelet requests a new certificate with identical parameters.
+You must approve your CSRs within an hour of adding the machines to the cluster. If you do not approve them within an hour, the certificates will rotate, and more than two certificates will be present for each node. You must approve all of these certificates. After the client CSR is approved, the Kubelet creates a secondary CSR for the serving certificate, which requires manual approval. The subsequent serving certificate renewal requests are then automatically approved by the `machine-approver` if the Kubelet requests a new certificate with identical parameters.
 ====
 +
 [NOTE]
@@ -144,8 +144,7 @@ $ oc get csr -o go-template='{{range .items}}{{if not .status}}{{.metadata.name}
 +
 [NOTE]
 ====
-Some Operators might not become available until some CSRs are approved.
-Each node submits two CSRs, so you may need to run the command to approve CSRs multiple times.
+Some Operators might not become available until some CSRs are approved. Each node submits two CSRs, so you may need to run the command to approve CSRs multiple times.
 ====
 
 . Now that your client requests are approved, you must review the server requests for each machine that you added to the cluster:
@@ -228,7 +227,7 @@ endif::ibm-power[]
 +
 [NOTE]
 ====
-It can take a few minutes after approval of the server CSRs for the machines to transition to the `Ready` status.
+You might need to wait a few minutes after approval of the server CSRs for the machines to transition to the `Ready` status.
 ====
 
 ifeval::["{context}" == "installing-ibm-z"]

diff --git a/modules/machine-user-infra-machines-ibm-z-kvm.adoc b/modules/machine-user-infra-machines-ibm-z-kvm.adoc
@@ -6,6 +6,7 @@
 [id="machine-user-infra-machines-ibm-z-kvm_{context}"]
 = Creating {op-system} machines using `virt-install`
 
+[role="_abstract"]
 You can create more {op-system-first} compute machines for your cluster by using `virt-install`.
 
 .Prerequisites
@@ -57,31 +58,33 @@ $ curl -LO $(oc -n openshift-machine-config-operator get configmap/coreos-bootim
 
 . Create the new KVM guest nodes using the {op-system-base} `kernel`, `initramfs`, and Ignition files; the new disk image; and adjusted parm line arguments.
 +
---
 [source,terminal]
 ----
 $ virt-install \
    --connect qemu:///system \
    --name <vm_name> \
    --autostart \
-   --os-variant rhel9.4 \ <1>
+   --os-variant rhel9.4 \
    --cpu host \
    --vcpus <vcpus> \
    --memory <memory_mb> \
    --disk <vm_name>.qcow2,size=<image_size> \
    --network network=<virt_network_parm> \
-   --location <media_location>,kernel=<rhcos_kernel>,initrd=<rhcos_initrd> \ <2>
+   --location <media_location>,kernel=<rhcos_kernel>,initrd=<rhcos_initrd> \
    --extra-args "rd.neednet=1" \
    --extra-args "coreos.inst.install_dev=/dev/vda" \
-   --extra-args "coreos.inst.ignition_url=http://<http_server>/worker.ign " \ <3>
-   --extra-args "coreos.live.rootfs_url=http://<http_server>/rhcos-<version>-live-rootfs.<architecture>.img" \ <4>
-   --extra-args "ip=<ip>::<gateway>:<netmask>:<hostname>::none" \ <5>
+   --extra-args "coreos.inst.ignition_url=http://<http_server>/worker.ign " \
+   --extra-args "coreos.live.rootfs_url=http://<http_server>/rhcos-<version>-live-rootfs.<architecture>.img" \
+   --extra-args "ip=<ip>::<gateway>:<netmask>:<hostname>::none" \
    --extra-args "nameserver=<dns>" \
    --extra-args "console=ttysclp0" \
    --noautoconsole \
    --wait
 ----
-<1> For `os-variant`, specify the {op-system-base} version for the {op-system} compute machine. `rhel9.4` is the recommended version. To query the supported {op-system-base} version of your operating system, run the following command:
++
+where:
++
+`os-variant rhel9.4`:: Specifies the {op-system-base} version for the {op-system} compute machine. `rhel9.4` is the recommended version. To query the supported {op-system-base} version of your operating system, run the following command:
 +
 [source,terminal]
 ----
@@ -93,15 +96,14 @@ $ osinfo-query os -f short-id
 The `os-variant` is case sensitive.
 ====
 +
-<2> For `--location`, specify the location of the kernel/initrd on the HTTP or HTTPS server.
-<3> Specify the location of the `worker.ign` config file. Only HTTP and HTTPS protocols are supported.
-<4> Specify the location of the `rootfs` artifact for the `kernel` and `initramfs` you are booting. Only HTTP and HTTPS protocols are supported
-<5> Optional: For `hostname`, specify the fully qualified hostname of the client machine.
---
+`location`:: Specifies the location of the kernel/initrd on the HTTP or HTTPS server.
+`coreos.inst.ignition_url`:: Specifies the location of the `worker.ign` config file. Only HTTP and HTTPS protocols are supported.
+`coreos.live.rootfs_url`:: Specifies the location of the `rootfs` artifact for the `kernel` and `initramfs` you are booting. Only HTTP and HTTPS protocols are supported
+`hostname`:: Optional parameter. Specifies the fully qualified hostname of the client machine.
 +
 [NOTE]
 ====
 If you are using HAProxy as a load balancer, update your HAProxy rules for `ingress-router-443` and `ingress-router-80` in the `/etc/haproxy/haproxy.cfg` configuration file.
 ====
 
-. Continue to create more compute machines for your cluster.
+. Continue to create more compute machines for your cluster.
diff --git a/modules/machine-user-infra-machines-iso.adoc b/modules/machine-user-infra-machines-iso.adoc
@@ -26,7 +26,7 @@ endif::ibm-power[]
 .Prerequisites
 
 * Obtain the URL of the Ignition config file for the compute machines for your cluster. You uploaded this file to your HTTP server during installation.
-* You must have the OpenShift CLI (`oc`)  installed.
+* You must have the {oc-first} installed.
 
 .Procedure
 
@@ -54,7 +54,9 @@ RHCOS_VHD_ORIGIN_URL=$(oc -n openshift-machine-config-operator get configmap/cor
 ----
 
 . Use the ISO file to install {op-system} on more compute machines. Use the same method that you used when you created machines before you installed the cluster:
++
 ** Burn the ISO image to a disk and boot it directly.
++
 ** Use ISO redirection with a LOM interface.
 
 . Boot the {op-system} ISO image without specifying any options, or interrupting the live boot sequence. Wait for the installer to boot into a shell prompt in the {op-system} live environment.

diff --git a/modules/machine-user-infra-machines-pxe.adoc b/modules/machine-user-infra-machines-pxe.adoc
@@ -14,7 +14,7 @@ endif::[]
 = Creating {op-system} machines by PXE or iPXE booting
 
 [role="_abstract"]
-You can create more {op-system-first} compute machines for your bare metal cluster by using PXE or iPXE booting.
+You can create more {op-system-first} compute machines for your bare-metal cluster by using PXE or iPXE booting.
 
 .Prerequisites
 
@@ -26,7 +26,7 @@ You can create more {op-system-first} compute machines for your bare metal clust
 .Procedure
 
 . Confirm that your PXE or iPXE installation for the {op-system} images is correct.
-
++
 ** For PXE:
 +
 ----
@@ -50,7 +50,7 @@ where:
 ====
 This configuration does not enable serial console access on machines with a graphical console. To configure a different console, add one or more `console=` arguments to the `APPEND` line. For example, add `console=tty0 console=ttyS0` to set the first PC serial port as the primary console and the graphical console as a secondary console. For more information on setting up a serial terminal and/or console in {op-system}, see "How does one set up a serial terminal and/or console in Red Hat Enterprise Linux?".
 ====
-
++
 ifndef::ibm-power[]
 ** For iPXE (`x86_64` + `aarch64`):
 endif::ibm-power[]
@@ -74,8 +74,7 @@ where:
 +
 [NOTE]
 ====
-* If you use multiple NICs, specify a single interface in the `ip` option.
-For example, to use DHCP on a NIC named `eno1`, set `ip=eno1:dhcp`.
+* If you use multiple NICs, specify a single interface in the `ip` option. For example, to use DHCP on a NIC named `eno1`, set `ip=eno1:dhcp`.
 +
 * This configuration does not enable serial console access on machines with a graphical console To configure a different console, add one or more `console=` arguments to the `kernel` line. For example, add `console=tty0 console=ttyS0` to set the first PC serial port as the primary console and the graphical console as a secondary console. For more information on setting up a serial terminal and/or console in {op-system}, see "How does one set up a serial terminal and/or console in Red Hat Enterprise Linux?" in the Additional resources section and "Enabling the serial console for PXE and ISO installation" in the "Advanced {op-system} installation configuration" section.
 ====
@@ -89,7 +88,7 @@ ifdef::ibm-power[]
 To network boot the CoreOS `kernel` on `ppc64le` architecture, you need to use a version of iPXE build with the `IMAGE_GZIP` option enabled. For more information, see "IMAGE_GZIP option in iPXE".
 endif::ibm-power[]
 ====
-
++
 ifndef::ibm-power[]
 ** For PXE (with UEFI and GRUB as second stage) on `aarch64`:
 endif::ibm-power[]
@@ -113,10 +112,9 @@ where:
 +
 [NOTE]
 ====
-If you use multiple NICs, specify a single interface in the `ip` option.
-For example, to use DHCP on a NIC named `eno1`, set `ip=eno1:dhcp`.
+If you use multiple NICs, specify a single interface in the `ip` option. For example, to use DHCP on a NIC named `eno1`, set `ip=eno1:dhcp`.
 ====
-+
+
 . Use the PXE or iPXE infrastructure to create the required compute machines for your cluster.
 
 ifeval::["{context}" == "creating-multi-arch-compute-nodes-ibm-power"]

diff --git a/...ng-multi-arch-compute-machines/creating-multi-arch-compute-nodes-ibm-power.adoc b/...ng-multi-arch-compute-machines/creating-multi-arch-compute-nodes-ibm-power.adoc
@@ -6,25 +6,36 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 To create a cluster with multi-architecture compute machines on {ibm-power-name} (`ppc64le`), you must have an existing single-architecture (`x86_64`) cluster. You can then add `ppc64le` compute machines to your {product-title} cluster.
 
 [IMPORTANT]
 ====
-Before you can add `ppc64le` nodes to your cluster, you must upgrade your cluster to one that uses the multi-architecture payload. For more information on migrating to the multi-architecture payload, see xref:../../updating/updating_a_cluster/migrating-to-multi-payload.adoc#migrating-to-multi-payload[Migrating to a cluster with multi-architecture compute machines].
+Before you can add `ppc64le` nodes to your cluster, you must upgrade your cluster to one that uses the multi-architecture payload. For more information on migrating to the multi-architecture payload, see "Migrating to a cluster with multi-architecture compute machines".
 ====
 
-The following procedures explain how to create a {op-system} compute machine using an ISO image or network PXE booting. This will allow you to add `ppc64le` nodes to your cluster and deploy a cluster with multi-architecture compute machines.
+The following procedures explain how to complete the following tasks:
 
-To create an {ibm-power-name} (`ppc64le`) cluster with multi-architecture compute machines on `x86_64`, follow the instructions for
-xref:../../installing/installing_ibm_power/preparing-to-install-on-ibm-power.adoc#preparing-to-install-on-ibm-power[Installing a cluster on {ibm-power-name}]. You can then add `x86_64` compute machines as described in xref:./creating-multi-arch-compute-nodes-bare-metal.adoc#creating-multi-arch-compute-nodes-bare-metal[Creating a cluster with multi-architecture compute machines on bare metal, {ibm-power-title}, or {ibm-z-title}].
+* Create a {op-system} compute machine by using an ISO image or network PXE booting. 
+* Add `ppc64le` nodes to your cluster and deploy a cluster with multi-architecture compute machines.
+
+To create an {ibm-power-name} (`ppc64le`) cluster with multi-architecture compute machines on `x86_64`, follow the instructions for "Installing a cluster on {ibm-power-name}". You can then add `x86_64` compute machines as described in "Creating a cluster with multi-architecture compute machines on bare metal, {ibm-power-title}, or {ibm-z-title}".
 
 [NOTE]
 ====
-Before adding a secondary architecture node to your cluster, it is recommended to install the Multiarch Tuning Operator, and deploy a `ClusterPodPlacementConfig` object. For more information, see xref:../../post_installation_configuration/configuring-multi-arch-compute-machines/multiarch-tuning-operator.adoc#multiarch-tuning-operator[Managing workloads on multi-architecture clusters by using the Multiarch Tuning Operator].
+Before adding a secondary architecture node to your cluster, Red Hat recommends that you install the Multiarch Tuning Operator, and deploy a `ClusterPodPlacementConfig` object. For more information, see "Managing workloads on multi-architecture clusters by using the Multiarch Tuning Operator".
 ====
 
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../updating/updating_a_cluster/migrating-to-multi-payload.adoc#migrating-to-multi-payload[Migrating to a cluster with multi-architecture compute machines]
+* xref:../../installing/installing_ibm_power/preparing-to-install-on-ibm-power.adoc#preparing-to-install-on-ibm-power[Installing a cluster on {ibm-power-name}]
+* xref:./creating-multi-arch-compute-nodes-bare-metal.adoc#creating-multi-arch-compute-nodes-bare-metal[Creating a cluster with multi-architecture compute machines on bare metal, {ibm-power-title}, or {ibm-z-title}]
+* xref:../../post_installation_configuration/configuring-multi-arch-compute-machines/multiarch-tuning-operator.adoc#multiarch-tuning-operator[Managing workloads on multi-architecture clusters by using the Multiarch Tuning Operator]
+
 include::modules/machine-user-infra-machines-iso.adoc[leveloffset=+1]
 
 include::modules/machine-user-infra-machines-pxe.adoc[leveloffset=+1]
 
-include::modules/installation-approve-csrs.adoc[leveloffset=+1]
+include::modules/installation-approve-csrs.adoc[leveloffset=+1]
diff --git a/...ng-multi-arch-compute-machines/creating-multi-arch-compute-nodes-ibm-z-kvm.adoc b/...ng-multi-arch-compute-machines/creating-multi-arch-compute-nodes-ibm-z-kvm.adoc
@@ -6,20 +6,32 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 To create a cluster with multi-architecture compute machines on {ibm-z-name} and {ibm-linuxone-name} (`s390x`) with {op-system-base} KVM, you must have an existing single-architecture `x86_64` cluster. You can then add `s390x` compute machines to your {product-title} cluster.
 
-Before you can add `s390x` nodes to your cluster, you must upgrade your cluster to one that uses the multi-architecture payload. For more information on migrating to the multi-architecture payload, see xref:../../updating/updating_a_cluster/migrating-to-multi-payload.adoc#migrating-to-multi-payload[Migrating to a cluster with multi-architecture compute machines].
+Before you can add `s390x` nodes to your cluster, you must upgrade your cluster to one that uses the multi-architecture payload. For more information on migrating to the multi-architecture payload, see "Migrating to a cluster with multi-architecture compute machines".
 
 The following procedures explain how to create a {op-system} compute machine using a {op-system-base} KVM instance. This will allow you to add `s390x` nodes to your cluster and deploy a cluster with multi-architecture compute machines.
 
-To create an {ibm-z-name} or {ibm-linuxone-name} (`s390x`) cluster with multi-architecture compute machines on `x86_64`, follow the instructions for
-xref:../../installing/installing_ibm_z/preparing-to-install-on-ibm-z.adoc#preparing-to-install-on-ibm-z[Installing a cluster on {ibm-z-name} and {ibm-linuxone-name}]. You can then add `x86_64` compute machines as described in xref:./creating-multi-arch-compute-nodes-bare-metal.adoc#creating-multi-arch-compute-nodes-bare-metal[Creating a cluster with multi-architecture compute machines on bare metal, {ibm-power-title}, or {ibm-z-title}].
+To create an {ibm-z-name} or {ibm-linuxone-name} (`s390x`) cluster with multi-architecture compute machines on `x86_64`, follow the instructions for "Installing a cluster on {ibm-z-name} and {ibm-linuxone-name}". You can then add `x86_64` compute machines as described in "Creating a cluster with multi-architecture compute machines on bare metal, {ibm-power-title}, or {ibm-z-title}".
 
 [NOTE]
 ====
-Before adding a secondary architecture node to your cluster, it is recommended to install the Multiarch Tuning Operator, and deploy a `ClusterPodPlacementConfig` object. For more information, see xref:../../post_installation_configuration/configuring-multi-arch-compute-machines/multiarch-tuning-operator.adoc#multiarch-tuning-operator[Managing workloads on multi-architecture clusters by using the Multiarch Tuning Operator].
+Before adding a secondary architecture node to your cluster, install the Multiarch Tuning Operator and then deploy a `ClusterPodPlacementConfig` object. For more information, see "Managing workloads on multi-architecture clusters by using the Multiarch Tuning Operator".
 ====
 
 include::modules/machine-user-infra-machines-ibm-z-kvm.adoc[leveloffset=+1]
 
-include::modules/installation-approve-csrs.adoc[leveloffset=+1]
+include::modules/installation-approve-csrs.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
+
+* xref:../../updating/updating_a_cluster/migrating-to-multi-payload.adoc#migrating-to-multi-payload[Migrating to a cluster with multi-architecture compute machines]
+
+* xref:../../installing/installing_ibm_z/preparing-to-install-on-ibm-z.adoc#preparing-to-install-on-ibm-z[Installing a cluster on {ibm-z-name} and {ibm-linuxone-name}]
+
+* xref:./creating-multi-arch-compute-nodes-bare-metal.adoc#creating-multi-arch-compute-nodes-bare-metal[Creating a cluster with multi-architecture compute machines on bare metal, {ibm-power-title}, or {ibm-z-title}]
+
+* xref:../../post_installation_configuration/configuring-multi-arch-compute-machines/multiarch-tuning-operator.adoc#multiarch-tuning-operator[Managing workloads on multi-architecture clusters by using the Multiarch Tuning Operator]