F OpenNebula/one#6053: documentation for in-place restore.

Includes documentation for:

- XML-RPC api call one.vm.restore.
- in-place backup operation
- ls operation for datastore driver
- restore operation for tm driver
- what's new entry

source/integration_and_development/infrastructure_drivers_development/sd.rst

@@ -127,6 +127,27 @@ The backup datastore drivers are responsible to store the generate ``backup`` fo
    -  **ARGUMENTS**: ``datastore_action_dump image_id``
    -  **RETURNS**: ``Template_ID Image_ID1 Image_ID2 ...``
 
+- **ls**: Lists the disk backups included in a given backup together with a downloader URL. The action receives the increment ID as a parameter and the information of the backup image, datastore and VM as XML through standard input.
+
+  - **ARGUMENTS**: ``-i <increment_id>`` to select a specific increment to restore use -1 for last increment or full backups.
+  - **STDIN**: An XML document with the VM, backup Image and Datastore object information, in the form:
+
+.. code::
+
+        <DS_DRIVER_ACTION_DATA>
+          <VM>...</VM>
+          <DATASTORE>...</DATASTORE>
+          <IMAGE>...</IMAGE>
+        </DS_DRIVER_ACTION_DATA>
+
+- **RETURNS**: A JSON document that includes for each disk a downloader URL. This URL is then used by the restore scripts to get the VM disk backups:
+
+.. code::
+
+    {
+      "0": "rsync://102//0:0e6658/var/lib/one/datastores/102/21/0e6658/disk.0.0"
+    }
+
 The following actions needs also to be implemented (see above):
 
 - **monitor**: Returns the storage space of the backup system.
@@ -328,6 +349,16 @@ Action scripts needed when the TM is used for the system datastore:
    -  ``vm_id`` is the id of the VM
    -  ``ds_id`` is the target datastore (the system datastore)
 
+- **restore**: Restores VM disks from a backup. This script will access the ``ls`` operation of the associated datastore to get a list of VM disks and their downloader pseudo-URLs. The downloader script is then used to get the disk images from the backup and replace the VM disks. The VM is in poweroff state.
+
+   -  **ARGUMENTS**: ``host:remote_system_ds vm_id img_id inc_id disk_id``
+   -  ``remote_system_ds_dir`` is the path for the VM directory in the system datastore in the host
+   -  ``host`` is the target host where the VM is running
+   -  ``vm_id`` is the id of the VM
+   -  ``img_id`` is the id of the image backup to restore
+   -  ``inc_id`` ID of the increment to use, -1 will select the last increment or for full backups
+   -  ``disk_id`` is the id of the disk to restore, -1 will restore all available disks
+
 .. note:: If the TM is only for regular images you only need to implement the first group.
 
 .. _ds_monitor:

source/integration_and_development/system_interfaces/api.rst

@@ -214,6 +214,8 @@ onevm
 +----------------------+---------------------------+-------------------+
 | pci-detach           | one.vm.detachpci          | VM:MANAGE         |
 +----------------------+---------------------------+-------------------+
+| restore              | one.vm.restore            | VM:MANAGE         |
++----------------------+---------------------------+-------------------+
 
 .. note::
 
@@ -2430,6 +2432,30 @@ one.vm.detachpci
 | OUT  | Int        | Error code.                                 |
 +------+------------+---------------------------------------------+
 
+one.vm.restore
+--------------------------------------------------------------------------------
+
+-  **Description**: Restore VM disks (selectively) from a backup. The VM needs to be in POWEROFF state.
+-  **Parameters**
+
++------+------------+-----------------------------------------------------------------------------------+
+| Type | Data Type  |                                 Description                                       |
++======+============+===================================================================================+
+| IN   | Int        | The VM ID.                                                                        |
++------+------------+-----------------------------------------------------------------------------------+
+| IN   | Int        | The Image ID of the backup to use                                                 |
++------+------------+-----------------------------------------------------------------------------------+
+| IN   | Int        | Sets the increment to restore. Use -1 for the last increment or with full backups |
++------+------------+-----------------------------------------------------------------------------------+
+| IN   | Int        | The disk ID to restore. Use -1 to restore all disks available in the backup.      |
++------+------------+-----------------------------------------------------------------------------------+
+| OUT  | Boolean    | true or false whenever is successful or not                                       |
++------+------------+-----------------------------------------------------------------------------------+
+| OUT  | Int/String | The VM ID / The error string.                                                     |
++------+------------+-----------------------------------------------------------------------------------+
+| OUT  | Int        | Error code.                                                                       |
++------+------------+-----------------------------------------------------------------------------------+
+
 one.vmpool.info
 --------------------------------------------------------------------------------
 

