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

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]
 

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]
 

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]
 

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]

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]

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"]

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"]

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]

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"]

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"]

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"]

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"]

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

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]

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]

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]
 

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]

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]

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

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[]

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.
 

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.

modules/enabling-OVS-balance-slb-mode.adoc

@@ -11,6 +11,7 @@
 [id="enabling-OVS-balance-slb-mode_{context}"]
 = Enabling OVS balance-slb mode for your cluster
 
+[role="_abstract"]
 You can enable the Open vSwitch (OVS) `balance-slb` mode so that two or more physical interfaces can share their network traffic. A `balance-slb` mode interface can give source load balancing (SLB) capabilities to a cluster that runs virtualization workloads, without requiring load balancing negotiation with the network switch.
 
 Currently, source load balancing runs on a bond interface, where the interface connects to an auxiliary bridge, such as  `br-phy`. Source load balancing balances only across different Media Access Control (MAC) address and virtual local area network (VLAN) combinations. Note that all OVN-Kubernetes pod traffic uses the same MAC address and VLAN, so this traffic cannot be load balanced across many physical interfaces.
@@ -40,25 +41,25 @@ You can integrate the `balance-slb` mode interface into primary or secondary net
 # ...
 networkConfig:
   interfaces:
-    - name: enp1s0 <1>
+    - name: enp1s0
       type: ethernet
       state: up
       ipv4:
         dhcp: true
         enabled: true
       ipv6:
         enabled: false
-    - name: enp2s0 <2>
+    - name: enp2s0
       type: ethernet
       state: up
-      mtu: 1500 <3>
+      mtu: 1500
       ipv4:
         dhcp: true
         enabled: true
       ipv6:
         dhcp: true
         enabled: true
-    - name: enp3s0 <4>
+    - name: enp3s0
       type: ethernet
       state: up
       mtu: 1500
@@ -68,10 +69,13 @@ networkConfig:
         enabled: false
 # ...
 ----
-<1> The interface for the provisioned network interface controller (NIC). 
-<2> The first bonded interface that pulls in the Ignition config file for the bond interface.
-<3> Manually set the `br-ex` maximum transmission unit (MTU) on the bond ports.
-<4> The second bonded interface is part of a minimal configuration that pulls ignition during cluster installation.
++
+where:
++
+`enp1s0`:: The interface for the provisioned network interface controller (NIC). 
+`enp2s0`:: The first bonded interface that pulls in the Ignition config file for the bond interface.
+`mtu`:: Manually set the `br-ex` maximum transmission unit (MTU) on the bond ports.
+`enp3s0`:: The second bonded interface is part of a minimal configuration that pulls ignition during cluster installation.
 
 . Define each network interface in an NMState configuration file:
 +
@@ -98,7 +102,7 @@ interfaces:
   - name: br-ex
     type: ovs-interface
     state: up
-    mtu: 1500 <1>
+    mtu: 1500
     ipv4:
       enabled: true
       dhcp: true
@@ -156,15 +160,18 @@ interfaces:
       enabled: false
 # ...
 ----
-<1> Manually set the `br-ex` MTU on the bond ports.
++
+where:
++
+`mtu`:: Manually set the `br-ex` MTU on the bond ports.
 
 . Use the `base64` command to encode the interface content of the NMState configuration file:
 +
 [source,terminal]
 ----
-$ base64 -w0  <nmstate_configuration>.yml <1>
+$ base64 -w0  <nmstate_configuration>.yml
 ----
-<1> Where the `-w0` option prevents line wrapping during the base64 encoding operation.
+* <nmstate_configuration>: Where the `-w0` option prevents line wrapping during the base64 encoding operation.
 
 . Create `MachineConfig` manifest files for the `master` role and the `worker` role. Ensure that you embed the base64-encoded string from an earlier command into each `MachineConfig` manifest file. The following example manifest file configures the `master` role for all nodes that exist in a cluster. You can also create a manifest file for `master` and `worker` roles specific to a node. 
 +
@@ -175,22 +182,25 @@ kind: MachineConfig
 metadata:
   labels:
     machineconfiguration.openshift.io/role: master
-  name: 10-br-ex-master <1>
+  name: 10-br-ex-master
 spec:
   config:
     ignition:
       version: 3.2.0
     storage:
       files:
       - contents:
-          source: data:text/plain;charset=utf-8;base64,<base64_encoded_nmstate_configuration> <2>
+          source: data:text/plain;charset=utf-8;base64,<base64_encoded_nmstate_configuration>
         mode: 0644
         overwrite: true
-        path: /etc/nmstate/openshift/cluster.yml <3>
+        path: /etc/nmstate/openshift/cluster.yml
 ----
-<1> The name of the policy.
-<2> Writes the encoded base64 information to the specified path.
-<3> Specify the path to the `cluster.yml` file. For each node in your cluster, you can specify the short hostname path to your node, such as `<node_short_hostname>`.yml.
++
+where:
++
+`name`:: The name of the policy.
+`source`:: Writes the encoded base64 information to the specified path.
+`path`:: Specify the path to the `cluster.yml` file. For each node in your cluster, you can specify the short hostname path to your node, such as `<node_short_hostname>`.yml.
 
 . Save each `MachineConfig` manifest file to the `./<installation_directory>/manifests` directory, where `<installation_directory>` is the directory in which the installation program creates files.
 +