Bug Reference

CLOUDSTACK-4757

Branch

Work is in progress in ova-multiple-disks branch

Introduction

OVA is an archive or an envelope specification that can contain a complete VM including multiple disks and other files such as ISOs. And CloudStack templates in case of VMware are in OVA format.

Today in CloudStack, we only support template creation based on OVA files that contain a single disk. If an Admin/User registers a template using OVA that contains more than 1 disk and launches an instance using this template, only the first disk is attached to the new instance and the rest of the disks are ignored. 

Purpose

Purpose of this document is to present functional specifications for improvements that are required to extent the current OVA support to include multiple disks.

Glossary

VM template – Represents a ROOT disk contained in an OVA along with other VM related information like Guest OS.

Datadisk Template - An abstraction for a DATA volume contained in an OVA

Goals

The current CloudStack behavior needs to be improved to support OVA files with multiple disks.

In case of an instance launched from a template that is an OVA containing more than 1 disk 

• First disk should be attached to the new instance as the ROOT disk
• Volumes should be created for the additional disks and attached to the instance as additional DATA disks

Scope

Scope of this proposal is limited to adding support for additional disks present in an OVA that is registered in CloudStack. It is not in the scope to fully support an OVA and hence CloudStack will ignore any other information that is encapsulated in the OVA which may include information about networks, multiple Virtual machines or ISO s present.

Feature specifications

Currently in CloudStack, template abstraction is that of a VM template that contains a single disk. To represent the additional disks present in an OVA we will introduce the concept of Datadisk templates.

Datadisk templates will be

• Used to create a data disk from the volume image that is present in the template
• Stored in vm_templates tables along with the current CS templates
• Used only when a user tries to deploy a VM from the corresponding VM template and never independently

Datadisk templates will provide flexibility to orchestrate, deploy and manage additional disks present in an OVA like any other Datadisk in CloudStack.

Architecture

Work flow changes

Template registration

• No change in user experience during template registration
• Once template is downloaded and installed in the secondary storage it will be post processed
  • OVA template custom property "cloud.ova.bootdisk" will be used to determine the ROOT disk. If it is not set the first disk will be identified as the ROOT disk
  • For each of the data disks
    • An OVF descriptor will be created 
    • Datadisk template will be created by packaging the disk and OVF into an OVA
    • Datadisk, OVF and OVA will be present in a separate folder inside the parent template folder. e.g. -
      • Say VM template id is 206, then the 1st data disk of a template will be present in folder  - template/tmpl/2/206/1 
      • Sample contents of the Datadisk template folder will be
        • MultipleVolumes.ova MultipleVolumes.ovf MultipleVolumes-disk1.vmdk
  • Template post processing will return information about each of the additional data disks present (if any).
  • Information about the data disks will include physical and virtual size of the data disk and path where the template has been installed
  • For each of the additional disks a Datadisk template will be created
    • Entries will be made in vm_templates and vm_template_store_ref table
    • Datadisk Template will be referenced to the corresponding VM template by with DB column parent_template_id where parent_template_id points to the VM template

Listing templates

• All template i.e. both VM templates and Datadisk templates will be listed.
• Datadisk template can be differentiated from VM templates by the property templatetype
  • Datadisk templates will have templatetype set to 'Datadisk'
  • VM templates will continue to have templatetype set to 'User'
• Following attributes will also be different for the two type of templates – bootable(set to false for Datadisk template), guestos(unset for Datadisk template)

Virtual Machine deployment

• If user tries to deploy a VM from a template containing multiple disks, user will have to choose a Datadisk offering for every Datadisk template chosen to be deployed along with the VM template
  • If the actual size of the disk exceeds the size of the disk offering then VM deployment will fail
• During VM create process, when CloudStack makes DB entry for the ROOT disk, DB entries will be made in volumes table for each of the Datadisk templates
• During VM orchestration while the storage is being prepared, a volume will be created in primary storage for each of the additional disks
  • Each of the volumes will be migrated from secondary storage to the primary storage chosen by the deployment planner
  • When VM starts it will be booted with all the chosen disks

