Hyper-V R2 Import/Export – Part 2 - The New Import/Export APIs

SoumyaDB — Thu, 21 May 2009 19:51:00 GMT

To enable the new functionality of Import/Export we now have new ‘Ex’ versions of the Import/Export APIs along with settings data objects that allow the user to tweak the necessary parameters upon export or import:

Export:

Before you run an export, you can get the export parameters associated with a VM in the form of a settings data object. They are populated with default values. You can modify the parameters you need and then call ExportVirtualSystemEx with the modified object passed in.

ExportVirtualSystemEx: http://msdn.microsoft.com/en-us/library/dd379583(VS.85).aspx

Export Setting data: http://msdn.microsoft.com/en-us/library/dd379576(VS.85).aspx

Import:

Before you run an import, you can get the import parameters for the directory the VM will be imported from. Here, you can tweak interesting parameters like the AzMan security scope, network connections and even paths to VHDs before calling ImportVirtualSystemEx with the modified parameters.

ImportVirtualSystemEx: http://msdn.microsoft.com/en-us/library/dd379583(VS.85).aspx

Import Setting data: http://msdn.microsoft.com/en-us/library/dd379577(VS.85).aspx

While I will not repeat the information in the MSDN documentation, there are some salient points about the API worth calling out:

Export Settings data (Msvm_VirtualSystemExportSettingData):

Here is a dump of the parameters from powershell:

Caption                    : Virtual System Export Setting Data

CopySnapshotConfiguration  : 0

CopyVmRuntimeInformation   : True

CopyVmStorage              : True

CreateVmExportSubdirectory : False

Description                : Microsoft Virtual System Export Setting Data

ElementName                : Microsoft Virtual System Export Setting Data

InstanceID                 : Microsoft:4919C848-AA71-43B3-A1A5-988242D39FA2

SnapshotVirtualSystem      :

CopyVmRuntimeInformation: you can specify if you want to export your saved state files or not. This is particularly useful if you are interested only in the storage associated with VM or if you are moving a VM across processor vendors, the saved state files will be useless as a result and you could live without the 1 or 2 GB worth of memory data on the pipe.
CopyVmStorage is the essential parameter that controls config-only export. That is the parameter you want to set to false if you want to do config-only export.
CopySnapshotConfiguration and SnapshotVirtualSystem can be used together to export a single snapshot

Import Settings data (Msvm_VirtualSystemImportSettingData):

Here is the dump of the parameters from powershell:

Caption                  : Virtual System Import Setting Data

CreateCopy               : True

CurrentResourcePaths     : {C:\7088\blog.vhd}

Description              : Microsoft Virtual System Import Setting Data

ElementName              : Microsoft Virtual System Import Setting Data

GenerateNewId            : True

InstanceID               : Microsoft:ADDB3F5B-17BF-4AB4-A21F-BF1EE41B0165

Name                     : blog

SecurityScope            :

SourceNetworkConnections :

SourceResourcePaths      : {C:\blog_VM\runtime\Virtual Hard Disks\blog.vhd}

SourceSnapshotDataRoot   :

SourceVhdDataRoot        :

SourceVmDataRoot         :

TargetNetworkConnections :

TargetResourcePaths      :

TargetSnapshotDataRoot   :

TargetVhdDataRoot        :

TargetVmDataRoot         :

Source vs. Target:

Over here, you can clearly see a larger number of parameters. In particular, there are a number of “Source…” prefixed and “Target...” prefixed parameters. Since we now do a copy on import, you could view the “Source…” prefixed parameters as specifying the “from” location of the copy and the “Target…” prefixed parameters as the “to” location of the copy. The SourceResourcePaths parameter is an array populated with the VHDs associated with the VM. Here the user can specify the locations of the VHDs to copy from. They do not necessarily need to be under the import folder. Correspondingly, the TargetResourcePaths parameter is an array with paths that specify where the VHDs are to be copied to.

