openshift · jeana-redhat · Jun 9, 2025 · Jun 4, 2025
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -2504,6 +2504,8 @@ Topics:
       File: cluster-api-config-options-rhosp
     - Name: Cluster API configuration options for VMware vSphere
       File: cluster-api-config-options-vsphere
+    - Name: Cluster API configuration options for bare metal
+      File: cluster-api-config-options-bare-metal
 #  - Name: Cluster API resiliency and recovery
 #    File: cluster-api-resiliency
   - Name: Troubleshooting Cluster API clusters

diff --git a/machine_management/applying-autoscaling.adoc b/machine_management/applying-autoscaling.adoc
@@ -32,7 +32,7 @@ include::modules/cluster-autoscaler-cr.adoc[leveloffset=+3]
 include::modules/cluster-autoscaler-config-priority-expander.adoc[leveloffset=+3]
 
 //Labeling GPU machine sets for the cluster autoscaler
-include::modules/machineset-label-gpu-autoscaler.adoc[leveloffset=+3]
+include::modules/machine-feature-agnostic-options-label-gpu-autoscaler.adoc[leveloffset=+3]
 
 :FeatureName: cluster autoscaler
 :FeatureResourceName: ClusterAutoscaler

diff --git a/.../cluster_api_provider_configurations/cluster-api-config-options-bare-metal.adoc b/.../cluster_api_provider_configurations/cluster-api-config-options-bare-metal.adoc
@@ -0,0 +1,35 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cluster-api-config-options-bare-metal"]
+= Cluster API configuration options for bare metal
+include::_attributes/common-attributes.adoc[]
+:context: cluster-api-config-options-bare-metal
+
+toc::[]
+
+You can change the configuration of your bare metal Cluster API machines by updating values in the Cluster API custom resource manifests.
+
+:FeatureName: Managing machines with the Cluster API
+include::snippets/technology-preview.adoc[]
+
+[id="cluster-api-sample-yaml-bare-metal_{context}"]
+== Sample YAML for configuring bare metal clusters
+
+The following example YAML files show configurations for a bare metal cluster.
+
+//Sample YAML for CAPI bare metal machine template resource
+include::modules/capi-yaml-machine-template-bare-metal.adoc[leveloffset=+2]
+
+//Sample YAML for a CAPI bare metal compute machine set resource
+include::modules/capi-yaml-machine-set-bare-metal.adoc[leveloffset=+2]
+
+[id="cluster-api-supported-features-bare-metal_{context}"]
+== Enabling bare metal features with the Cluster API
+
+You can enable features by updating values in the Cluster API custom resource manifests.
+
+// Cluster autoscaler GPU labels
+include::modules/machine-feature-agnostic-options-label-gpu-autoscaler.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../../machine_management/applying-autoscaling.adoc#cluster-autoscaler-cr_applying-autoscaling[Cluster autoscaler resource definition]
diff --git a/modules/capi-yaml-machine-set-bare-metal.adoc b/modules/capi-yaml-machine-set-bare-metal.adoc
@@ -0,0 +1,50 @@
+// Module included in the following assemblies:
+//
+// * machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-bare-metal.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="capi-yaml-machine-set-bare-metal_{context}"]
+= Sample YAML for a Cluster API compute machine set resource on bare metal
+
+The compute machine set resource defines additional properties of the machines that it creates.
+The compute machine set also references the cluster resource and machine template when creating machines.
+
+[source,yaml]
+----
+apiVersion: cluster.x-k8s.io/v1
+kind: MachineSet
+metadata:
+  name: <machine_set_name> # <1>
+  namespace: openshift-cluster-api
+  labels:
+    cluster.x-k8s.io/cluster-name: <cluster_name> # <2>
+spec:
+  clusterName: <cluster_name>
+  replicas: 1
+  selector:
+    matchLabels:
+      test: example
+      cluster.x-k8s.io/cluster-name: <cluster_name>
+      cluster.x-k8s.io/set-name: <machine_set_name>
+  template:
+    metadata:
+      labels:
+        test: example
+        cluster.x-k8s.io/cluster-name: <cluster_name>
+        cluster.x-k8s.io/set-name: <machine_set_name>
+        node-role.kubernetes.io/<role>: ""
+    spec:
+      bootstrap:
+         dataSecretName: worker-user-data
+      clusterName: <cluster_name>
+      infrastructureRef:
+        apiVersion: infrastructure.cluster.x-k8s.io/v1
+        kind: Metal3MachineTemplate # <3>
+        name: <template_name> # <4>
+----
+<1> Specify a name for the compute machine set.
+The cluster ID, machine role, and region form a typical pattern for this value in the following format: `<cluster_name>-<role>-<region>`.
+<2> Specify the cluster ID as the name of the cluster.
+<3> Specify the machine template kind.
+This value must match the value for your platform.
+<4> Specify the machine template name.
diff --git a/modules/capi-yaml-machine-template-bare-metal.adoc b/modules/capi-yaml-machine-template-bare-metal.adoc
@@ -0,0 +1,29 @@
+// Module included in the following assemblies:
+//
+// * machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-bare-metal.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="capi-yaml-machine-template-bare-metal_{context}"]
+= Sample YAML for a Cluster API machine template resource on bare metal
+
+The machine template resource is provider-specific and defines the basic properties of the machines that a compute machine set creates.
+The compute machine set references this template when creating machines.
+
+[source,yaml]
+----
+apiVersion: infrastructure.cluster.x-k8s.io/v1
+kind: Metal3MachineTemplate # <1>
+metadata:
+  name: <template_name> # <2>
+  namespace: openshift-cluster-api
+spec:
+  template:
+    spec: # <3>
+      customDeploy: install_coreos
+      userData: worker-user-data
+----
+<1> Specify the machine template kind.
+This value must match the value for your platform.
+<2> Specify a name for the machine template.
+<3> Specify the details for your environment.
+The values here are examples.
diff --git a/modules/cluster-autoscaler-cr.adoc b/modules/cluster-autoscaler-cr.adoc
@@ -53,7 +53,7 @@ spec:
 <7> Optional: To configure the cluster autoscaler to deploy GPU-enabled nodes, specify a `type` value.
 This value must match the value of the `spec.template.spec.metadata.labels[cluster-api/accelerator]` label in the machine set that manages the GPU-enabled nodes of that type.
 For example, this value might be `nvidia-t4` to represent Nvidia T4 GPUs, or `nvidia-a10g` for A10G GPUs.
-For more information, see "Labeling GPU machine sets for the cluster autoscaler".
+For more information, see "Cluster autoscaler GPU labels".
 <8> Specify the minimum number of GPUs of the specified type to deploy in the cluster.
 <9> Specify the maximum number of GPUs of the specified type to deploy in the cluster.
 <10> Specify the logging verbosity level between `0` and `10`. The following log level thresholds are provided for guidance:

diff --git a/modules/machine-feature-agnostic-options-label-gpu-autoscaler.adoc b/modules/machine-feature-agnostic-options-label-gpu-autoscaler.adoc
@@ -0,0 +1,43 @@
+// Module included in the following assemblies:
+//
+// * machine_management/applying-autoscaling.adoc
+// * machine_management/cluster_api_machine_management/cluster_api_provider_configurations/cluster-api-config-options-aws.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="machine-feature-agnostic-options-label-gpu-autoscaler_{context}"]
+= Cluster autoscaler GPU labels
+
+You can indicate machines that the cluster autoscaler can deploy GPU-enabled nodes on by adding parameters to a compute machine set custom resource (CR).
+
+.Sample cluster autoscaler GPU label
+[source,yaml]
+----
+apiVersion: <api_group_version> # <1>
+kind: MachineSet
+# ...
+spec:
+  template:
+    spec:
+      metadata:
+        labels:
+          cluster-api/accelerator: <gpu_type> # <2>
+# ...
+----
+<1> Specifies the API group and version of the machine set.
+The following values are valid:
+`cluster.x-k8s.io/v1beta1`:: The API group and version for Cluster API machine sets.
+`machine.openshift.io/v1beta1`:: The API group and version for Machine API machine sets.
+<2> Specifies a label to use for GPU-enabled nodes.
+The label must use the following format:
++
+--
+* Consists of alphanumeric characters, `-`, `_`, or `.`.
+* Starts and ends with an alphanumeric character.
+--
+For example, this value might be `nvidia-t4` to represent Nvidia T4 GPUs, or `nvidia-a10g` for A10G GPUs.
++
+[NOTE]
+====
+You must also specify the value of this label for the `spec.resourceLimits.gpus.type` parameter in your `ClusterAutoscaler` CR.
+For more information, see "Cluster autoscaler resource definition".
+====