Merge pull request #110558 from skopacz1/OSDOCS-17038

OSDOCS-17038: Agent install CQA

Author: skopacz1

installing/installing_with_agent_based_installer/installing-with-agent-based-installer.adoc

@@ -6,63 +6,60 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-Use the following procedures to install an {product-title} cluster with customizations using the Agent-based Installer.
+[role="_abstract"]
+You can install an {product-title} cluster using the Agent-based Installer, with customizations to meet your deployment needs.
 
-[id="prerequisites_{context}"]
-== Prerequisites
+The following procedures deploy a single-node {product-title} cluster in a disconnected environment. You can use these procedures as a basis and modify according to your requirements.
 
-* You reviewed details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes.
-* You read the documentation on xref:../../installing/overview/installing-preparing.adoc#installing-preparing[selecting a cluster installation method and preparing it for users].
-* If you use a firewall or proxy, you xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configured it to allow the sites] that your cluster requires access to.
+include::modules/installing-ocp-agent-prereqs.adoc[leveloffset=+1]
 
-[id="installing-ocp-agent_{context}"]
-== Installing {product-title} with the Agent-based Installer
+[role="_additional-resources"]
+.Additional resources
 
-The following procedures deploy a single-node {product-title} in a disconnected environment. You can use these procedures as a basis and modify according to your requirements.
+* xref:../../architecture/architecture-installation.adoc#architecture-installation[Installation and update]
+* xref:../../installing/overview/installing-preparing.adoc#installing-preparing[Selecting a cluster installation method and preparing it for users]
+* xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[Configuring your firewall]
 
 // Downloading the Agent-based Installer
-include::modules/installing-ocp-agent-download.adoc[leveloffset=+2]
+include::modules/installing-ocp-agent-download.adoc[leveloffset=+1]
 
 // Verifying the supported architecture for an Agent-based installation
-include::modules/agent-installer-architectures.adoc[leveloffset=+2]
+include::modules/agent-installer-architectures.adoc[leveloffset=+1]
 
 // Creating the preferred configuration inputs
-include::modules/installing-ocp-agent-inputs.adoc[leveloffset=+2]
+include::modules/installing-ocp-agent-inputs.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
+* xref:../../installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc#modifying-install-config-for-dual-stack-network_ipi-install-installation-workflow[Deploying with dual-stack networking]
+* xref:../../installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc#configuring-the-install-config-file_ipi-install-installation-workflow[Configuring the install-config yaml file]
+* xref:../../installing/installing_bare_metal/upi/installing-restricted-networks-bare-metal.adoc#installation-three-node-cluster_installing-restricted-networks-bare-metal[Configuring a three-node cluster]
+* xref:../../installing/installing_with_agent_based_installer/preparing-to-install-with-agent-based-installer.adoc#root-device-hints_preparing-to-install-with-agent-based-installer[About root device hints]
+* link:https://nmstate.io/examples.html[NMState state examples (NMState documentation)]
 * xref:../../installing/installing_vsphere/ipi/installing-vsphere-installer-provisioned-customizations.adoc#configuring-vsphere-regions-zones_installing-vsphere-installer-provisioned-customizations[Configuring regions and zones for a VMware vCenter]
 * xref:../../installing/installing_with_agent_based_installer/installing-with-agent-based-installer.adoc#agent-install-verifying-architectures_installing-with-agent-based-installer[Verifying the supported architecture for installing an Agent-based installer cluster]
 * xref:../../installing/installing_with_agent_based_installer/understanding-disconnected-installation-mirroring.adoc#agent-install-configuring-for-disconnected-registry_understanding-disconnected-installation-mirroring[Configuring the Agent-based Installer to use mirrored images]
 
-[id="installing-ocp-agent-opt-manifests_{context}"]
-=== Creating additional manifest files
-
-As an optional task, you can create additional manifests to further configure your cluster beyond the configurations available in the `install-config.yaml` and `agent-config.yaml` files.
-
-[IMPORTANT]
-====
-Customizations to the cluster made by additional manifests are not validated, are not guaranteed to work, and might result in a nonfunctional cluster.
-====
+include::modules/installing-ocp-agent-additional-manifests.adoc[leveloffset=+1]
 
 // Creating a directory to contain additional manifests
-include::modules/installing-ocp-agent-manifest-folder.adoc[leveloffset=+3]
+include::modules/installing-ocp-agent-manifest-folder.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
 * xref:../../machine_configuration/machine-configs-configure.adoc#machine-configs-configure[Using MachineConfig objects to configure nodes]
 
 // Disk partitioning
-include::modules/installation-user-infra-machines-advanced-disk.adoc[leveloffset=+3]
+include::modules/installation-user-infra-machines-advanced-disk.adoc[leveloffset=+2]
 
 // Using ZTP manifests
 include::modules/installing-ocp-agent-ZTP.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
-* xref:../../installing/installing_with_agent_based_installer/installing-with-agent-based-installer.adoc#sample-ztp-custom-resources_installing-with-agent-based-installer[Sample {ztp} custom resources].
+* xref:../../installing/installing_with_agent_based_installer/installing-with-agent-based-installer.adoc#sample-ztp-custom-resources_installing-with-agent-based-installer[Sample {ztp} custom resources]
 
-* See xref:../../edge_computing/ztp-deploying-far-edge-clusters-at-scale.adoc#ztp-deploying-far-edge-clusters-at-scale[Challenges of the network far edge] to learn more about {ztp-first}.
+* xref:../../edge_computing/ztp-deploying-far-edge-clusters-at-scale.adoc#ztp-deploying-far-edge-clusters-at-scale[Challenges of the network far edge]
 
 // Encrypting the disk
 include::modules/installing-ocp-agent-encrypt.adoc[leveloffset=+2]
@@ -73,34 +70,26 @@ include::modules/installing-ocp-agent-encrypt.adoc[leveloffset=+2]
 * xref:../../installing/install_config/installing-customizing.adoc#installation-special-config-encrypt-disk_installing-customizing[About disk encryption]
 
 // Creating and booting the agent image
-include::modules/installing-ocp-agent-boot.adoc[leveloffset=+2]
+include::modules/installing-ocp-agent-boot.adoc[leveloffset=+1]
 
 // Adding {ibm-z-name} agents with {op-system-base} KVM
-include::modules/installing-ocp-agent-ibm-z-kvm.adoc[leveloffset=+2]
+include::modules/installing-ocp-agent-ibm-z-kvm.adoc[leveloffset=+1]
 
 // Configuring a local arbiter node
-include::modules/installing-ocp-agent-local-arbiter-node.adoc[leveloffset=+2]
+include::modules/installing-ocp-agent-local-arbiter-node.adoc[leveloffset=+1]
 
 // Verifying that the current installation host can pull release images
-include::modules/installing-ocp-agent-tui.adoc[leveloffset=+2]
+include::modules/installing-ocp-agent-tui.adoc[leveloffset=+1]
 
 // Tracking and verifying installation progress
-include::modules/installing-ocp-agent-verify.adoc[leveloffset=+2]
-
-[role="_additional-resources"]
-.Additional resources
-* See xref:../../installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc#modifying-install-config-for-dual-stack-network_ipi-install-installation-workflow[Deploying with dual-stack networking].
-* See xref:../../installing/installing_bare_metal/ipi/ipi-install-installation-workflow.adoc#configuring-the-install-config-file_ipi-install-installation-workflow[Configuring the install-config yaml file].
-* See xref:../../installing/installing_bare_metal/upi/installing-restricted-networks-bare-metal.adoc#installation-three-node-cluster_installing-restricted-networks-bare-metal[Configuring a three-node cluster] to deploy three-node clusters in bare-metal environments.
-* See xref:../../installing/installing_with_agent_based_installer/preparing-to-install-with-agent-based-installer.adoc#root-device-hints_preparing-to-install-with-agent-based-installer[About root device hints].
-* See link:https://nmstate.io/examples.html[NMState state examples].
+include::modules/installing-ocp-agent-verify.adoc[leveloffset=+1]
 
 include::modules/sample-ztp-custom-resources.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
 
-* See xref:../../edge_computing/ztp-deploying-far-edge-clusters-at-scale.adoc#ztp-deploying-far-edge-clusters-at-scale[Challenges of the network far edge] to learn more about {ztp-first}.
+* xref:../../edge_computing/ztp-deploying-far-edge-clusters-at-scale.adoc#ztp-deploying-far-edge-clusters-at-scale[Challenges of the network far edge]
 
 // Gathering log data from a failed Agent-based installation
 include::modules/installing-ocp-agent-gather-log.adoc[leveloffset=+1]

modules/agent-installer-architectures.adoc

@@ -6,7 +6,8 @@
 [id="agent-install-verifying-architectures_{context}"]
 = Verifying the supported architecture for an Agent-based installation
 
-Before installing an {product-title} cluster using the Agent-based Installer, you can verify the supported architecture on which you can install the cluster. This procedure is optional.
+[role="_abstract"]
+Before installing an {product-title} cluster using the Agent-based Installer, you can optionally verify the supported architecture on which you can install the cluster.
 
 .Prerequisites
 
@@ -39,9 +40,10 @@ If you are using the release image with the `multi` payload, the `release archit
 [source,terminal]
 +
 ----
-$ oc adm release info <release_image> -o jsonpath="{ .metadata.metadata}" <1>
+$ oc adm release info <release_image> -o jsonpath="{ .metadata.metadata}"
 ----
-<1> Replace `<release_image>` with the release image. For example: `quay.io/openshift-release-dev/ocp-release@sha256:123abc456def789ghi012jkl345mno678pqr901stu234vwx567yz0`.
++
+Replace `<release_image>` with the release image. For example: `quay.io/openshift-release-dev/ocp-release@sha256:123abc456def789ghi012jkl345mno678pqr901stu234vwx567yz0`.
 +
 .Example output when the release image uses the `multi` payload
 [source,terminal]

modules/installation-user-infra-machines-advanced-disk.adoc

@@ -13,10 +13,11 @@ ifeval::["{context}" == "installing-restricted-networks-bare-metal"]
 endif::[]
 
 :_mod-docs-content-type: PROCEDURE
+ifndef::agent[]
 [id="installation-user-infra-machines-advanced-disk_{context}"]
 = Disk partitioning
 
-ifndef::agent[]
+
 [role="_abstract"]
 During {op-system-first} installation, {product-title} applies a default partition layout that automatically expands the root file system to fill available space. By understanding this default configuration, you can override partitioning settings to customize the layout for specific node architecture requirements.
 
@@ -42,6 +43,9 @@ If you have resized your disk size to host a larger file system, consider creati
 ====
 endif::agent[]
 ifdef::agent[]
+[id="installation-user-infra-machines-advanced-disk_{context}"]
+= Creating disk partitions
+
 [role="_abstract"]
 To accommodate directories expected to grow, create separate partitions during the {op-system} installation. This configuration overrides the default partitioning layout, ensuring specific storage requirements are met for dynamic data.
 endif::agent[]

modules/installing-ocp-agent-ZTP.adoc

@@ -6,8 +6,11 @@
 [id="installing-ocp-agent-ztp_{context}"]
 = Using ZTP manifests
 
+[role="_abstract"]
 As an optional task, you can use {ztp-first} manifests to configure your installation beyond the options available through the `install-config.yaml` and `agent-config.yaml` files.
 
+See "Challenges of the network far edge" to learn more about {ztp-first}.
+
 [NOTE]
 ====
 {ztp} manifests can be generated with or without configuring the `install-config.yaml` and `agent-config.yaml` files beforehand.

modules/installing-ocp-agent-additional-manifests.adoc

@@ -0,0 +1,11 @@
+:_mod-docs-content-type: CONCEPT
+[id="installing-ocp-agent-opt-manifests_{context}"]
+= Creating additional manifest files
+
+[role="_abstract"]
+As an optional task, you can create additional manifests to further configure your cluster beyond the configurations available in the `install-config.yaml` and `agent-config.yaml` files.
+
+[IMPORTANT]
+====
+Customizations to the cluster made by additional manifests are not validated, are not guaranteed to work, and might result in a nonfunctional cluster.
+====

modules/installing-ocp-agent-boot.adoc

@@ -7,7 +7,8 @@
 [id="installing-ocp-agent-boot_{context}"]
 = Creating and booting the agent image
 
-Use this procedure to boot the agent image on your machines.
+[role="_abstract"]
+After you have prepared the configuration inputs for your installation, create the ISO image and boot it on your machines.
 
 .Prerequisites
 
@@ -22,7 +23,10 @@ Use this procedure to boot the agent image on your machines.
 $ openshift-install --dir <install_directory> agent create image
 ----
 +
-NOTE: Red Hat Enterprise Linux CoreOS (RHCOS) supports multipathing on the primary disk, allowing stronger resilience to hardware failure to achieve higher host availability. Multipathing is enabled by default in the agent ISO image, with a default `/etc/multipath.conf` configuration.
+[NOTE]
+====
+{op-system-first} supports multipathing on the primary disk, allowing stronger resilience to hardware failure to achieve higher host availability. Multipathing is enabled by default in the agent ISO image, with a default `/etc/multipath.conf` configuration.
+====
 
 . If you plan to boot the ISO image from a USB drive, add a master boot record to the image by running the following command:
 +

modules/installing-ocp-agent-download.adoc

@@ -9,7 +9,8 @@
 [id="installing-ocp-agent-retrieve_{context}"]
 = Downloading the Agent-based Installer
 
-Use this procedure to download the Agent-based Installer and the CLI needed for your installation.
+[role="_abstract"]
+Begin the installation process by downloading the Agent-based Installer and the CLI needed for your installation.
 
 .Procedure
 

modules/installing-ocp-agent-encrypt.adoc

@@ -6,7 +6,8 @@
 [id="installing-ocp-agent-encrypt_{context}"]
 = Encrypting the disk
 
-As an optional task, you can use this procedure to encrypt your disk or partition while installing {product-title} with the Agent-based Installer.
+[role="_abstract"]
+As an optional task, you can encrypt your disk or partition while installing {product-title} with the Agent-based Installer.
 
 [IMPORTANT]
 ====
@@ -53,10 +54,13 @@ $ cd <installation_directory>/cluster-manifests
 [source,yaml]
 ----
 diskEncryption:
-    enableOn: all <1>
-    mode: tang <2>
-    tangServers: "server1": "http://tang-server-1.example.com:7500" <3>
+    enableOn: all
+    mode: tang
+    tangServers: "server1": "http://tang-server-1.example.com:7500"
 ----
-<1> Specify which nodes to enable disk encryption on. Valid values are `none`, `all`, `masters`, and `workers`.
-<2> Specify which disk encryption mode to use. Valid values are `tpmv2` and `tang`.
-<3> Optional: If you are using Tang, specify the Tang servers.
++
+where:
+
+`diskEncryption.enableOn`:: Specifies which nodes to enable disk encryption on. Valid values are `none`, `all`, `masters`, and `workers`.
+`diskEncryption.mode`:: Specifies which disk encryption mode to use. Valid values are `tpmv2` and `tang`.
+`diskEncryption.tangServers`:: Specifies the Tang servers if you are using Tang. This value is optional.

modules/installing-ocp-agent-gather-log.adoc

@@ -7,7 +7,8 @@
 [id="installing-ocp-agent-gather-log_{context}"]
 = Gathering log data from a failed Agent-based installation
 
-Use the following procedure to gather log data about a failed Agent-based installation to provide for a support case.
+[role="_abstract"]
+If you encounter a failed Agent-based installation, you can gather log data to provide for a support case.
 
 .Prerequisites
 

modules/installing-ocp-agent-ibm-z-kvm.adoc

@@ -11,12 +11,16 @@ endif::[]
 [id="installing-ocp-agent-ibm-z-kvm_{context}"]
 = Adding {ibm-z-title} agents with {op-system-base} KVM
 
-Use the following procedure to manually add {ibm-z-name} agents with {op-system-base} KVM.
+[role="_abstract"]
+You can manually add {ibm-z-name} agents with {op-system-base} KVM.
+
 Only use this procedure for {ibm-z-name} clusters with {op-system-base} KVM.
+
 [NOTE]
 ====
 The `nmstateconfig` parameter must be configured for the KVM boot.
 ====
+
 .Procedure
 
 . Boot your {op-system-base} KVM machine.
@@ -33,7 +37,7 @@ $ virt-install \
    --ram=16384 \
    --cpu host \
    --vcpus=8 \
-   --location <path_to_kernel_initrd_image>,kernel=kernel.img,initrd=initrd.img \// <1>
+   --location <path_to_kernel_initrd_image>,kernel=kernel.img,initrd=initrd.img \
    --disk <qcow_image_path> \
    --network network:macvtap ,mac=<mac_address> \
    --graphics none \
@@ -48,7 +52,8 @@ $ virt-install \
    --extra-args "coreos.inst.persistent-kargs=console=tty1 console=ttyS1,115200n8" \
    --osinfo detect=on,require=off
 ----
-<1> For the `--location` parameter, specify the location of the `kernel` and `initrd` files. The location can be a local server path or a URL using HTTP or HTTPS.
++
+For the `--location` parameter, specify the location of the `kernel` and `initrd` files. The location can be a local server path or a URL using HTTP or HTTPS.
 
 endif::pxe-boot[]
 
@@ -63,15 +68,16 @@ $ virt-install
     --memory=<memory> \
     --cpu host \
     --vcpus=<vcpus> \
-    --cdrom \<path_to_image>/<agent_iso_image> \ <1>
+    --cdrom \<path_to_image>/<agent_iso_image> \
     --disk pool=default,size=<disk_pool_size> \
     --network network:default,mac=<mac_address> \
     --graphics none \
     --noautoconsole \
     --os-variant rhel9.0 \
     --wait=-1
 ----
-<1> For the `--cdrom` parameter, specify the location of the ISO image on the local server, for example, `<path_to_image>/home/<image>.iso`.
++
+For the `--cdrom` parameter, specify the location of the ISO image on the local server, for example, `<path_to_image>/home/<image>.iso`.
 +
 [NOTE]
 ====
@@ -93,7 +99,7 @@ $ virt-install \
    --ram=16384 \
    --cpu host \
    --vcpus=8 \
-   --location <path_to_kernel_initrd_image>,kernel=kernel.img,initrd=initrd.img \// <1>
+   --location <path_to_kernel_initrd_image>,kernel=kernel.img,initrd=initrd.img \
    --disk <qcow_image_path> \
    --network network:macvtap ,mac=<mac_address> \
    --graphics none \
@@ -106,21 +112,20 @@ $ virt-install \
    --extra-args "ignition.firstboot ignition.platform.id=metal" \
    --extra-args "console=tty1 console=ttyS1,115200n8" \
    --extra-args "coreos.inst.persistent-kargs=console=tty1 console=ttyS1,115200n8" \
-   --extra-args "fips=1" \// <2>
+   --extra-args "fips=1" \
    --osinfo detect=on,require=off
 ----
 +
-[NOTE]
-====
-For KVM-based installations using DASD devices on {ibm-z-title}, a partition (for example, `/dev/dasdb1`) must be created using the `fdasd` partitioning tool.
-====
-+
-<1> For the `--location` parameter, specify the location of the kernel/initrd on the HTTP or HTTPS server.
-<2> To enable FIPS mode, specify `fips=1`. This entry is required in addition to setting the `fips` parameter to `true` in the `install-config.yaml` file.
+where:
+
+`--location`:: Specifies the location of the kernel/initrd on the HTTP or HTTPS server.
+`--extra-args "fips=1"`:: Specifies the enablement of FIPS mode. This entry is required in addition to setting the `fips` parameter to `true` in the `install-config.yaml` file.
 +
 [NOTE]
 ====
-Currently, only PXE boot is supported to enable FIPS mode on {ibm-z-name}.
+* For KVM-based installations using DASD devices on {ibm-z-title}, a partition (for example, `/dev/dasdb1`) must be created using the `fdasd` partitioning tool.
+
+* Currently, only PXE boot is supported to enable FIPS mode on {ibm-z-name}.
 ====
 
 ifeval::["{context}" == "prepare-pxe-assets-agent"]