OSDOCS-17013-bm-upi-4: CQAs bare metal UPI doc

dfitzmau · dfitzmau · commit cc93eb885980 · 2025-12-22T17:04:25.000Z
diff --git a/installing/installing_bare_metal/upi/installing-bare-metal-network-customizations.adoc b/installing/installing_bare_metal/upi/installing-bare-metal-network-customizations.adoc
@@ -67,10 +67,14 @@ include::modules/installation-network-user-infra.adoc[leveloffset=+2]
 
 include::modules/installation-dns-user-infra.adoc[leveloffset=+2]
 
+include::modules/installation-dns-user-infra-example.adoc[leveloffset=+3]
+
 * xref:../../../installing/installing_bare_metal/upi/installing-bare-metal-network-customizations.adoc#installation-user-provisioned-validating-dns_installing-bare-metal-network-customizations[Validating DNS resolution for user-provisioned infrastructure]
 
 include::modules/installation-load-balancing-user-infra.adoc[leveloffset=+2]
 
+include::modules/installation-load-balancing-user-infra-example.adoc[leveloffset=+3]
+
 // Creating a manifest object that includes a customized `br-ex` bridge
 include::modules/creating-manifest-file-customized-br-ex-bridge.adoc[leveloffset=+1]
 
diff --git a/installing/installing_bare_metal/upi/installing-bare-metal.adoc b/installing/installing_bare_metal/upi/installing-bare-metal.adoc
@@ -69,6 +69,8 @@ include::modules/installation-network-user-infra.adoc[leveloffset=+2]
 
 include::modules/installation-dns-user-infra.adoc[leveloffset=+2]
 
+include::modules/installation-dns-user-infra-example.adoc[leveloffset=+3]
+
 [role="_additional-resources"]
 .Additional resources
 
@@ -77,6 +79,8 @@ include::modules/installation-dns-user-infra.adoc[leveloffset=+2]
 // Load balancing requirements for user-provisioned infrastructure
 include::modules/installation-load-balancing-user-infra.adoc[leveloffset=+2]
 
+include::modules/installation-load-balancing-user-infra-example.adoc[leveloffset=+3]
+
 // Creating a manifest object that includes a customized `br-ex` bridge
 include::modules/creating-manifest-file-customized-br-ex-bridge.adoc[leveloffset=+1]
 
diff --git a/installing/installing_bare_metal/upi/installing-restricted-networks-bare-metal.adoc b/installing/installing_bare_metal/upi/installing-restricted-networks-bare-metal.adoc
@@ -79,13 +79,17 @@ include::modules/installation-network-user-infra.adoc[leveloffset=+2]
 
 include::modules/installation-dns-user-infra.adoc[leveloffset=+2]
 
+include::modules/installation-dns-user-infra-example.adoc[leveloffset=+3]
+
 [role="_additional-resources"]
 .Additional resources
 
 * xref:../../../installing/installing_bare_metal/upi/installing-restricted-networks-bare-metal.adoc#installation-user-provisioned-validating-dns_installing-restricted-networks-bare-metal[Validating DNS resolution for user-provisioned infrastructure]
 
 include::modules/installation-load-balancing-user-infra.adoc[leveloffset=+2]
 
+include::modules/installation-load-balancing-user-infra-example.adoc[leveloffset=+3]
+
 // Creating a manifest object that includes a customized `br-ex` bridge
 include::modules/creating-manifest-file-customized-br-ex-bridge.adoc[leveloffset=+1]
 
diff --git a/installing/installing_ibm_power/installing-ibm-power.adoc b/installing/installing_ibm_power/installing-ibm-power.adoc
@@ -62,8 +62,12 @@ include::modules/installation-network-user-infra.adoc[leveloffset=+2]
 
 include::modules/installation-dns-user-infra.adoc[leveloffset=+2]
 
+include::modules/installation-dns-user-infra-example.adoc[leveloffset=+3]
+
 include::modules/installation-load-balancing-user-infra.adoc[leveloffset=+2]
 
