F OpenNebula/one#7902: Document cross-datastore image cloning

content/product/integration_references/infrastructure_drivers_development/devel-market.md

@@ -98,9 +98,9 @@ The `import` action is an special action that involves two driver calls chained
 
 The job of the export is to:
 
-* Calculate the `MD5`, `FORMAT`, `SIZE`.
-* Generate an `IMPORT_SOURCE` so the `<market_mad>/import` can do the image => market dump.
-* Specify `DISPOSE="YES"` and `DISPOSE_CMD`  if the `IMPORT_SOURCE` is a temporary file that must be removed after the dump performed by `<market_mad>/import`. `DISPOSE="NO"` if otherwise.
+* Return the required `FORMAT` and `SIZE` and, when available, the `MD5` or `SHA1` checksum.
+* Generate an `IMPORT_SOURCE` so the `<market_mad>/import` can copy the Image into the Marketplace.
+* Return an opaque `DISPOSE_DATA` value if the export creates temporary resources. The Datastore driver's `dispose_export` action receives this value after the Marketplace import finishes, whether it succeeds or fails.
 
 **ARGUMENTS**
 
@@ -113,13 +113,17 @@ It should return an XML document:
 ```default
 <IMPORT_INFO>
     <IMPORT_SOURCE>$IMPORT_SOURCE</IMPORT_SOURCE>
-    <MD5>$MD5_SUM</MD5>
-    <SIZE>$SIZE</SIZE>
     <FORMAT>$FORMAT</FORMAT>
-    <DISPOSE>NO</DISPOSE>
-</IMPORT_INFO>"
+    <SIZE>$SIZE</SIZE>
+    <MD5>$MD5_SUM</MD5>
+    <DISPOSE_DATA>$DRIVER_SPECIFIC_DATA</DISPOSE_DATA>
+</IMPORT_INFO>
 ```
 
+`MD5`, `SHA1`, and `DISPOSE_DATA` are optional. If `DISPOSE_DATA` is present, the same Datastore driver must implement an idempotent `dispose_export` action. See the [`IMPORT_INFO` structure and Datastore export operations]({{% relref "sd#sd-export" %}}) for details.
+
+The legacy `DISPOSE` and `DISPOSE_CMD` fields remain supported for existing Marketplace integrations. New Datastore drivers should use `DISPOSE_DATA` and `dispose_export` instead.
+
 `<market_mad>/import`:
 
 The job of the export is to grab the `IMPORT_SOURCE` and dump it to the backend.

content/product/integration_references/infrastructure_drivers_development/sd.md

@@ -80,16 +80,25 @@ Located under `/var/lib/one/remotes/datastore/<ds_mad>`
   - `datastore_image_dump` is an XML dump of the driver action encoded in Base 64. See a decoded [example]({{% relref "#sd-dump" %}}). This dump, in addition to the elements in the example, contains a ROOT element: `TARGET_SNAPSHOT`, with the ID of the snapshot.
   - `size` the size in MB.
   - `chain` chain spec in format <base_id>:<base_hash>[,<inc_id>:<inc_hash>]\*.
-- **export**: Generates an XML file required to export an image from a datastore. This script represents only the first part of the export process, it only generates metadata (an xml). The information returned by this script is then fed to `downloader.sh` which completes the export process
+- **export**: Generates the metadata required to read an Image from a Datastore. The resulting source can be consumed by a Marketplace driver or by another Datastore driver during a cross-driver Image clone.
   - **ARGUMENTS**: `image_id`
   - **STDIN**: `datastore_image_dump`
   - **RETURNS**: `export_xml`
   - `datastore_image_dump` is an XML dump of the driver action encoded in Base 64. See a decoded [example]({{% relref "#sd-dump" %}}). This dump, in addition to the elements in the example, contains a ROOT element: `TARGET_SNAPSHOT`, with the ID of the snapshot.
