Introduction

Currently in Apache CloudStack, a user can only deploy a VM from templates or ISOs but not directly from VM snapshots. To deploy a VM off another VM at a given point in time, today a CloudStack user needs to take a snapshot of the original VM’s volume at that point in time, create a template from the snapshot backup of the volume and then deploy a VM from the template. This work flow is tedious and time consuming as it involves multiple data transfers over network,

1. From primary storage to secondary storage to export snapshot as template over to secondary storage.
2. From secondary storage to primary storage to download the template to seed the template for further instance deployment over that primary storage.

This document describes a feature that will be introduced to ease the above process by providing users with the ability to deploy VMs directly from VM snapshots residing on the primary storage.

Purpose

This is the functional specification for feature ‘Deploy VM from VM Snapshot’.

References

JIRA Ticket

Unable to render Jira issues macro, execution error.

Branch

master

Document History

Glossary

• Snapshot - VM snapshot
  
• Original VM - The user instance whose snapshot is being used to deploy a new user instance

Feature specifications

1. Deployment of user instance from snapshot will be quicker than earlier work flow which includes exporting snapshot to secondary storage as template and importing template from secondary storage to deploy user instance in primary storage.
2. Support deployment of user instance from snapshot of existing user instance over VMware hypervisor
   
   1. Deployed instance must have the root volume identical (content-wise) to the root volume from snapshot.
   2. Deployed instance should be added to guest networks specified by the list of network offerings specified while deploying user instance
   3. Deployed instance must have the configuration as per the service/compute offering specified while deploying user instance
   4. Root volume of deployed instance must use the same primary storage pool as that of the counter-part in original VM.
   5. There is no restriction on the configuration of original VM, the user instance whose snapshot is used to deploy a user instance. For example orginal VM may have zero or more data volumes OR may be part of zero or more guest networks. Also it is possible for a user instance and its snapshot to span across one or more primary storage pools if user instance has more than 1 volume and the volumes spread across primary storage pools.
3. Snapshots of a user instance forms a hierarchy and users should be allowed to deploy user instance from any snapshot in that hierarchy.
4. Provide means to seed template in same primary storage pool from snapshot
5. Provide means to create volume from VM snapshot on same primary storage, from specified volume in original VM of the snapshot
6. While deploying a user instance from snapshot,
   1. Users will not be allowed to specify a zone, as current zone is assumed.
   2. Users will not be allowed to specify a template, as the snapshot image would be used as source instead of template.
   3. Users will be allowed to specify a host, provided the host has access to primary storage pool where the original VM resides.
   4. Users will be allowed to choose compute offering for customized compute configurations and guest networks
   5. CloudStack should ignore memory dump, if any, which is associated with the specified snapshot
7. Post deployment, life cycle and behavior of a VM deployed from a snapshot will be the same as any other VM in the CloudStack cloud.
8. Deployed user instance inherits following properties of original VM
   1. disk_offering_id
   2. vm_template_id
   3. service_offering_id (unless a compute offering was specified by user while deploying this user instance)
9. All volumes of new user instance inherits disk_offering_id of respective volumes of original VM, except for volumes of type ROOT which is attached to original VM which was deployed from template. In case of such volumes disk_offering_id would be the compute offering chosen by user, if any, while deploying the user instance otherwise disk_offering_id of ROOT volume of original VM
10. Root volume of new user instance inherits template_id (if original VM was deployed from a template) or iso_id (if original VM was deployed from ISO) property from original VM. This establishes the point of restore in future.
11. What is not supported?
    1. Deploying multiple instances simultaneously from the snapshot
    2. Supporting storage migration of user instance while deploy VM from snapshot of that user instance is in progress
    3. Deploy instance from snapshot in primary storage other than where the snapshot is present
    4. Deploy instance along with all volumes from the snapshot.
    5. Data volumes will not be considered while creating/seeding template from snapshot
    6. Creating/seeding template from snapshot is not supported for primary storage pools other than primary storage pool of the snapshot.

Test guidelines

• User instance deployed from a snapshot should have root disk identical (content-wise) to that in original VM
• If the primary storage pool already has template seeded from snapshot using 'prepareTemplate' API, then time to deploy instance from that snapshot would be consistent. That means 1st deployment of user instance would be same as that of 2nd, 3rd,... nth deployment.
• Ability to choose guest networks while deploying user instance for snapshot
• Ability to choose compute offering while deploying user instance for snapshot

Error handling

• In case VM deployment from VM snapshot fails at any stage during the deployment,
  • The VM should be moved to ‘ERROR’ state
  • UI and management server logs should clearly indicate the reason for the failure
  • Cleanup process of the VM and all its resources should be identical to the cleanup of any VM in ‘ERROR’ state.

Audit Events

• Events will be generated in the management server logs for any resource (for e.g. VM, volume, NIC) being created during the course of the deployment.

• vCenter tasks involved during a VM deployment – Clone virtual machine, Reconfigure virtual machine, Power On virtual machine etc.

Target users

• CloudStack Users and Admins.

Use case

1. Allow user to quickly deploy user instance directly from snapshot

Design description