+include::modules/installation-load-balancing-user-infra-example.adoc[leveloffset=+3]
+
 include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1]
 
 include::modules/installation-user-provisioned-validating-dns.adoc[leveloffset=+1]
diff --git a/installing/installing_ibm_power/installing-restricted-networks-ibm-power.adoc b/installing/installing_ibm_power/installing-restricted-networks-ibm-power.adoc
@@ -70,8 +70,12 @@ include::modules/installation-network-user-infra.adoc[leveloffset=+2]
 
 include::modules/installation-dns-user-infra.adoc[leveloffset=+2]
 
+include::modules/installation-dns-user-infra-example.adoc[leveloffset=+3]
+
 include::modules/installation-load-balancing-user-infra.adoc[leveloffset=+2]
 
+include::modules/installation-load-balancing-user-infra-example.adoc[leveloffset=+3]
+
 include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1]
 
 include::modules/installation-user-provisioned-validating-dns.adoc[leveloffset=+1]
diff --git a/installing/installing_ibm_z/upi/installing-ibm-z-kvm.adoc b/installing/installing_ibm_z/upi/installing-ibm-z-kvm.adoc
@@ -33,6 +33,8 @@ Be sure to also review this site list if you are configuring a proxy.
 
 include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1]
 
+include::modules/installation-load-balancing-user-infra-example.adoc[leveloffset=+2]
+
 include::modules/installation-initializing-manual.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/installing/installing_ibm_z/upi/installing-ibm-z-lpar.adoc b/installing/installing_ibm_z/upi/installing-ibm-z-lpar.adoc
@@ -31,6 +31,8 @@ Be sure to also review this site list if you are configuring a proxy.
 
 include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1]
 
+include::modules/installation-load-balancing-user-infra-example.adoc[leveloffset=+2]
+
 include::modules/installation-initializing-manual.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/installing/installing_ibm_z/upi/installing-ibm-z-reqs.adoc b/installing/installing_ibm_z/upi/installing-ibm-z-reqs.adoc
@@ -49,4 +49,6 @@ include::modules/installation-network-user-infra.adoc[leveloffset=+2]
 
 include::modules/installation-dns-user-infra.adoc[leveloffset=+2]
 
+include::modules/installation-dns-user-infra-example.adoc[leveloffset=+3]
+
 include::modules/installation-load-balancing-user-infra.adoc[leveloffset=+2]
diff --git a/installing/installing_ibm_z/upi/installing-ibm-z.adoc b/installing/installing_ibm_z/upi/installing-ibm-z.adoc
@@ -32,6 +32,8 @@ Be sure to also review this site list if you are configuring a proxy.
 
 include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1]
 
+include::modules/installation-load-balancing-user-infra-example.adoc[leveloffset=+2]
+
 include::modules/installation-initializing-manual.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/installing/installing_ibm_z/upi/installing-restricted-networks-ibm-z-kvm.adoc b/installing/installing_ibm_z/upi/installing-restricted-networks-ibm-z-kvm.adoc
@@ -41,6 +41,8 @@ include::modules/installation-about-restricted-network.adoc[leveloffset=+1]
 
 include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1]
 
+include::modules/installation-load-balancing-user-infra-example.adoc[leveloffset=+2]
+
 include::modules/installation-initializing-manual.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/installing/installing_ibm_z/upi/installing-restricted-networks-ibm-z-lpar.adoc b/installing/installing_ibm_z/upi/installing-restricted-networks-ibm-z-lpar.adoc
@@ -39,6 +39,8 @@ include::modules/installation-about-restricted-network.adoc[leveloffset=+1]
 
 include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1]
 
+include::modules/installation-load-balancing-user-infra-example.adoc[leveloffset=+2]
+
 include::modules/installation-initializing-manual.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/installing/installing_ibm_z/upi/installing-restricted-networks-ibm-z.adoc b/installing/installing_ibm_z/upi/installing-restricted-networks-ibm-z.adoc
@@ -40,6 +40,8 @@ include::modules/installation-about-restricted-network.adoc[leveloffset=+1]
 
 include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1]
 
