Merge pull request #72553 from aspauldi/CNV-28093

CNV-28093: DOC: Cloning strategies and how to check which one was used

Author: jeana-redhat

modules/virt-about-cloning.adoc

@@ -0,0 +1,69 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/virt-creating-vms-by-cloning-pvcs.adoc
+
+:_mod-docs-content-type: CONCEPT
+[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:
+
+* 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.
+
+[id="csi-volume-cloning_{context}"]
+== CSI volume cloning
+
+Container Storage Interface (CSI) cloning uses CSI driver features to more efficiently clone a source data volume.
+
+CSI volume cloning has the following requirements:
+
+* The CSI driver that backs the storage class of the persistent volume claim (PVC) must support volume cloning.
+* For provisioners not recognized by the CDI, the corresponding storage profile must have the `cloneStrategy` set to CSI Volume Cloning.
+* The source and target PVCs must have the same storage class and volume mode.
+* If you create the data volume, you must have permission to create the `datavolumes/source` resource in the source namespace.
+* The source volume must not be in use.
+
+
+[id="smart-cloning_{context}"]
+== Smart cloning
+
+When a Container Storage Interface (CSI) plugin with snapshot capabilities is available, the Containerized Data Importer (CDI) creates a persistent volume claim (PVC) from a snapshot, which then allows efficient cloning of additional PVCs.
+
+Smart cloning has the following requirements:
+
+* A snapshot class associated with the storage class must exist.
+* The source and target PVCs must have the same storage class and volume mode.
+* If you create the data volume, you must have permission to create the `datavolumes/source` resource in the source namespace.
+* The source volume must not be in use.
+
+
+[id="host-assisted-cloning_{context}"]
+== Host-assisted cloning
+
+When the requirements for neither Container Storage Interface (CSI) volume cloning nor smart cloning have been met, host-assisted cloning is used as a fallback method. Host-assisted cloning is less efficient than either of the two other cloning methods.
+
+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
+
+[source,yaml]
+----
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  annotations:
+    cdi.kubevirt.io/cloneFallbackReason: The volume modes of source and target are incompatible
+    cdi.kubevirt.io/clonePhase: Succeeded
+    cdi.kubevirt.io/cloneType: copy
+----
+
+.Example event
+
+[source,terminal]
+----
+NAMESPACE   LAST SEEN   TYPE      REASON                    OBJECT                              MESSAGE
+test-ns     0s          Warning   IncompatibleVolumeModes   persistentvolumeclaim/test-target   The volume modes of source and target are incompatible
+----

virt/virtual_machines/creating_vms_custom/virt-creating-vms-by-cloning-pvcs.adoc

@@ -8,10 +8,11 @@ toc::[]
 
 You can create virtual machines (VMs) by cloning existing persistent volume claims (PVCs) with custom images.
 
-You clone a PVC by creating a data volume that references a source PVC.
-
 You must install the xref:../../../virt/virtual_machines/creating_vms_custom/virt-installing-qemu-guest-agent.adoc#virt-installing-qemu-guest-agent[QEMU guest agent] on VMs created from operating system images that are not provided by Red Hat.
 
+You clone a PVC by creating a data volume that references a source PVC.
+
+include::modules/virt-about-cloning.adoc[leveloffset=+1]
 include::modules/virt-creating-vm-custom-image-web.adoc[leveloffset=+1]
 
 [id="creating-vm-by-cloning-pvcs-cli"]