Adding a new assembly and modules to cover preallocation mode for CDI operations.

Author: aburdenthehand

_topic_map.yml

@@ -2623,6 +2623,8 @@ Topics:
       File: virt-reserving-pvc-space-fs-overhead
     - Name: Configuring CDI to work with namespaces that have a compute resource quota
       File: virt-configuring-cdi-for-namespace-resourcequota
+    - Name: Using preallocation for data volumes
+      File: virt-using-preallocation-for-datavolumes
     - Name: Uploading local disk images by using the web console
       File: virt-uploading-local-disk-images-web
     - Name: Uploading local disk images by using the virtctl tool

modules/virt-about-preallocation.adoc

@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc
+
+[id="virt-about-preallocation_{context}"]
+= About preallocation
+
+The Containerized Data Importer (CDI) can use the QEMU preallocate mode for data volumes to improve write performance. You can use preallocation mode for importing and uploading operations and when creating blank data volumes.
+
+If preallocation is enabled, the CDI uses the better preallocation method depending on the underlying file system and device type:
+
+`fallocate`::
+If the file system supports it, CDI uses the operating system's `fallocate` call to preallocate space by using the `posix_fallocate` function, which allocates blocks and marks them as uninitialized. 
+
+`full`::
+If `fallocate` mode cannot be used, `full` mode allocates space for the image by writing data to the underlying storage. Depending on the storage location, all the empty allocated space might be zeroed.

modules/virt-enabling-preallocation-for-dv.adoc

@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc
+
+[id="virt-enabling-preallocation-for-dv_{context}"]
+= Enabling preallocation for a data volume
+
+If preallocation is not globally enabled for the cluster, you can enable it for specific data volumes by including the `spec.preallocation` field in the data volume manifest. You can enable preallocation mode in either the web console or by using the OpenShift client (`oc`).
+
+Preallocation mode is supported for all CDI source types.
+
+.Procedure
+
+* Specify the `spec.preallocation` field in the data volume manifest:
++
+[source,yaml]
+----
+apiVersion: cdi.kubevirt.io/v1beta1
+kind: DataVolume
+metadata:
+  name: preallocated-datavolume
+spec:
+  source: <1>
+    ...
+  pvc:
+    ...
+  preallocation: true <2>
+----
+<1> All CDI source types support preallocation, however preallocation is ignored for cloning operations.
+<2> The `preallocation` field is a boolean that defaults to false.
+

modules/virt-enabling-preallocation-globally.adoc

@@ -0,0 +1,39 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc
+
+[id="virt-enabling-preallocation-globally_{context}"]
+= Enabling preallocation globally
+
+You can enable cluster-wide preallocation mode for the Containerized Data Importer (CDI) by adding the `prellocation` field to the `CDI` object.
+
+.Prerequisites
+
+* Install the OpenShift client (`oc`).
+
+.Procedure
+
+. Use the `oc` client to edit the `CDI` object:
++
+[source,terminal]
+----
+$ oc edit cdi
+----
+
+. Set the `spec.config.preallocation` field with a value of `true`:
++
+[source,yaml]
+----
+apiVersion: cdi.kubevirt.io/v1beta1
+kind: CDI
+metadata:
+...
+spec:
+  config:
+    preallocation: true <1>
+----
+<1> The `preallocation` field is a boolean that defaults to false.
+
+. Save and exit your editor to update the `CDI` object and enable prellocation mode.
+
+

virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume-block.adoc

@@ -31,3 +31,4 @@ include::modules/virt-cloning-pvc-of-vm-disk-into-new-datavolume.adoc[leveloffse
 include::modules/virt-cdi-supported-operations-matrix.adoc[leveloffset=+1]
 
 :blockstorage!:
+

virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume.adoc

@@ -26,3 +26,4 @@ include::modules/virt-cloning-pvc-of-vm-disk-into-new-datavolume.adoc[leveloffse
 include::modules/virt-template-datavolume-clone.adoc[leveloffset=+1]
 
 include::modules/virt-cdi-supported-operations-matrix.adoc[leveloffset=+1]
+

virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes-block.adoc

@@ -35,3 +35,9 @@ include::modules/virt-creating-local-block-pv.adoc[leveloffset=+1]
 include::modules/virt-importing-vm-to-block-pv.adoc[leveloffset=+1]
 
 include::modules/virt-cdi-supported-operations-matrix.adoc[leveloffset=+1]
+
+[id="{context}_additional-resources"]
+== Additional resources
+
+* xref:../../../virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc#virt-using-preallocation-for-datavolumes[Configure preallocation mode] to improve write performance for data volume operations.
+

virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes.adoc

@@ -38,3 +38,8 @@ include::modules/virt-importing-vm-datavolume.adoc[leveloffset=+1]
 // include::modules/virt-template-datavolume-vm.adoc[leveloffset=+1]
 
 // include::modules/virt-template-datavolume-import.adoc[leveloffset=+1]
+
+[id="{context}_additional-resources"]
+== Additional resources
+
+* xref:../../../virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc#virt-using-preallocation-for-datavolumes[Configure preallocation mode] to improve write performance for data volume operations.

virt/virtual_machines/virtual_disks/virt-cloning-a-datavolume-using-smart-cloning.adoc

@@ -15,6 +15,9 @@ include::modules/virt-understanding-smart-cloning.adoc[leveloffset=+1]
 
 include::modules/virt-cloning-a-datavolume.adoc[leveloffset=+1]
 
+[id="{context}_additional-resources"]
 == Additional resources
 
 * xref:../../../virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume.adoc#virt-cloning-pvc-of-vm-disk-into-new-datavolume_virt-cloning-vm-disk-into-new-datavolume[Cloning the persistent volume claim of a virtual machine disk into a new data volume]
+
+* xref:../../../virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc#virt-using-preallocation-for-datavolumes[Configure preallocation mode] to improve write performance for data volume operations.

virt/virtual_machines/virtual_disks/virt-expanding-virtual-storage-with-blank-disk-images.adoc

@@ -11,4 +11,9 @@ include::modules/virt-about-datavolumes.adoc[leveloffset=+1]
 
 include::modules/virt-creating-blank-disk-datavolumes.adoc[leveloffset=+1]
 
-include::modules/virt-template-blank-disk-datavolume.adoc[leveloffset=+1]
+include::modules/virt-template-blank-disk-datavolume.adoc[leveloffset=+1]
+
+[id="{context}_additional-resources"]
+== Additional resources
+
+* xref:../../../virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc#virt-using-preallocation-for-datavolumes[Configure preallocation mode] to improve write performance for data volume operations.