+include::modules/installation-load-balancing-user-infra-example.adoc[leveloffset=+2]
+
 include::modules/installation-initializing-manual.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/installing/installing_ibm_z/upi/upi-ibm-z-preparing-to-install.adoc b/installing/installing_ibm_z/upi/upi-ibm-z-preparing-to-install.adoc
@@ -45,9 +45,6 @@ include::modules/cli-installing-cli-macos.adoc[leveloffset=+1]
 
 include::modules/ssh-agent-using.adoc[leveloffset=+1]
 
-//verify how to get in differences between kvm and zvm, lpar
-// include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1]
-
 include::modules/installation-user-provisioned-validating-dns.adoc[leveloffset=+1]
 
 //verify telemetry only connected do we want it here
diff --git a/installing/installing_openstack/installing-openstack-installer-custom.adoc b/installing/installing_openstack/installing-openstack-installer-custom.adoc
@@ -26,6 +26,8 @@ include::modules/installation-osp-bootstrap-machine.adoc[leveloffset=+2]
 
 include::modules/installation-load-balancing-user-infra.adoc[leveloffset=+2]
 
+include::modules/installation-load-balancing-user-infra-example.adoc[leveloffset=+3]
+
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 
 include::modules/installation-osp-enabling-swift.adoc[leveloffset=+1]
diff --git a/installing/installing_platform_agnostic/installing-platform-agnostic.adoc b/installing/installing_platform_agnostic/installing-platform-agnostic.adoc
@@ -50,8 +50,12 @@ include::modules/installation-network-user-infra.adoc[leveloffset=+2]
 
 include::modules/installation-dns-user-infra.adoc[leveloffset=+2]
 
+include::modules/installation-dns-user-infra-example.adoc[leveloffset=+3]
+
 include::modules/installation-load-balancing-user-infra.adoc[leveloffset=+2]
 
+include::modules/installation-load-balancing-user-infra-example.adoc[leveloffset=+3]
+
 include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1]
 
 include::modules/installation-user-provisioned-validating-dns.adoc[leveloffset=+1]
diff --git a/installing/installing_two_node_cluster/installing_tnf/installing-two-node-fencing.adoc b/installing/installing_two_node_cluster/installing_tnf/installing-two-node-fencing.adoc
@@ -48,6 +48,8 @@ include::modules/installation-two-node-cluster-min-resource-reqs.adoc[leveloffse
 // Two-node-dns-requirements - user-provisioned infrastructure
 include::modules/installation-dns-user-infra.adoc[leveloffset=+1]
 
+include::modules/installation-dns-user-infra-example.adoc[leveloffset=+2]
+
 // Two-node-dns-requirements - installer-provisioned infrastructure
 include::modules/installation-dns-installer-infra.adoc[leveloffset=+1]
 
diff --git a/installing/installing_vsphere/upi/upi-vsphere-installation-reqs.adoc b/installing/installing_vsphere/upi/upi-vsphere-installation-reqs.adoc
@@ -59,4 +59,8 @@ include::modules/installation-network-user-infra.adoc[leveloffset=+2]
 
 include::modules/installation-dns-user-infra.adoc[leveloffset=+2]
 
+include::modules/installation-dns-user-infra-example.adoc[leveloffset=+3]
+
 include::modules/installation-load-balancing-user-infra.adoc[leveloffset=+2]
+
+include::modules/installation-load-balancing-user-infra-example.adoc[leveloffset=+3]
diff --git a/installing/installing_vsphere/upi/upi-vsphere-preparing-to-install.adoc b/installing/installing_vsphere/upi/upi-vsphere-preparing-to-install.adoc
@@ -39,4 +39,6 @@ include::modules/ssh-agent-using.adoc[leveloffset=+1]
 
 include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1]
 
+include::modules/installation-load-balancing-user-infra-example.adoc[leveloffset=+2]
+
 include::modules/installation-user-provisioned-validating-dns.adoc[leveloffset=+1]
diff --git a/modules/cluster-entitlements.adoc b/modules/cluster-entitlements.adoc
@@ -109,6 +109,7 @@ endif::[]
 ifndef::openshift-origin[]
 = Internet access for {product-title}
 
