Merge pull request #102522 from jhradilek/cnv-modules-dita-prep

CNV-62649: Update CNV modules to pass DITA validation

Author: jhradilek

modules/virt-NUMA-prereqs.adoc

@@ -12,7 +12,8 @@ Before you can enable NUMA functionality with {VirtProductName} VMs, you must en
 * Worker nodes must have huge pages enabled.
 * The `KubeletConfig` object on worker nodes must be configured with the `cpuManagerPolicy: static` spec to guarantee dedicated CPU allocation, which is a prerequisite for NUMA pinning.
 +
-.Example `cpuManagerPolicy: static` spec
+Example `cpuManagerPolicy: static` spec:
++
 [source,yaml]
 ----
 apiVersion: machineconfiguration.openshift.io/v1

modules/virt-about-aaq-operator.adoc

@@ -6,6 +6,7 @@
 [id="virt-about-aaq-operator_{context}"]                                   
 = About the AAQ Operator
 
+[role="_abstract"]
 The Application-Aware Quota (AAQ) Operator provides more flexible and extensible quota management compared to the native `ResourceQuota` object in the {product-title} platform.
 
 In a multi-tenant cluster environment, where multiple workloads operate on shared infrastructure and resources, using the Kubernetes native `ResourceQuota` object to limit aggregate CPU and memory consumption presents infrastructure overhead and live migration challenges for {VirtProductName} workloads. 
@@ -21,7 +22,8 @@ The AAQ Operator introduces two new API objects defined as custom resource defin
 
 * `ApplicationAwareResourceQuota`: Sets aggregate quota restrictions enforced per namespace. The `ApplicationAwareResourceQuota` API is compatible with the native `ResourceQuota` object and shares the same specification and status definitions.
 +
-.Example manifest
+Example manifest:
++
 [source,yaml]
 ----
 apiVersion: aaq.kubevirt.io/v1alpha1
@@ -41,7 +43,8 @@ spec:
 
 * `ApplicationAwareClusterResourceQuota`: Mirrors the `ApplicationAwareResourceQuota` object at a cluster scope. It is compatible with the native `ClusterResourceQuota` API object and shares the same specification and status definitions. When creating an AAQ cluster quota, you can select multiple namespaces based on annotation selection, label selection, or both by editing the `spec.selector.labels` or `spec.selector.annotations` fields.
 +
-.Example manifest
+Example manifest:
++
 [source,yaml]
 ----
 apiVersion: aaq.kubevirt.io/v1alpha1

modules/virt-about-application-consistent-backups.adoc

@@ -6,8 +6,9 @@
 [id="virt-about-application-consistent-backups_{context}"]
 = About application-consistent snapshots and backups
 
-You can configure application-consistent snapshots and backups for Linux or Windows virtual machines (VMs) through a cycle of freezing and thawing. For any application, you can either configure a script on a Linux VM or register on a Windows VM to be notified when a snapshot or backup is due to begin.
+[role="_abstract"]
+You can configure application-consistent snapshots and backups for Linux or Windows virtual machines (VMs) through a cycle of freezing and thawing. For any application, you can configure a script on a Linux VM or register on a Windows VM to be notified when a snapshot or backup is due to begin.
 
 On a Linux VM, freeze and thaw processes trigger automatically when a snapshot is taken or a backup is started by using, for example, a plugin from Velero or another backup vendor. The freeze process, performed by QEMU Guest Agent (QEMU GA) freeze hooks, ensures that before the snapshot or backup of a VM occurs, all of the VM's filesystems are frozen and each appropriately configured application is informed that a snapshot or backup is about to start. This notification affords each application the opportunity to quiesce its state. Depending on the application, quiescing might involve temporarily refusing new requests, finishing in-progress operations, and flushing data to disk. The operating system is then directed to quiesce the filesystems by flushing outstanding writes to disk and freezing new write activity. All new connection requests are refused. When all applications have become inactive, the QEMU GA freezes the filesystems, and a snapshot is taken or a backup initiated. After the taking of the snapshot or start of the backup, the thawing process begins. Filesystems writing is reactivated and applications receive notification to resume normal operations.
 
-The same cycle of freezing and thawing is available on a Windows VM. Applications register with the Volume Shadow Copy Service (VSS) to receive notifications that they should flush out their data because a backup or snapshot is imminent. Thawing of the applications after the backup or snapshot is complete returns them to an active state. For more details, see the Windows Server documentation about the Volume Shadow Copy Service.
+The same cycle of freezing and thawing is available on a Windows VM. Applications register with the Volume Shadow Copy Service (VSS) to receive notifications that they should flush out their data because a backup or snapshot is imminent. Thawing of the applications after the backup or snapshot is complete returns them to an active state. For more details, see the Windows Server documentation about the Volume Shadow Copy Service.

modules/virt-about-auto-bootsource-updates.adoc

@@ -7,12 +7,13 @@
 [id="virt-about-auto-bootsource-updates_{context}"]
 = About automatic boot source updates
 
-Boot sources can make virtual machine (VM) creation more accessible and efficient for users. If automatic boot source updates are enabled, the Containerized Data Importer (CDI) imports, polls, and updates the images so that they are ready to be cloned for new VMs. By default, CDI automatically updates the _system-defined_ boot sources that {VirtProductName} provides.
+[role="_abstract"]
+Boot sources can make virtual machine (VM) creation more accessible and efficient for users. If automatic boot source updates are enabled, the Containerized Data Importer (CDI) imports, polls, and updates the images so that they are ready to be cloned for new VMs.
 
-You can opt out of automatic updates for all system-defined boot sources by disabling the `enableCommonBootImageImport` feature gate. If you disable this feature gate, all `DataImportCron` objects are deleted. This does not remove previously imported boot source objects that store operating system images, though administrators can delete them manually.
+By default, CDI automatically updates the _system-defined_ boot sources that {VirtProductName} provides. You can opt out of automatic updates for all system-defined boot sources by disabling the `enableCommonBootImageImport` feature gate. If you disable this feature gate, all `DataImportCron` objects are deleted. This does not remove previously imported boot source objects that store operating system images, though administrators can delete them manually.
 
 When the `enableCommonBootImageImport` feature gate is disabled, `DataSource` objects are reset so that they no longer point to the original boot source. An administrator can manually provide a boot source by populating a PVC with an operating system, optionally creating a volume snapshot from the PVC, and then referring to the PVC or volume snapshot from the `DataSource` object.
 
 _Custom_ boot sources that are not provided by {VirtProductName} are not controlled by the feature gate. You must manage them individually by editing the `HyperConverged` custom resource (CR). You can also use this method to manage individual system-defined boot sources.
 
-Cluster administrators can enable automatic subscription for {op-system-base-full} virtual machines in the {product-title} web console.
+Cluster administrators can enable automatic subscription for {op-system-base-full} virtual machines in the {product-title} web console.

modules/virt-about-block-pvs.adoc

@@ -8,6 +8,7 @@
 [id="virt-about-block-pvs_{context}"]
 = About block persistent volumes
 
+[role="_abstract"]
 A block persistent volume (PV) is a PV that is backed by a raw block device. These volumes
 do not have a file system and can provide performance benefits for
 virtual machines by reducing overhead.

modules/virt-about-cdi-operator.adoc

@@ -6,6 +6,7 @@
 [id="virt-about-cdi-operator_{context}"]
 = About the Containerized Data Importer (CDI) Operator
 
+[role="_abstract"]
 The CDI Operator, `cdi-operator`, manages CDI and its related resources, which imports a virtual machine (VM) image into a persistent volume claim (PVC) by using a data volume.
 
 image::cnv_components_cdi-operator.png[cdi-operator components]

modules/virt-about-changing-removing-mediated-devices.adoc

@@ -6,6 +6,9 @@
 [id="about-changing-removing-mediated-devices_{context}"]
 = About changing and removing mediated devices
 
+[role="_abstract"]
+As an administrator, you can change or remove mediated devices by editing the `HyperConverged` custom resource (CR).
+
 You can reconfigure or remove mediated devices in several ways:
 
 * Edit the `HyperConverged` CR and change the contents of the `mediatedDeviceTypes` stanza.
