Introduction

This feature adds the ability to create a new instance from a VM backup for dummy, NAS and Veeam backup providers. It works even if the original instance used to create the backup was expunged or unmanaged. There are two parts to this functionality:

1. Saving all configuration details that the VM had at the time of taking the backup. And using them to create an instance from backup.
2. Enabling a user to expunge/unmanage an instance that has backups.

Currently, it is not possible to expunge a VM with backups because the backup offering cannot be removed while backups exist. This feature addresses that gap.

The process flow is as follows:

1. A user selects a backup and clicks the "Create Instance from Backup" button.
2. The user can choose to create the instance straightaway (all configuration details are fetched from the backup metadata) or they can choose to configure some details details themselves with some restrictions.
3. A new instance is created with the intended configurations.
4. The instance is started to allocate volumes, then stopped for restore.
5. For NAS provider, backed-up data is copied to the new instance's volumes using existing restore functionality.
6. For Veeam, a command is sent to the Veeam server to restore the backup to the new instance location.
7. After restore, the instance is started and ready for use.

...

Part 1 : Creating Instance from Backup

Saving Instance Details / Properties

The following details are needed for creating the new Instance:

1. Hypervisor Type
2. Template ID or ISO ID
3. Service Offering UUID
4. UUIDs of the Networks to attach
5. IP and MAC Address configurations for each network
6. Disk Offering ID, Volume Sizes, Min IOPS, Max IOPS for all data volumes

• Hypervisor and Template/ISO are retrieved directly from the original instance
• Service Offering and Network details (including IP/MAC configurations stored in a comma separated format for each network) are stored in the backup_details table
• Volume information is already stored in the backed_volumes column in the backup table. It has details like Disk Offering UUID, size and type. It is enhanced to also store deviceId, minIOPS and maxIOPS. This information is stored for all the volumes.

The rest of the Instance properties are not stored and retrieved from backup. Users have to set them explicitly if needed.

Applying Configuration Details

• The UI form is pre-populated with backup metadata.

• Users may override configurations.

• Restrictions:

  • Number of data volumes must remain the same.
  • Data volume sizes must be >= backed-up sizes.

  These are already enforced in the UI, and will return an error if called directly from API.

• The option to reuse original IP and MAC is available only if the original VM is expunged and the addresses are still available in the network.

Some properties are not fetched from backup but still needs special handling.

• ISO : ISO is attached  while creating the instance and detached  before restore, so that the new instance doesn't boot with ISO, but still has the metadata that it was created using that ISO.
• SSHKeys : SSH key if given by the user is set after restore so that it doesn't get overwritten during restore.
• User data : User data is not re-applied when restoring from a backup.  Backups are expected to capture the full VM state after user data (cloud-init) has been applied. Therefore, user data is considered already baked into the disk image.

New API

A new api createVmFromBackup is added.

The CreateVmFromBackup API needs parameters similar to DeployVmCmd because it internally creates a new VM instance. However, some of these parameters, like serviceOfferingId and templateId, are mandatory in DeployVmCmd, but in the context of creating a VM from a backup, they can be derived from the backup metadata. To avoid modifying DeployVmCmd and breaking backward compatibility, a new abstract base class was introduced which consolidates common parameters used in both APIs.

• A new abstract class BaseVmDeployCmd based on DeployVmCmd is created.
• Both CreateVmFromBackupCmd and DeployVmCmd extend this new abstract class.
• CreateVmFromBackupCmd allows serviceOfferingId and templateId to be optional.
• backupId and preserveip are additional parameters introduced in CreateVmFromBackupCmd.

This abstraction ensures:

• Reusability of shared logic
• Cleaner parameter handling
• Backward compatibility for existing deployments

Multiple Data Volume Support

The existing DeployVmCmd only supports creating a single data volume during instance deployment. However, backups can contain multiple data volumes, and to restore such backups, the CreateVmFromBackup API needs to support the creation of multiple data volumes.

To enable this, a new parameter named dataDiskDetails has been added to BaseDeployVirtualMachineCmd. This enhancement allows both CreateVmFromBackupCmd and DeployVmCmd to support multiple data volumes.

• Each entry in dataDiskDetails contains:
  • Disk Offering ID
  • Volume Size
  • MinIOPS (optional)
  • MaxIOPS (optional)

The instance orchestration framework has been updated to support creating and attaching multiple data volumes as part of the VM creation process.

Although this functionality is technically available in DeployVmCmd, it has not been integrated into the UI.

UI Changes

• New button: "Create Instance from Backup" in backups list view.
• User can choose to directly create the VM or configure VM parameters before creating it.

...

Part 2 : Support for Expunging Instances that has Backups

Currently, backup offering can not be removed from an Instance which has backups. This has been changed so that backup offering can be removed and the VM can be expunged even with backups

• This is supported for Dummy, NAS and Veeam providers.
• VM can be reassigned a different backup offering.
• Operations supported on retained backups:
  • Create Instance from Backup
  • Restore Volume from Backup and Attach to VM
  • Delete backup

Framework Level Changes

• Volumes related information is retrieved from backup.backed_volumes instead of vm_instance.backup_volumes as vm_instance.backup_volumes is cleared when the backup offering is removed.
• Backup offering and provider are derived from the backup table, not from the vm_instance table.

Backup Usage Tracking

Backup usage tracking has undergone major changes to support the new flexibility around backup offerings.

• Previously, usage was tracked per VM.
• Now, usage is tracked per (VM, Backup Offering) pair. This reflects the fact that a VM can have backups across multiple offerings, potentially with different billing implications or tiers.

The backup and recovery infrastructure retrieves usage metrics (backup size, number of backups, retention) from all providers. These metrics were previously returned consolidated for all backups per VM.

All current backup providers — NAS, Dummy, Networker, and Veeam — have been updated to return usage metrics per (VMId, Backup Offering) tuple.

Usage is also tracked for backups of Expunged Instances. Pre-requisite for this is that the Database entry for the expunged VM is present. It is made sure that the db entry for expunged Instances with Backups are not auto-purged by the system itself. Users should make sure not to manually purge DB entries for such VMs.

Usage Tracking Lifecycle Changes

• Previously, removing a backup offering from a VM would also remove its the usage record associated with that offering.
• With this change, usage records are preserved even after a backup offering is removed, as long as any backups exist.
• Usage record for such offering is now removed only after the last backup associated with that offering is removed.

NAS Plugin Changes

• No structural changes needed.
• Retrieve information from backup instead of the VM.
• Metrics are now returned per (VM, BackupOffering) rather than per VM.

Veeam Plugin Changes

• Removing backup offering deletes the Veeam job but it does not delete any backups.
• Backups can be deleted separately from CloudStack.
• The backups remain in orphaned state in Veeam but usable.
• Old job’s backup schedules are also deleted on removing the offering, just the backups remain.
• New job is created if VM is assigned a new offering. Not affecting old backups.
• Veeam Provider and Client updated to return metrics per (VM, BackupOffering)

The design given below is obsolete, but the functionality is implemented.
Github PR has the latest details : https://github.com/apache/cloudstack/pull/10140/

--- Obsolete ---

Problem Statement

A. Ability to restore a backup to a new Instance.

Currently Backups are tightly coupled with Instances. Restore can only be done on the same instance from which the backup was taken. If the instance is deleted, backup is not usable and restoring the full backup or individual volumes lead to random exceptions.

This limitation is mostly because of how CloudStacks Backup and Recovery framework code is written. Backup providers usually don’t care if restore is being done to the same VM from which the backup was taken. So there is an opportunity to enhance the BnR framework so that user can create a new Instance and restore from a backup is done on that instance. This will also be useful in cases where the original instance is expunged or unmanaged but the backup is still present.

Support for Dummy, NAS and Veeam Backup Providers will be provided for this feature.

Design

Metadata

When restoring a backup to a new instance, or restoring an expunged instance, the user might want to reuse the state and configuration of the original VM. The metadata can be classified into two types

1. Instance metadata
   1. networks
   2. ip addresses
   3. compute offering
   4. host
   5. template
2. Volume metadata
   1. uuid
   2. size
   3. type
   4. path
   5. disk offering

Volume’s uuid, size, type and path are already stored in the backups table (backed_volumes : Backup.VolumeInfo). Remaining metadata can be added as well at the time of backup. And then during restore the fields can be auto-populated in the deploy VM form. The user can choose to use different settings or use the auto-populated ones.

API and Schema changes

New Apis

1. createInstanceFromBackup extends deployVMCmd :

   Parameters

   1. backupId

   Result: A new instance is created with the given config with all data volumes present in the backup.

Schema Changes

New columns in the backups table

...

• .

...

...