However, if you do not want to do a copy on import, (ie: you set the CreateCopy parameter to false), you do not need to specify any of the “Target…” prefixed parameters. Hyper-V will use the “Source…” prefixed parameters to configure the VM upon import.

Dataroots vs. ResourcePaths

On another dimension, you have the dataroots (SourceSnapshotDataRoot, SourceVhdDataRoot, SourceVmDataRoot) and the resourcepaths (SourceResourcePaths and TargetResourcePaths). Say, if all your VHDs reside in a single directory that you want to import from, specifying the SourceVhdDataRoot will be sufficient. Also, if upon import you want all the VHDs to reside in a single folder, just specify the TargetVhdDataRoot and you are done. You do not need to specify each of the TargetResourcePaths. The same logic applies to the (Source/Target)SnapshotDataRoot and (Source/Target)VmDataRoot.

Hyper-V R2 Import/Export – Part 1 – The Case for New Import/Export Functionality

SoumyaDB — Wed, 20 May 2009 07:13:00 GMT

This is the first blog entry of a multi-part series of blogs that addresses Import/Export in Windows Server 2008 R2. This blog talks about the scenarios enabled by the changes made to import/export in R2.

Ben Armstrong had blogged earlier about the intricacies of Import and Export with v1 Hyper-V in his blog posts:
http://blogs.msdn.com/virtual_pc_guy/archive/2008/08/26/hyper-v-export-import-part-1.aspx
http://blogs.msdn.com/virtual_pc_guy/archive/2008/08/27/hyper-v-export-import-part-2.aspx

Now, the big problem with how import export worked in v1 was that it just did not give the user enough control over the process of exporting and more significantly, importing a VM. Additionally, it was rather unforgiving. I bet many a user has been burnt trying to import a VM a second time only to find out that since he/she had imported it once already, the import folder could not be used anymore.

So, introducing the R2 version of Import Export: a lot more fine grained control on the entire process as well as added capabilities that are more in tune with user needs. Here is a list of capabilities enabled with the new Import Export functionality:

Copy on Import: The R2 Import/Export APIs now allow the user to specify a location to import to and not use the import directory as the VM's execution directory. Thus, the user can now create a "gold VM", export it once to a file share and then import it multiple times from that file share. This capability ends up enabling a number of scenarios as a result:
a. Backup-restore: For the users who do not want to use a backup application to backup their VMs, they can use import/Export and can restore the same files multiple times. Additionally, they can now have their backup media as read-only.
b. Moving/Cloning VMs: The users do not need to do a separate file copy operation in order to move a VM now. They just have to export to a file share and then import it. Additionally, at import time, the user can now specify where to place the VM on the target machine.
Export of a Snapshot: Picture this in the v1 days of Hyper-v: Tester Fred is running a number of tests using virtual machines. During the course of the tests, he takes snapshots at different points in time. Now, after snapshot #5 of 20, he sees a bug. So, he would like the developer to take a look at it. However, he would need to export the entire VM and all its snapshots in order to do that. In R2, he can export snapshot #5 as a separate and independent VM and send it to the developer to debug.
Additionally, this functionality has enabled another scenario in the IT arena: IT Admin John has a staging environment where he experiments with a number of versions of software in a VM to determine which works best for his scenario. Using R2 Hyper-V, he can create snapshots for each version of the software being tried out. When he determines a version that would work best in his deployment, all he has to do is to export that snapshot and then import it as an independent VM in the production machines.
Fine grained control: In R2, we have a much richer APIs for Export and Import, enabling the user to tweak parameters like VHD paths, network connections and AzMan during import. Additionally, these parameters can be modified regardless of how the export was carried out. In v1, if the users did a full export (ie: export with configuration as well as VHDs), there was little available to the user to tweak upon import. If they exported config only, they had to edit the config.xml file upon import. None of that in R2. All the parameters can now be tweaked via the import APIs. More on this in the following blog

Windows Virtualization Team Blog : import

Hyper-V R2 Import/Export – Part 2 - The New Import/Export APIs

Hyper-V R2 Import/Export – Part 1 – The Case for New Import/Export Functionality