CNV-5258: FS overhead space

Author: ousleyp

_topic_map.yml

@@ -2538,6 +2538,8 @@ Topics:
       File: virt-features-for-storage
     - Name: Configuring local storage for virtual machines
       File: virt-configuring-local-storage-for-vms
+    - Name: Reserving PVC space for file system overhead
+      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: Uploading local disk images by using the web console

modules/virt-how-fs-overhead-affects-space-vm-disks.adoc

@@ -0,0 +1,15 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/virtual_disks/virt-reserving-pvc-space-fs-overhead.adoc
+
+[id="virt-how-fs-overhead-affects-space-vm-disks_{context}"]
+= How file system overhead affects space for virtual machine disks
+
+When you add a virtual machine disk to a persistent volume claim (PVC) that uses the `Filesystem` volume mode, you must ensure that there is enough space on the PVC for:
+
+* The virtual machine disk.
+* The space that the Containerized Data Importer (CDI) reserves for file system overhead, such as metadata.
+
+By default, the CDI reserves 5.5% of the PVC space for overhead, reducing the space available for virtual machine disks by that amount.
+
+If a different value works better for your use case, you can configure the overhead value by editing the `CDI` object. You can change the value globally and you can specify values for specific storage classes.

modules/virt-overriding-default-fs-overhead-value.adoc

@@ -0,0 +1,47 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/virtual_disks/virt-reserving-pvc-space-fs-overhead.adoc
+
+[id="virt-overriding-default-fs-overhead-value_{context}"]
+= Overriding the default file system overhead value
+
+Change the amount of persistent volume claim (PVC) space that the Containerized Data Importer (CDI) reserves for file system overhead by editing the `spec.config.filesystemOverhead` attribute of the `CDI` object.
+
+.Prerequisites
+
+* Install the OpenShift CLI (`oc`).
+
+.Procedure
+
+. Open the `CDI` object for editing by running the following command:
++
+[source,terminal]
+----
+$ oc edit cdi
+----
+
+. Edit the `spec.config.filesystemOverhead` fields, populating them with your chosen values:
++
+[source,yaml]
+----
+...
+spec:
+  config:
+    filesystemOverhead:
+      global: "<new_global_value>" <1>
+      storageClass:
+        <storage_class_name>: "<new_value_for_this_storage_class>" <2>
+----
+<1> The file system overhead percentage that CDI uses across the cluster. For example, `global: "0.07"` reserves 7% of the PVC for file system overhead.
+<2> The file system overhead percentage for the specified storage class. For example, `mystorageclass: "0.04"` changes the default overhead value for PVCs in the `mystorageclass` storage class to 4%.
+
+. Save and exit the editor to update the `CDI` object.
+
+.Verification steps
+
+* View the `CDI` status and verify your changes by running the following command:
++
+[source,terminal]
+----
+$ oc get cdi -o yaml
+----

virt/virtual_machines/virtual_disks/virt-reserving-pvc-space-fs-overhead.adoc

@@ -0,0 +1,11 @@
+[id="virt-reserving-pvc-space-fs-overhead"]
+= Reserving PVC space for file system overhead
+include::modules/virt-document-attributes.adoc[]
+:context: virt-reserving-pvc-space-fs-overhead
+toc::[]
+
+By default, the Containerized Data Importer (CDI) reserves space for file system overhead data in persistent volume claims (PVCs) that use the `Filesystem` volume mode. You can set the percentage that CDI reserves for this purpose globally and for specific storage classes.
+
+include::modules/virt-how-fs-overhead-affects-space-vm-disks.adoc[leveloffset=+1]
+
+include::modules/virt-overriding-default-fs-overhead-value.adoc[leveloffset=+1]