CNV-1396 Cloning a DataVolume using smart-cloning

_topic_map.yml

@@ -2348,6 +2348,8 @@ Topics:
       File: virt-moving-local-vm-disk-to-different-node
     - Name: Expanding virtual storage by adding blank disk images
       File: virt-expanding-virtual-storage-with-blank-disk-images
+    - Name: Cloning a DataVolume using smart-cloning
+      File: virt-cloning-a-datavolume-using-smart-cloning
     - Name: Storage defaults for DataVolumes
       File: virt-storage-defaults-for-datavolumes
     - Name: Preparing CDI scratch space

modules/virt-cloning-a-datavolume.adoc

@@ -0,0 +1,77 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/virtual_disks/virt-cloning-a-datavolume-using-smart-cloning.adoc
+
+// `blockstorage` conditionals are used (declared in the "*-block" assembly) to separate content
+
+[id="virt-cloning-a-datavolume_{context}"]
+= Cloning a DataVolume
+
+.Prerequisites
+
+For smart-cloning to occur:
+
+* Your storage provider must support snapshots.
+* The source and target PVCs must be defined to the same namespace.
+* The source and target PVCs must be defined to the same storage class.
+* The VolumeSnapshotClass object must reference the storage class defined to both the source and target PVCs.
+
+If any of these prerequisites are not met, host-assisted cloning occurs when you create a DataVolume with a
+PVC source.
+
+.Procedure
+
+To initiate cloning of a DataVolume:
+
+. Create a YAML file for a DataVolume object that specifies the name of the
+new DataVolume, the name and namespace of the source PVC,
+ifdef::blockstorage[]
+`volumeMode: Block` so that an available block PV is used,
+endif::[]
+and the size of the new DataVolume.
++
+For example:
++
+[source,yaml]
+----
+apiVersion: cdi.kubevirt.io/v1beta1
+kind: DataVolume
+metadata:
+  name: <cloner-datavolume> <1>
+spec:
+  source:
+    pvc:
+      namespace: "<source-namespace>" <2>
+      name: "<my-favorite-vm-disk>" <3>
+  pvc:
+    accessModes:
+      - ReadWriteOnce
+    resources:
+      requests:
+        storage: <2Gi> <4>
+ifdef::blockstorage[]
+    volumeMode: Block <5>
+endif::[]
+----
+<1> The name of the new DataVolume.
+<2> The namespace where the source PVC exists.
+<3> The name of the source PVC.
+<4> The size of the new DataVolume. You must allocate enough space, or the
+cloning operation fails. The size must be the same as or larger than the source PVC.
+ifdef::blockstorage[]
+<5> Specifies that the destination is a block PV
+endif::[]
+
+. Start cloning the PVC by creating the DataVolume:
++
+[source,terminal]
+----
+$ oc create -f <cloner-datavolume>.yaml
+----
++
+[NOTE]
+====
+DataVolumes prevent a virtual machine from starting before the PVC is prepared,
+so you can create a virtual machine that references the new DataVolume while the
+PVC clones.
+====

modules/virt-understanding-smart-cloning.adoc

@@ -0,0 +1,15 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/virtual_disks/virt-cloning-a-datavolume-using-smart-cloning.adoc
+
+[id="virt-understanding-smart-cloning_{context}"]
+= Understanding smart-cloning
+
+Smart-cloning creates a clone of a DataVolume using the most efficient method available,
+either by snapshot or host-assisted cloning.
+
+When a DataVolume is smart-cloned, the following occurs:
+
+. A snapshot of the source PersistentVolumeClaim (PVC) is created.
+. A PVC is created from the snapshot.
+. The snapshot is deleted.

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

@@ -0,0 +1,21 @@
+[id="virt-cloning-a-datavolume-using-smart-cloning"]
+= Cloning a DataVolume using smart-cloning
+include::modules/virt-document-attributes.adoc[]
+:context: virt-cloning-a-datavolume-using-smart-cloning
+toc::[]
+
+When you clone a DataVolume, you make a copy of it.
+
+By cloning, you reduce the amount of time it takes to deploy many
+virtual machines at one time.
+
+Cloning happens automatically when you create a DataVolume with a
+PersistentVolumeClaim (PVC) source.
+
+include::modules/virt-understanding-smart-cloning.adoc[leveloffset=+1]
+
+include::modules/virt-cloning-a-datavolume.adoc[leveloffset=+1]
+
+== Additional resources
+
+* xref:../../../virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume.html#virt-cloning-pvc-of-vm-disk-into-new-datavolume_virt-cloning-vm-disk-into-new-datavolume[Cloning the PersistentVolumeClaim of a virtual machine disk into a new DataVolume]