openshift · bergerhoffer · Mar 25, 2026
diff --git a/machine_management/index.adoc b/machine_management/index.adoc
@@ -6,12 +6,13 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 You can use machine management to flexibly work with underlying infrastructure such as Amazon Web Services (AWS), Microsoft Azure, {gcp-first}, {rh-openstack-first}, and VMware vSphere to manage the {product-title} cluster.
 You can control the cluster and perform auto-scaling, such as scaling up and down the cluster based on specific workload policies.
 
 It is important to have a cluster that adapts to changing workloads. The {product-title} cluster can horizontally scale up and down when the load increases or decreases.
 
-Machine management is implemented as a xref:../operators/understanding/crds/crd-extending-api-with-crds.adoc#crd-extending-api-with-crds[custom resource definition] (CRD).
+Machine management is implemented as a custom resource definition (CRD).
 A CRD object defines a new unique object `Kind` in the cluster and enables the Kubernetes API server to handle the object's entire lifecycle.
 
 The Machine API Operator provisions the following resources:
@@ -28,73 +29,14 @@ include::modules/machine-api-overview.adoc[leveloffset=+1]
 .Additional resources
 * xref:../machine_management/machine-phases-lifecycle.adoc#machine-phases-lifecycle[Machine phases and lifecycle]
 
-[id="machine-mgmt-intro-managing-compute_{context}"]
-== Managing compute machines
+include::modules/machine-managing-compute-machines.adoc[leveloffset=+1]
 
-As a cluster administrator, you can perform the following actions:
+include::modules/machine-control-plane-machines.adoc[leveloffset=+1]
 
-* Create a compute machine set for the following cloud providers:
+include::modules/machine-applying-autoscaling.adoc[leveloffset=+1]
 
-** xref:../machine_management/creating_machinesets/creating-machineset-aws.adoc#creating-machineset-aws[AWS]
+include::modules/machine-adding-compute-machines-upi.adoc[leveloffset=+1]
 