-  - `export_xml`: The XML response should follow [this]({{% relref "#sd-export" %}}) structure. The variables that appear within are the following:
-    > - `<src>`: The SOURCE of the image (path to the image in the datastore)
-    > - `<md5>`: The MD5 of the image
-    > - `<format>`: The format of the image, e.g.: `qcow2`, `raw`, `vmdk`, `unknown`…
-    > - `<dispose>`: Can be either `YES` or `NO`. Dispose will remove the image from the reported path after the image has been successfully exported. This is regularly not necessary if the `downloader.sh` script can access the path to the image directly in the datastore (`src`).
+  - `export_xml`: The XML response must follow the [`IMPORT_INFO` structure]({{% relref "#sd-export" %}}).
+- **dispose_export**: Releases temporary resources created by `export`. Cross-driver clones invoke this action after the destination finishes consuming the export, whether the import succeeds or fails.
+  - **ARGUMENTS**: `image_id`
+  - **STDIN**: `datastore_image_dump` with the `IMPORT_INFO` returned by `export` appended to the root element.
+  - **RETURNS**: `-`
+  - The script must treat `DISPOSE_DATA` as an opaque driver-specific value and must be idempotent. If the export has no temporary resources or `DISPOSE_DATA` is empty, it must succeed without performing any action.
+
+To enable cloning to and from Image Datastores that use a different driver, set `CROSS_DS_CLONE="YES"` in the driver's `DS_MAD_CONF` entry. A driver with this capability must:
+
+- Import the sources produced by the other compatible drivers through its `cp` action.
+- Produce a stable source through `export`.
+- Implement `dispose_export`, using a no-op script when `export` does not allocate temporary resources.
+
+Both the source and destination drivers must enable `CROSS_DS_CLONE`. Clones between Datastores that use the same driver continue to invoke the regular `clone` action.
 
 {{< alert title="Note" type="info" >}}
 `image_source` has to be dynamically generated by the `cp` and `mkfs` script. It will be passed later on to the transfer manager, so it should provide all the information the transfer manager needs to locate the image.{{< /alert >}} 
@@ -835,13 +844,25 @@ There are additional minor helper functions, please read the `scripts_common.sh`
 ## Export XML
 
 <a id="sd-export"></a>
+
+The `IMPORT_INFO` response contains the following fields:
+
+- `IMPORT_SOURCE`: Required. A path or URI that identifies the exported Image and can be consumed by `downloader.sh`.
+- `FORMAT`: Required. The Image format, for example `qcow2`, `raw`, `vmdk`, or `unknown`.
+- `SIZE`: Required. The Image size in MB.
+- `MD5`: Optional MD5 checksum.
+- `SHA1`: Optional SHA-1 checksum.
+- `DISPOSE_DATA`: Optional opaque data required by the same driver's `dispose_export` action.
+
 ```xml
 <IMPORT_INFO>
-   <IMPORT_SOURCE><![CDATA[<src>]]></IMPORT_SOURCE>
-   <MD5><![CDATA[<md5sum>]]></MD5>
-   <SIZE><![CDATA[<size>]]></SIZE>
-   <FORMAT><![CDATA[<format>]></FORMAT>
-   <DISPOSE><dispose></DISPOSE>
-   <DISPOSE_CMD><<![CDATA[<dispose command>]]>/DISPOSE_CMD>
+    <IMPORT_SOURCE><![CDATA[<source>]]></IMPORT_SOURCE>
+    <FORMAT><![CDATA[<format>]]></FORMAT>
+    <SIZE><![CDATA[<size>]]></SIZE>
+    <MD5><![CDATA[<md5sum>]]></MD5>
+    <SHA1><![CDATA[<sha1sum>]]></SHA1>
+    <DISPOSE_DATA><![CDATA[<driver-specific data>]]></DISPOSE_DATA>
 </IMPORT_INFO>
 ```
+
+The `MD5`, `SHA1`, and `DISPOSE_DATA` elements can be omitted when they are not needed. The legacy `DISPOSE` and `DISPOSE_CMD` elements remain available for existing Marketplace integrations; new Datastore drivers should use `DISPOSE_DATA` and `dispose_export` instead.

content/product/virtual_machines_operation/virtual_machines/images.md

@@ -344,12 +344,14 @@ Existing Images can be cloned to a new one. This is useful to make a backup of a
 $ oneimage clone Ubuntu new_image
 ```
 
-You can optionally clone the Image to a different Datastore. The new Datastore **must use the same DS_MAD driver**.
+You can optionally clone the Image to a different Datastore:
 
 ```default
 $ oneimage clone Ubuntu new_image --datastore new_img_ds
 ```
 
+The source and destination Image Datastores can use different storage drivers. All Image Datastore drivers in the [storage portfolio]({{% relref "/product/cluster_configuration/storage_system/overview/#storage-portfolio" %}}), except VirtioFS, support cross-driver Image cloning.
+
 ### Sharing Images with other Users
 
 Users can share their Images with other users in their group or with all the users in OpenNebula. Full details are described in the [Managing Permissions guide]({{% relref "../../cloud_system_administration/multitenancy/chmod#chmod" %}}). Here below you can see a quick example: to share the Image 0 with users in your group grant the **USE** right bit for **GROUP**: