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

installing/installing_bare_metal/upi/installing-bare-metal-network-customizations.adoc

@@ -10,14 +10,11 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-In {product-title} {product-version}, you can install a cluster on bare
-metal infrastructure that you provision with customized network configuration
-options. By customizing your network configuration, your cluster can coexist
-with existing IP address allocations in your environment and integrate with
-existing MTU and VXLAN configurations.
+[role="_abstract"]
+In {product-title} {product-version}, you can install a cluster on bare-metal infrastructure that you provision with customized network configuration options. By customizing your network configuration, your cluster can coexist
+with existing IP address allocations in your environment and integrate with existing MTU and VXLAN configurations.
 
-When you customize {product-title} networking, you must set most of the network configuration parameters during installation. You can modify only `kubeProxy` network configuration parameters in a running
-cluster.
+When you customize {product-title} networking, you must set most of the network configuration parameters during installation. You can modify only `kubeProxy` network configuration parameters in a running cluster.
 
 == Prerequisites
 
@@ -67,10 +64,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

@@ -11,12 +11,11 @@ include::_attributes/common-attributes.adoc[]
 toc::[]
 
 [role="_abstract"]
-In {product-title} {product-version}, you can install a cluster on bare-metal infrastructure that you provision.
+To optimize performance and maintain more control over your hardware in {product-title} {product-version}, you an install a cluster on bare-metal infrastructure that you provision.
 
 [IMPORTANT]
 ====
-While you might be able to follow this procedure to deploy a cluster on virtualized or cloud environments, you must be aware of additional
-considerations for non-bare-metal platforms. Review the information in the link:https://access.redhat.com/articles/4207611[guidelines for deploying {product-title} on non-tested platforms] before you attempt to install an {product-title} cluster in such an environment.
+While you might be able to follow this procedure to deploy a cluster on virtualized or cloud environments, you must be aware of additional considerations for non-bare-metal platforms. Review the information in the link:https://access.redhat.com/articles/4207611[guidelines for deploying {product-title} on non-tested platforms] before you attempt to install an {product-title} cluster in such an environment.
 ====
 
 == Prerequisites
@@ -69,6 +68,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 +78,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/cli-installing-cli-linux.adoc

@@ -56,7 +56,7 @@ endif::[]
 = Installing the OpenShift CLI on Linux
 
 [role="_abstract"]
-You can install the {oc-first} binary on Linux.
+To manage your cluster and deploy applications from the command line, install the {oc-first} binary on Linux.
 
 [IMPORTANT]
 ====

modules/cli-installing-cli-macos.adoc

@@ -56,7 +56,7 @@ endif::[]
 = Installing the OpenShift CLI on macOS
 
 [role="_abstract"]
-You can install the {oc-first} binary on macOS.
+To manage your cluster and deploy applications from the command line, install the {oc-first} binary on macOS.
 
 [IMPORTANT]
 ====

modules/cli-installing-cli-windows.adoc

@@ -56,7 +56,7 @@ endif::[]
 = Installing the OpenShift CLI on Windows
 
 [role="_abstract"]
-You can install the {oc-first} binary on Windows.
+To manage your cluster and deploy applications from the command line, install {oc-first} binary on Windows.
 
 [IMPORTANT]
 ====

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.