-** xref:../machine_management/creating_machinesets/creating-machineset-azure.adoc#creating-machineset-azure[Azure]
-
-** xref:../machine_management/creating_machinesets/creating-machineset-azure-stack-hub.adoc#creating-machineset-azure-stack-hub[Azure Stack Hub]
-
-** xref:../machine_management/creating_machinesets/creating-machineset-gcp.adoc#creating-machineset-gcp[{gcp-short}]
-
-** xref:../machine_management/creating_machinesets/creating-machineset-ibm-cloud.adoc#creating-machineset-ibm-cloud[IBM Cloud]
-
-** xref:../machine_management/creating_machinesets/creating-machineset-ibm-power-vs.adoc#creating-machineset-ibm-power-vs[IBM Power Virtual Server]
-
-** xref:../machine_management/creating_machinesets/creating-machineset-nutanix.adoc#creating-machineset-nutanix[Nutanix]
-
-** xref:../machine_management/creating_machinesets/creating-machineset-osp.adoc#creating-machineset-osp[{rh-openstack}]
-
-** xref:../machine_management/creating_machinesets/creating-machineset-vsphere.adoc#creating-machineset-vsphere[vSphere]
-
-* Create a machine set for a bare metal deployment: xref:../machine_management/creating_machinesets/creating-machineset-bare-metal.adoc#creating-machineset-bare-metal[Creating a compute machine set on bare metal]
-
-* xref:../machine_management/manually-scaling-machineset.adoc#manually-scaling-machineset[Manually scale a compute machine set] by adding or removing a machine from the compute machine set.
-
-* xref:../machine_management/modifying-machineset.adoc#modifying-machineset[Modify a compute machine set] through the `MachineSet` YAML configuration file.
-
-* xref:../machine_management/deleting-machine.adoc#deleting-machine[Delete] a machine.
-
-* xref:../machine_management/creating-infrastructure-machinesets.adoc#creating-infrastructure-machinesets[Create infrastructure compute machine sets].
-
-* Configure and deploy a xref:../machine_management/deploying-machine-health-checks.adoc#deploying-machine-health-checks[machine health check] to automatically fix damaged machines in a machine pool.
-
-[id="machine-mgmt-intro-managing-control-plane_{context}"]
-== Managing control plane machines
-
-As a cluster administrator, you can perform the following actions:
-
-* xref:../machine_management/control_plane_machine_management/cpmso-managing-machines.adoc#cpmso-feat-config-update_cpmso-managing-machines[Update your control plane configuration] with a control plane machine set for the following cloud providers:
-
-** xref:../machine_management/control_plane_machine_management/cpmso_provider_configurations/cpmso-config-options-aws.adoc#cpmso-config-options-aws[{aws-full}]
-
-** xref:../machine_management/control_plane_machine_management/cpmso_provider_configurations/cpmso-config-options-gcp.adoc#cpmso-config-options-gcp[{gcp-full}]
-
-** xref:../machine_management/control_plane_machine_management/cpmso_provider_configurations/cpmso-config-options-azure.adoc#cpmso-config-options-azure[{azure-full}]
-
-** xref:../machine_management/control_plane_machine_management/cpmso_provider_configurations/cpmso-config-options-nutanix#cpmso-config-options-nutanix[Nutanix]
-
-** xref:../machine_management/control_plane_machine_management/cpmso_provider_configurations/cpmso-config-options-openstack.adoc#cpmso-config-options-openstack[{rh-openstack-first}]
-
-** xref:../machine_management/control_plane_machine_management/cpmso_provider_configurations/cpmso-config-options-vsphere#cpmso-config-options-vsphere[{vmw-full}]
-
-* Configure and deploy a xref:../machine_management/deploying-machine-health-checks.adoc#deploying-machine-health-checks[machine health check] to automatically recover unhealthy control plane machines.
-
-[id="machine-mgmt-intro-autoscaling_{context}"]
-== Applying autoscaling to an {product-title} cluster
-
-You can automatically scale your {product-title} cluster to ensure flexibility for changing workloads. To xref:../machine_management/applying-autoscaling.adoc#applying-autoscaling[autoscale] your cluster, you must first deploy a cluster autoscaler, and then deploy a machine autoscaler for each compute machine set.
-
-* The xref:../machine_management/applying-autoscaling.adoc#cluster-autoscaler-about_applying-autoscaling[_cluster autoscaler_] increases and decreases the size of the cluster based on deployment needs.
-
-* The xref:../machine_management/applying-autoscaling.adoc#machine-autoscaler-about_applying-autoscaling[_machine autoscaler_] adjusts the number of machines in the compute machine sets that you deploy in your {product-title} cluster.
-
-[id="machine-mgmt-intro-add-for-upi_{context}"]
-== Adding compute machines on user-provisioned infrastructure
-User-provisioned infrastructure is an environment where you can deploy infrastructure such as compute, network, and storage resources that host the {product-title}. You can xref:../machine_management/user_infra/adding-compute-user-infra-general.adoc#adding-compute-user-infra-general[add compute machines] to a cluster on user-provisioned infrastructure during or after the installation process.
+[role="_additional-resources"]
+.Additional resources
+* xref:../machine_management/user_infra/adding-compute-user-infra-general.adoc#adding-compute-user-infra-general[Adding compute machines to clusters with user-provisioned infrastructure manually]
diff --git a/modules/machine-adding-compute-machines-upi.adoc b/modules/machine-adding-compute-machines-upi.adoc
@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// * machine_management/index.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="machine-mgmt-intro-add-for-upi_{context}"]
+= Compute machine creation on user-provisioned infrastructure
+
+[role="_abstract"]
+User-provisioned infrastructure is an environment where you can deploy infrastructure such as compute, network, and storage resources that host the {product-title}. You can add compute machines to a cluster on user-provisioned infrastructure during or after the installation process.
diff --git a/modules/machine-applying-autoscaling.adoc b/modules/machine-applying-autoscaling.adoc
@@ -0,0 +1,18 @@
+// Module included in the following assemblies:
+//
+// * machine_management/index.adoc
+//
+// This file is a navigation file - xrefs are allowed in this type of module, but it must only ever be included from one location
+
+:_mod-docs-content-type: REFERENCE
+[id="machine-mgmt-intro-autoscaling_{context}"]
+= Cluster autoscaling
+
+[role="_abstract"]
+You can automatically scale your {product-title} cluster to ensure flexibility for changing workloads.
+
+To xref:../machine_management/applying-autoscaling.adoc#applying-autoscaling[autoscale] your cluster, you must first deploy a cluster autoscaler, and then deploy a machine autoscaler for each compute machine set.
+
+* The xref:../machine_management/applying-autoscaling.adoc#cluster-autoscaler-about_applying-autoscaling[_cluster autoscaler_] increases and decreases the size of the cluster based on deployment needs.
+
+* The xref:../machine_management/applying-autoscaling.adoc#machine-autoscaler-about_applying-autoscaling[_machine autoscaler_] adjusts the number of machines in the compute machine sets that you deploy in your {product-title} cluster.
diff --git a/modules/machine-control-plane-machines.adoc b/modules/machine-control-plane-machines.adoc
@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// * machine_management/index.adoc
+//
+// This file is a navigation file - xrefs are allowed in this type of module, but it must only ever be included from one location
+
+:_mod-docs-content-type: REFERENCE
+[id="machine-mgmt-intro-managing-control-plane_{context}"]
+= Control plane machine management
+
+[role="_abstract"]
+As a cluster administrator, you can manage the control plane machines in your {product-title} cluster.
+
+For example, you can perform the following actions:
+
+* xref:../machine_management/control_plane_machine_management/cpmso-managing-machines.adoc#cpmso-feat-config-update_cpmso-managing-machines[Update your control plane configuration] with a control plane machine set for the following cloud providers:
+
+** xref:../machine_management/control_plane_machine_management/cpmso_provider_configurations/cpmso-config-options-aws.adoc#cpmso-config-options-aws[{aws-full}]
+
+** xref:../machine_management/control_plane_machine_management/cpmso_provider_configurations/cpmso-config-options-gcp.adoc#cpmso-config-options-gcp[{gcp-full}]
+
+** xref:../machine_management/control_plane_machine_management/cpmso_provider_configurations/cpmso-config-options-azure.adoc#cpmso-config-options-azure[{azure-full}]
+
+** xref:../machine_management/control_plane_machine_management/cpmso_provider_configurations/cpmso-config-options-nutanix#cpmso-config-options-nutanix[Nutanix]
+
+** xref:../machine_management/control_plane_machine_management/cpmso_provider_configurations/cpmso-config-options-openstack.adoc#cpmso-config-options-openstack[{rh-openstack-first}]
+
+** xref:../machine_management/control_plane_machine_management/cpmso_provider_configurations/cpmso-config-options-vsphere#cpmso-config-options-vsphere[{vmw-full}]
+
+* Configure and deploy a xref:../machine_management/deploying-machine-health-checks.adoc#deploying-machine-health-checks[machine health check] to automatically recover unhealthy control plane machines.
diff --git a/modules/machine-managing-compute-machines.adoc b/modules/machine-managing-compute-machines.adoc
@@ -0,0 +1,46 @@
+// Module included in the following assemblies:
+//
+// * machine_management/index.adoc
+//
+// This file is a navigation file - xrefs are allowed in this type of module, but it must only ever be included from one location
+
+:_mod-docs-content-type: REFERENCE
+[id="machine-mgmt-intro-managing-compute_{context}"]
+= Compute machine management
+
+[role="_abstract"]
+As a cluster administrator, you can manage the compute machines in your {product-title} cluster.
+
+For example, you can perform the following actions:
+
+* Create a compute machine set for the following cloud providers:
+
+** xref:../machine_management/creating_machinesets/creating-machineset-aws.adoc#creating-machineset-aws[AWS]
+
+** xref:../machine_management/creating_machinesets/creating-machineset-azure.adoc#creating-machineset-azure[Azure]
+
+** xref:../machine_management/creating_machinesets/creating-machineset-azure-stack-hub.adoc#creating-machineset-azure-stack-hub[Azure Stack Hub]
+
+** xref:../machine_management/creating_machinesets/creating-machineset-gcp.adoc#creating-machineset-gcp[{gcp-short}]
+
+** xref:../machine_management/creating_machinesets/creating-machineset-ibm-cloud.adoc#creating-machineset-ibm-cloud[IBM Cloud]
+
+** xref:../machine_management/creating_machinesets/creating-machineset-ibm-power-vs.adoc#creating-machineset-ibm-power-vs[IBM Power Virtual Server]
+
+** xref:../machine_management/creating_machinesets/creating-machineset-nutanix.adoc#creating-machineset-nutanix[Nutanix]
+
+** xref:../machine_management/creating_machinesets/creating-machineset-osp.adoc#creating-machineset-osp[{rh-openstack}]
+
+** xref:../machine_management/creating_machinesets/creating-machineset-vsphere.adoc#creating-machineset-vsphere[vSphere]
+
+* Create a machine set for a bare metal deployment: xref:../machine_management/creating_machinesets/creating-machineset-bare-metal.adoc#creating-machineset-bare-metal[Creating a compute machine set on bare metal]
+
+* xref:../machine_management/manually-scaling-machineset.adoc#manually-scaling-machineset[Manually scale a compute machine set] by adding or removing a machine from the compute machine set.
+
+* xref:../machine_management/modifying-machineset.adoc#modifying-machineset[Modify a compute machine set] through the `MachineSet` YAML configuration file.
+
+* xref:../machine_management/deleting-machine.adoc#deleting-machine[Delete] a machine.
+
+* xref:../machine_management/creating-infrastructure-machinesets.adoc#creating-infrastructure-machinesets[Create infrastructure compute machine sets].
+
+* Configure and deploy a xref:../machine_management/deploying-machine-health-checks.adoc#deploying-machine-health-checks[machine health check] to automatically fix damaged machines in a machine pool.