diff --git a/content/product/integration_references/infrastructure_drivers_development/devel-market.md b/content/product/integration_references/infrastructure_drivers_development/devel-market.md index 4ab63001..26484321 100644 --- a/content/product/integration_references/infrastructure_drivers_development/devel-market.md +++ b/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 `/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 `/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 `/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_SOURCE - $MD5_SUM - $SIZE $FORMAT - NO -" + $SIZE + $MD5_SUM + $DRIVER_SPECIFIC_DATA + ``` +`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. + `/import`: The job of the export is to grab the `IMPORT_SOURCE` and dump it to the backend. diff --git a/content/product/integration_references/infrastructure_drivers_development/sd.md b/content/product/integration_references/infrastructure_drivers_development/sd.md index 1f94fd43..f1d840a3 100644 --- a/content/product/integration_references/infrastructure_drivers_development/sd.md +++ b/content/product/integration_references/infrastructure_drivers_development/sd.md @@ -80,16 +80,25 @@ Located under `/var/lib/one/remotes/datastore/` - `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 :[,:]\*. -- **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: - > - ``: The SOURCE of the image (path to the image in the datastore) - > - ``: The MD5 of the image - > - ``: The format of the image, e.g.: `qcow2`, `raw`, `vmdk`, `unknown`… - > - ``: 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 + +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 - ]]> - ]]> - ]]> - ]> - - <]]>/DISPOSE_CMD> + ]]> + ]]> + ]]> + ]]> + ]]> + ]]> ``` + +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. diff --git a/content/product/virtual_machines_operation/virtual_machines/images.md b/content/product/virtual_machines_operation/virtual_machines/images.md index 744be181..d341beae 100644 --- a/content/product/virtual_machines_operation/virtual_machines/images.md +++ b/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**: