From ab184640d01291a4506a9dffee62d39fa1ad3a49 Mon Sep 17 00:00:00 2001
From: akalenyu <akalenyu@redhat.com>
Date: Fri, 23 Jun 2023 02:06:33 +0300
Subject: [PATCH] Add DataImportCron snapshot sources docs (#2747)

Signed-off-by: Alex Kalenyuk <akalenyu@redhat.com>
---
 doc/os-image-poll-and-update.md | 30 +++++++++++++++++++++++++++---
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/doc/os-image-poll-and-update.md b/doc/os-image-poll-and-update.md
index 8e197f38b2..2b6f007f34 100644
--- a/doc/os-image-poll-and-update.md
+++ b/doc/os-image-poll-and-update.md
@@ -1,6 +1,6 @@
 # Automated OS image import, poll and update
 
-CDI supports automating OS image import, poll and update, keeping OS images up-to-date according to the given `schedule`. On the first time a `DataImportCron` is scheduled, the controller will import the source image. On any following scheduled poll, if the source image digest (sha256) has updated, the controller will import it to a new `PVC` in the `DataImportCron` namespace, and update the managed `DataSource` to point that `PVC`. A garbage collector (`garbageCollect: Outdated` enabled by default) is responsible to keep the last `importsToKeep` (3 by default) imported `PVCs` per `DataImportCron`, and delete older ones.
+CDI supports automating OS image import, poll and update, keeping OS images up-to-date according to the given `schedule`. On the first time a `DataImportCron` is scheduled, the controller will import the source image. On any following scheduled poll, if the source image digest (sha256) has updated, the controller will import it to a new [*source*](#dataimportcron-source-formats) in the `DataImportCron` namespace, and update the managed `DataSource` to point to the newly created source. A garbage collector (`garbageCollect: Outdated` enabled by default) is responsible to keep the last `importsToKeep` (3 by default) imported sources per `DataImportCron`, and delete older ones.
 
 See design doc [here](https://github.com/kubevirt/community/blob/main/design-proposals/golden-image-delivery-and-update-pipeline.md)
 
@@ -29,7 +29,7 @@ spec:
   managedDataSource: fedora
 ```
 
-A `DataVolume` can use a `sourceRef` referring to a `DataSource`, instead of the `source`, so whenever created it will use the updated referred `PVC` similarly to a `source.PVC`. 
+A `DataVolume` can use a `sourceRef` referring to a `DataSource`, instead of the `source`, so whenever created it will use the latest imported source similarly to specifying `dv.spec.source`. 
 
 ```yaml
 apiVersion: cdi.kubevirt.io/v1beta1
@@ -84,4 +84,28 @@ Or on CRC:
 * oc import-image cirros-is -n openshift-virtualization-os-images --from=kubevirt/cirros-container-disk-demo --scheduled --confirm
 * oc set image-lookup cirros-is -n openshift-virtualization-os-images
 
-More information on image streams is available [here](https://docs.openshift.com/container-platform/4.8/openshift_images/image-streams-manage.html) and [here](https://www.tutorialworks.com/openshift-imagestreams).
\ No newline at end of file
+More information on image streams is available [here](https://docs.openshift.com/container-platform/4.13/openshift_images/image-streams-manage.html) and [here](https://www.tutorialworks.com/openshift-imagestreams).
+
+## DataImportCron source formats
+
+* PersistentVolumeClaim
+* VolumeSnapshot
+
+DataImportCron was originally designed to only maintain PVC sources,  
+However, for certain storage types, we know that snapshots sources scale better.  
+Some details and examples can be found in [clone-from-volumesnapshot-source](./clone-from-volumesnapshot-source.md).
+
+We keep this provisioner-specific information on the [StorageProfile](./storageprofile.md) object for each provisioner at the `dataImportCronSourceFormat` field (possible values are `snapshot`/`pvc`), which tells the DataImportCron which type of source is preferred for the provisioner.  
+
+Some provisioners like ceph rbd are opted in automatically.  
+To opt-in manually, one must edit the `StorageProfile`:
+```yaml
+apiVersion: cdi.kubevirt.io/v1beta1
+kind: StorageProfile
+metadata:
+  ...
+spec:
+  dataImportCronSourceFormat: snapshot
+```
+
+To ensure smooth transition, existing DataImportCrons can be switchd to maintaining snapshots instead of PVCs by updating their corresponding storage profiles.