source/intro_release_notes/release_notes/whats_new.rst

@@ -17,6 +17,7 @@ OpenNebula Core
 
 Storage & Backups
 ================================================================================
+- **In-place restore**: Users now have access to a streamlined operation for restoring VM disk backups directly onto existing VMs, eliminating the need of generating new images and VM templates. For further information, please refer to the :ref:`backup documentation <vm_backups_restore>`.
 
 FireEdge Sunstone
 ================================================================================

source/management_and_operations/backups/operations.rst

@@ -276,11 +276,87 @@ If the backup operation is not running, but the VM stays in the backup state, us
 Restoring Backups
 ================================================================================
 
-When you restore a VM backup OpenNebula will create:
+There are two main methods for restoring VM backups:
+
+- In-place restore: This involves replacing the disks of the VM with a backup copy.
+- Full restore: This process creates new disk images and templates. Unlike in-place restore, this operation doesn't require the VM to exist beforehand.
+
+In-place Restore
+--------------------------------------------------------------------------------
+
+In this mode, the disks of an existing VM are replaced with a copy from a backup. This operation requires that the VM is in a powered-off state. During the restoration process, you have the option to restore all disks or only the selected one.
+
+For example, let's consider a scenario with VM 83 in a powered-off state and an image backup (176) of this VM with three increments. It's important to note that the VM remains powered off during this process.
+
+.. prompt:: bash $ auto
+
+    $ oneimage show 176
+    IMAGE 176 INFORMATION
+    ID             : 176
+
+    ...
+
+    BACKUP INFORMATION
+    VM             : 83
+    TYPE           : INCREMENTAL
+
+    BACKUP INCREMENTS
+     ID PID T SIZE                DATE SOURCE
+      0  -1 F 173M      05/06 08:46:08 5f33de
+      1   0 I 1M        05/06 08:52:05 a0c4eb
+      2   1 I 1M        05/06 08:52:46 046843
+
+and the corresponding VM.
+
+.. prompt:: bash $ auto
+
+    $ onevm show 83
+    VIRTUAL MACHINE 83 INFORMATION
+    ID                  : 83
+    NAME                : alpine-83
+
+    ...
+
+    VM DISKS
+     ID DATASTORE  TARGET IMAGE                               SIZE      TYPE SAVE
+      0 default    vda    alpine                              173M/256M file   NO
+      1 -          hda    CONTEXT                             1M/-      -       -
+
+    ...
+
+    BACKUP CONFIGURATION
+    BACKUP_VOLATILE="NO"
+    FS_FREEZE="NONE"
+    INCREMENTAL_BACKUP_ID="176"
+    INCREMENT_MODE="CBT"
+    KEEP_LAST="4"
+    LAST_INCREMENT_ID="2"
+    MODE="INCREMENT"
+
+    VM BACKUPS
+    IMAGE IDS: 176
+
+    ...
+
+To restore all disks of the VM from the second increment (ID 1), simply execute:
+
+.. prompt:: bash $ auto
+
+    $ onevm restore --increment 1 83 176
+
+Note that all snapshots of the VM will be deleted upon restoring the backup.
+
+
+Full Restore
+--------------------------------------------------------------------------------
+
+When you perform a full restore a VM backup OpenNebula will create:
 
 - A Virtual Machine Template, with an equivalent definition to that of the VM when the backup was taken (i.e. NICs, capacity...)
 - A disk image for each of the disks stored in the backup.
 
+Note that in this case the VM does not have to exists. This operation is not tied to the original VM where the backup was made.
+
 When you restore the backup you may choose to:
 
 - Not keep the NIC addressing (i.e. IPs, or MAC)