Template deletion

• Deletion of individual Datadisk Templates will be allowed
• When a VM template is deleted, all the corresponding Datadisk templates will deleted

Template copy

• Copy template will not be supported on a individual Datadisk template
• When a VM template is copied to a zone, all the corresponding Datadisk templates will also be copied to the zone

Template update

• Users will be allowed to update Datadisk templates
  • Template attributes that can be updated - bootable, displayext, format, name, ostypeid, sortkey

Update template permissions

• Not supported for Datadisk Templates
• By default the Datadisk templates will be private and non-featured

Identifying ROOT disk in an OVA 

• During template post processing after download CloudStack will check the OVA template being registered if there exists multiple disks in the container.
  • Unless the OVA has custom property "cloud.ova.bootdisk" set, the first disk in the OVA container is registered as vm template and remaining disks would be registered as data disk templates. The value of parameter “cloud.ova.bootdisk” should be in format ”<controllertype><controllerId>:<devicenumber_on_this_controller>” to VM before exporting that as OVA. Possible values for <controllertype> are "ide" or "scsi". Possible values for <controllerId> are 0, 1, 2, 3. Possible values for <devicenumber_on_this_controller> are 0 to 15. Ex: “cloud.ova.bootdisk”=”scsi0:2”. Custom property can be added to VM before creating OVA from the VM per VMware documentation http://pubs.vmware.com/vsphere-50/topic/com.vmware.vsphere.vm_admin.doc_50/GUID-88C8B72F-5753-4A2A-94B5-40EA1046C4D9.html

Change in the existing behavior

• When a user downloads a CS template with multiple volumes, the entity that is downloaded will not be same as the one that was registered
  • The downloaded template will only contain the ROOT disk because when a OVA template is registered it is now consumed and split into 2 or more templates (VM Template and Datadisk Template(s))

Web Service API

DeployVirtualMachine API

New parameter – datadisktemplatetodiskofferinglist

• Mapping from Datadisk Template to Datadisk Offering
• If a VM is being deployed from an OVA template that contains additional disks, then during the deployment user will have to choose a Datadisk offering for every Datadisk template he/she chooses to deploy along with the VM template
• Mutually exclusive with the existing parameter diskofferingid
• Optional
• Usage - &disktemplatetodiskofferinglist[0].disktemplateid=2&disktemplatetodiskofferinglist[0].diskofferingid=3

UI Flow

Deploy VM wizard

• While listing all templates list only VM templates i.e. non Datadisk templates (VM templates will have bootable property set to true)
• Once the user has selected the VM template allow user to pick between disk offering or Datadisk template with the help of radio buttons (user can choose to select neither)
• If user chooses disk offering then rest of the work flow will remain the same as today
• If user chooses Datadisk template then list all the Datadisk templates that belong to the VM template chosen in the first step (templates that have parentTemplateId parameter set to that of VM template)

DB Schema changes

• Add new column parent_template_id to vm_templates table

  • default value is null

  • for Datadisk templates, value will be Id of the VM template that the Datadisk template belongs to

  • for VM templates, value will always be null

Upgrade scenario

• In a setup that has been upgraded to 4.4, templates with multiple volumes
  • That were registered prior to upgrade will continue to operate as before. Any VM launched from these templates will only have the ROOT disk
  • That will be registered after upgrade will follow the new behavior. Any VM launched from these templates will have additional data disks attached to them along with the ROOT disk (i.e. if user chooses to)

Limitations

• CloudStack templates and uploaded volumes in case of VMware are in OVA format. For 4.4 release, we will be adding multiple disk OVA support only for CloudStack templates and not uploaded volumes.
• In 4.4, users will not be allowed to perform any independent operations on the Datadisk templates
  • User cannot use the Datadisk template to add a data disk volume after VM is created based on the template
  • Following operations will not be supported on the Datadisk templates - updateTemplatePermissions, extractTemplate, prepareTemplate (Future work)
• While deploying a Virtual Machine, user will not be able to provide custom disk offerings for datadisk templates
  • disktemplatetodiskofferinglist can only have disk offerings that are non-custom