@@ -17,4 +20,4 @@ You can reconfigure or remove mediated devices in several ways:
 [NOTE]
 ====
 If you remove the device information from the `spec.permittedHostDevices` stanza without also removing it from the `spec.mediatedDevicesConfiguration` stanza, you cannot create a new mediated device type on the same node. To properly remove mediated devices, remove the device information from both stanzas.
-====
+====

modules/virt-about-cloning.adoc

@@ -6,12 +6,10 @@
 [id="virt-about-cloning_{context}"]
 = About cloning
 
-When cloning a data volume, the Containerized Data Importer (CDI) chooses one of the following Container Storage Interface (CSI) clone methods:
+[role="_abstract"]
+When cloning a data volume, the Containerized Data Importer (CDI) chooses one of the Container Storage Interface (CSI) clone methods: CSI volume cloning or smart cloning. Both methods are efficient but have certain requirements. If the requirements are not met, the CDI uses host-assisted cloning.
 
-* CSI volume cloning
-* Smart cloning
-
-Both CSI volume cloning and smart cloning methods are efficient, but they have certain requirements for use. If the requirements are not met, the CDI uses host-assisted cloning. Host-assisted cloning is the slowest and least efficient method of cloning, but it has fewer requirements than either of the other two cloning methods.
+Host-assisted cloning is the slowest and least efficient method of cloning, but it has fewer requirements than either of the other two cloning methods.
 
 [id="csi-volume-cloning_{context}"]
 == CSI volume cloning
@@ -47,7 +45,7 @@ When the requirements for neither Container Storage Interface (CSI) volume cloni
 
 Host-assisted cloning uses a source pod and a target pod to copy data from the source volume to the target volume. The target persistent volume claim (PVC) is annotated with the fallback reason that explains why host-assisted cloning has been used, and an event is created.
 
-.Example PVC target annotation
+Example PVC target annotation:
 
 [source,yaml]
 ----
@@ -60,7 +58,7 @@ metadata:
     cdi.kubevirt.io/cloneType: copy
 ----
 
-.Example event
+Example event:
 
 [source,terminal]
 ----

modules/virt-about-cluster-network-addons-operator.adoc

@@ -6,6 +6,7 @@
 [id="virt-about-cluster-network-addons-operator_{context}"]
 = About the Cluster Network Addons Operator
 
+[role="_abstract"]
 The Cluster Network Addons Operator, `cluster-network-addons-operator`, deploys networking components on a cluster and manages the related resources for extended network functionality.
 
 image::cnv_components_cluster-network-addons-operator.png[cluster-network-addons-operator components]

modules/virt-about-control-plane-only-updates.adoc

@@ -6,7 +6,10 @@
 [id="virt-about-control-plane-only-updates_{context}"]
 = Control Plane Only updates
 
-Every even-numbered minor version of {product-title} is an Extended Update Support (EUS) version. However, Kubernetes design mandates serial minor version updates, so you cannot directly update from one EUS version to the next. An EUS-to-EUS update starts with updating {VirtProductName} to the latest z-stream of the next odd-numbered minor version. Next, update {product-title} to the target EUS version. When the {product-title} update succeeds, the corresponding update for {VirtProductName} becomes available. You can now update {VirtProductName} to the target EUS version.
+[role="_abstract"]
+Every even-numbered minor version of {product-title} is an Extended Update Support (EUS) version. However, Kubernetes design mandates serial minor version updates, so you cannot directly update from one EUS version to the next.
+
+An EUS-to-EUS update starts with updating {VirtProductName} to the latest z-stream of the next odd-numbered minor version. Next, update {product-title} to the target EUS version. When the {product-title} update succeeds, the corresponding update for {VirtProductName} becomes available. You can now update {VirtProductName} to the target EUS version.
 
 [NOTE]
 ====
@@ -29,4 +32,4 @@ Before beginning a Control Plane Only update, you must:
 By default, {VirtProductName} automatically updates workloads, such as the `virt-launcher` pod, when you update the {VirtProductName} Operator. You can configure this behavior in the `spec.workloadUpdateStrategy` stanza of the `HyperConverged` custom resource.
 ====
 
-// link to EUS to EUS docs in assembly due to module limitations
+// link to EUS to EUS docs in assembly due to module limitations