+[role="_abstract"]
 In {product-title} {product-version}, you require access to the internet to
 ifndef::restricted[]
 install
diff --git a/modules/creating-manifest-file-customized-br-ex-bridge.adoc b/modules/creating-manifest-file-customized-br-ex-bridge.adoc
@@ -14,6 +14,7 @@ endif::[]
 [id="creating-manifest-file-customized-br-ex-bridge_{context}"]
 = Creating a manifest object that includes a customized `br-ex` bridge
 
+[role="_abstract"]
 ifndef::postinstall-bare-metal[]
 As an alternative to using the `configure-ovs.sh` shell script to set a `br-ex` bridge on a bare-metal platform, you can create a `MachineConfig` object that includes an NMState configuration file. The host `nmstate-configuration.service` and `nmstate.service` apply the NMState configuration file to each node that runs in your cluster.
 endif::postinstall-bare-metal[]
diff --git a/modules/creating-scaling-machine-sets-compute-nodes-networking.adoc b/modules/creating-scaling-machine-sets-compute-nodes-networking.adoc
@@ -11,9 +11,10 @@
 [id="creating-scaling-machine-sets-compute-nodes-networking_{context}"]
 = Scaling each machine set to compute nodes
 
-To apply a customized `br-ex` bridge configuration to all compute nodes in your {product-title} cluster, you must edit your `MachineConfig` custom resource (CR) and modify its roles. Additionally, you must create a `BareMetalHost` CR that defines information for your bare-metal machine, such as hostname, credentials, and so on.
+[role="_abstract"]
+To scale each machine set to compute nodes, you must apply a customized `br-ex` bridge configuration to all compute nodes in your {product-title} cluster. You must then edit your `MachineConfig` custom resource (CR) and modify its roles. 
 
-After you configure these resources, you must scale machine sets, so that the machine sets can apply the resource configuration to each compute node and reboot the nodes.
+Additionally, you must create a `BareMetalHost` CR that defines information for your bare-metal machine, such as hostname, credentials, and so on. After you configure these resources, you must scale machine sets, so that the machine sets can apply the resource configuration to each compute node and reboot the nodes.
 
 .Prerequisites
 
@@ -70,7 +71,7 @@ $ oc get machinesets
 +
 [source,terminal]
 ----
-$ oc scale machineset <machineset_name> --replicas=<n> <1>
+$ oc scale machineset <machineset_name> --replicas=<n>
 ----
-<1> Where `<machineset_name>` is the name of the machine set and `<n>` is the number of compute nodes.
+* <n>: Where `<machineset_name>` is the name of the machine set and `<n>` is the number of compute nodes.
 
diff --git a/modules/csr-management.adoc b/modules/csr-management.adoc
@@ -29,4 +29,5 @@
 [id="csr-management_{context}"]
 = Certificate signing requests management
 
+[role="_abstract"]
 Because your cluster has limited access to automatic machine management when you use infrastructure that you provision, you must provide a mechanism for approving cluster certificate signing requests (CSRs) after installation. The `kube-controller-manager` only approves the kubelet client CSRs. The `machine-approver` cannot guarantee the validity of a serving certificate that is requested by using kubelet credentials because it cannot confirm that the correct machine issued the request. You must determine and implement a method of verifying the validity of the kubelet serving certificate requests and approving them.
diff --git a/modules/installation-dns-user-infra-example.adoc b/modules/installation-dns-user-infra-example.adoc
diff --git a/modules/installation-dns-user-infra.adoc b/modules/installation-dns-user-infra.adoc
diff --git a/modules/installation-load-balancing-user-infra-example.adoc b/modules/installation-load-balancing-user-infra-example.adoc
diff --git a/modules/installation-load-balancing-user-infra.adoc b/modules/installation-load-balancing-user-infra.adoc
diff --git a/modules/installation-machine-requirements.adoc b/modules/installation-machine-requirements.adoc
diff --git a/modules/installation-minimum-resource-requirements.adoc b/modules/installation-minimum-resource-requirements.adoc