1. Existing workflow for user instance deployment, deployment planning and resource allocation will be leveraged while deploying instance from snapshot.
2. Instance creation (resource creation in Apache CloudStack DB)
   1. Additional validations will be made if a VM is being deployed from a snapshot.
      1. Apache CloudStack will check if the compute offering specified by the user is valid. For e.g. Apache CloudStack will validate if the number of CPUs mentioned in the compute offering matches the number of virtual CPUs present in the original VM.
      2. These validations will be done by comparing various configurations of the original VM with the properties in the user specified compute offering.
      3. GetVmSnapshotConfigs - A new agent command will be introduced to retrieve configuration details of the original VM at the time the snapshot was taken from the hypervisor.
   2. Below volume operations continue to be blocked on VMs that have VM snapshots associated with them -
      

      1. Attach volume

      2. Detach volume

      3. Resize volume

   3. Choosing service/compute offering is mandatory while deploying user instance from snapshot.
3. Instance start (resource creation on hypervisor)
4. 1. Instance will be created on the hypervisor by cloning the original VM and the clone will be based off the snapshot point.
   2. There are two ways in which this can be achieved
      Option 1
      1. When the first instance is being deployed from a snapshot, the snapshot will be full cloned into the primary storage that contains the snapshot. Then the instance will be created by link cloning from this copy. Every instance that is deployed after the first deployment will simply be link cloned from the full clone copy.
      2. This workflow is similar to the existing work flow of instance deployment from a template. In case of instance deployment from template, the base template is created and stored in primary storage. And every instance would be deployed by full or fast clone (based on global configuration setting 'vmware.create.full.clone') of the template copy in primary storage.
      3. This will ensure that VM deployments are quick and that the snapshot chain doesn't grow too long causing any inconsistencies or low performance.
      Option 2
      1. Every time a VM is deployed from a VM snapshot a linked clones will created directly from the VM snapshot. 
      2. Though this will ensure quick VM deployments, it is error prone as the disk chain could grow too long and potentially lead to corruption of several VMs upon failures. 
   3. Specifications for the cloning operation
      1. CloudStack will specify the exact host and datastore(s) to the clone the VM into. This will be based on the host and storage(s) chosen by the deployment planner.
      2. CloudStack will specify the NICs to be added and removed. This is based on the network(s) chosen by the user to deploy the VM in. This is needed because by default when a VM is cloned, all the NICS on the original VM are created on the new VM.
5. After user instance is deployed from snapshot, there would not be any relation between instance and the snapshot used to create the instance
6. If primary storage runs out of space, the instance deployment would be failed.
7. Modify createVolume API implementation to support VM snapshot as source in addition to the 2 currently supported sources disk offering and volume snapshot. Volume would be created on same primary storage as that of the volume specified in VM snapshot.
8. Modify prepareTemplate API implementation to support seeding template from VM snapshot.

Limitations

• VM can only be deployed on the host that can access the primary storage pool that contains the VM snapshot (VM snapshot will reside with the original VM). If there is not enough capacity i.e. if no host that can access this storage pool has sufficient resources (memory, CPU etc.) then Apache CloudStack will fail the deployment.
• Existing Apache CloudStack limitation will continue, below volume operations will continue to be blocked on VMs that have VM snapshots associated with them. Please refer the design section for more details.

  • Attach volume

  • Detach volume

  • Resize volume

API Changes

1. Existing API deployVirtualMachine will be updated
   1. Adding 1 new optional parameter – vmsnapshotid
      1. vmsnapshotid - UUID of the VM snapshot that the VM has to be deployed from.
      2. This parameter would be mutually exclusive with the existing parameter ‘templateid’
      3. Usage - &vmsnapshotid=<vmsnapshot-uuid>
   2. Modifying the existing parameter templateid from required to optional
      
      
2. prepareTemplate– Existing API will be updated
1. Adding 1 new optional parameter – vmsnapshotid
   1. vmsnapshotid - UUID of the VM snapshot from which the template would be created from.
   2. This parameter would be mutually exclusive with the existing parameter ‘templateid’
   3. Usage - &vmsnapshotid=<vmsnapshot-uuid>
2. Modifying the existing parameter templateid from required to optional
   
   
3. createVolume -  Existing API will be updated
1. Adding 2 new optional parameters – vmsnapshotid, volumeId.
1. vmsnapshotid
1. UUID of the VM snapshot from which the volume should be extracted and created from.
2. This parameter would be used along with volumeId parameter.
3. This parameter would be mutually exclusive with diskofferingid, snapshotid
4. Usage - &vmsnapshotid=<vmsnapshot-uuid>
2. volumeId
1. UUID of the volume from which (content of) new volume would be created so that content of volume would be identical to that of the volume from snapshot specified by vmsnapshotid.
2. This parameter would be used along with vmsnapshotid parameter
3. Usage - &volumeId=<volume-uuid>
2. Size of new volume would be same as that of the volume specified by <volumeid>

DB Changes

vmsnapshot_spool_ref (id, pool_id, vm_snapshot_id, created, install_path, state) -  This table will contain the mapping between a VM snapshot and the primary storage it is on.

Hypervisors supported

VMware ESXi 5.0 and above.

UI Flow

• Add a new option ‘Deploy VM from VM snapshot’ to the existing operations supported on VM snapshots.
  • Include it under, Instances --> Details --> View Snapshots --> VM Snapshot
  • When a user selects this option, the existing VM deployment workflow should be provided to the user. The same VM deployment widget without the first screen where a user needs to provides the zone and template.

Upgrade

• Deployment of VM from VM snapshots will be available with a fresh deployment as well as an upgraded deployment.
• In an upgraded deployment, VM deployment will be supported for VM snapshots created both before and after upgrade.

Open Items/Questions

1. NA