Creating Virtual Machines and Virtual Machine Templates

To create a virtual machine, you use the Folder.CreateVM_Task method. The method takes a VirtualMachineConfigSpec data object as input argument. VirtualMachineConfigSpec allows you to specify the attributes of the virtual machine you are creating.

If you need several identical virtual machines, you can convert an existing virtual machine to a template and create multiple copies (clones) from the template. You can also create multiple virtual machines by cloning an existing virtual machine directly.

Creating a Virtual Machine Using VirtualMachineConfigSpec

Use the Folder.CreateVM_Task method to create a virtual machine by specifying its attributes. You must specify either a host or a resource pool (or both). The virtual machine uses the CPU and memory resources from the host or resource pool.

Calling the CreateVM_Task Method

Create a virtual machine by calling the Folder.CreateVM_Task method with the following arguments:

■	_this —Folder where you want to place the virtual machine.

■	config— VirtualMachineConfigSpec data object that specifies CPU, memory, networking, and so on. See Specifying Virtual Machine Attributes with VirtualMachineConfigSpec)

■	pool— Resource pool for the virtual machine to draw resources from.

■	host— HostSystem managed object that represents the target host on which to run the virtual machine. If you invoke this method on a standalone host, omit this parameter. If the target host is part of a VMware DRS cluster, this parameter is optional; if no host is specified, the system selects one.

Important All objects must be located in the same datacenter.

Specifying Virtual Machine Attributes with VirtualMachineConfigSpec

The actual customization of the virtual machine happens through the properties of the VirtualMachineConfigSpec that is passed in as an argument to Folder.CreateVM_Task. For example, you can specify the name, boot options, number of CPUs, and memory for the virtual machine. All properties of VirtualMachineConfigSpec are optional to support incremental changes. See the API Reference.

The following example fragment from the VMCreate sample program illustrates how to define a VirtualMachineConfigSpec.

Example: Defining a VirtualMachineConfigSpec Data Object

VirtualMachineConfigSpec vmConfigSpec = new VirtualMachineConfigSpec();

...

vmConfigSpec.setName(“MyVM”);

vmConfigSpec.setMemoryMB(new Long(Integer.parseInt 500));

vmConfigSpec.setNumCPUs(Integer.parseInt 4);

vmConfigSpec.setGuestId(cb.get_option("guestosid"));

...

 

The VMware SDK SDK/samples/Axis/java/com/vmware/apputils/vim/VMUtils.java sample defines a more comprehensive virtual machine that also includes a Floppy, CD-ROM, disk, and virtual NIC. See Configuring a Virtual Machine for a discussion of commonly set properties.

When you create a virtual machine, the virtual machine files are added at the virtual machine’s storage location. See Virtual Machine Files.

Additional Configuration Information

The VirtualMachineConfigInfo and VirtualMachineConfigSpec objects provide the extraConfig property for additional configuration information. The extraConfig property is an array of key/value pairs that identify configuration options. The Server stores the extraConfig options in the .vmx file for the virtual machine. As the vSphere API evolves from version to version, an extraConfig option may become a standard configuration property that is part of the defined inventory data model. In this case, you must use the standard data model property for access; you cannot use the extraConfig property.

Creating Virtual Machine Templates

Templates allow you to create multiple virtual machines with the same characteristics, such as resources allocated to CPU and memory, or type of virtual hardware. A virtual machine template is a virtual machine that cannot be powered on and that is not associated with a resource pool.

You can convert any powered off virtual machine to a template by calling VirtualMachine.MarkAsTemplate. After the conversion, the original virtual machine no longer exists. You can use the template to create multiple clones of the same configuration.

Cloning a Virtual Machine

A clone is a copy of a virtual machine. The main difference between a virtual machine and a clone is that the VirtualMachine.config.template property is set to true.

You can create a clone in one of the following ways:

■	If you no longer need a specific instance of a virtual machine, but you want to use the virtual machine’s configuration as a template, use the VirtualMachine.MarkAsTemplate method. This method sets the config.template property to true, and disables the virtual machine.

■	If you want to use an existing virtual machine as a template, but keep the virtual machine, call the VirtualMachine.CloneVM_Task method to create a duplicate of the virtual machine.

If you use the VirtualMachine.CloneVM_Task method, you can customize certain attributes of the clone by specifying them in the VirtualMachineCloneSpec data object you pass in when you call the method.

The following code fragment from VMClone.java illustrates how you can customize a clone and specify a new location for it.

Example: Cloning a Virtual Machine

VirtualMachineCloneSpec cloneSpec = new VirtualMachineCloneSpec();

VirtualMachineRelocateSpec relocSpec = new VirtualMachineRelocateSpec();

cloneSpec.setLocation(relocSpec);

cloneSpec.setPowerOn(false);

cloneSpec.setTemplate(false);

String clonedName = cloneName;

 

ManagedObjectReference cloneTask

= service.cloneVM_Task(vmRef, vmFolderRef, clonedName, cloneSpec);

 

The VirtualMachine.CloneVM_Task method takes the source virtual machine, target folder, name, and VirtualMachineCloneSpec as arguments.

The VirtualMachineCloneSpec data object includes the location, power state, and whether the clone should be a template. The location, in turn, is a VirtualMachineRelocateSpec data object that specifies the target location (datastore, disk, and host or resource pool) and any transformation to be performed on the disk.

Converting a Template to a Virtual Machine

You can change a template back to an operational virtual machine.

■

To convert the template to a virtual machine, call the MarkAsVirtualMachine method on the template. You must specify a resource pool and, optionally, a host for the virtual machine. Host and resource pool must be under the same ComputeResource. When the operation completes, the template no longer exists.

■	To keep the template, clone the template by calling the CloneVM_Task method on the template. In the VirtualMachineCloneSpec (the spec parameter), set the template property to false.

Accessing Information About a Virtual Machine

After you have created a virtual machine, you can retrieve information about the virtual machine through the VirtualMachineConfigInfo properties. See the API Reference for a complete list.

Checking Default Files

After you have created a virtual machine, several files are generated and placed in the directory specified in the VirtualMachineConfigSpec.files property.

Virtual Machine Files 

File	Usage	File Description	File Format
.vmx	.vmname.vmx	Virtual machine configuration file.	ASCII
.vmxf	vmname.vmxf	Additional virtual machine configuration files, available, for example, with teamed virtual machines.	ASCII
.vmdk	vmname.vmdk	Virtual disk file.	ASCII
.flat.vmdk	vmname.flat.vmdk	Preallocated virtual disk in binary format.	Binary
.vswp	vmname.vswp	Swap file.
.nvram	vmname.nvram or nvram	Non-volatile RAM. Stores virtual machine BIOS information.
.vmss	vmname.vmss	Virtual machine suspend file.
.log	vmware.log	Virtual machine log file.	ASCII
#.log	vmware-#.log	Old virtual machine log files. # is a number starting with 1.	ASCII
.vmtx	vmname.vmtx	Virtual machine template file.	ASCII

If you are using snapshots, the following additional files might be available. See Snapshots.

Virtual Machine Snapshot Files 

File Extension	Usage	File Description
.vmsd	vmname.vmsd	Virtual machine snapshot file.
.vmsn	vmname.vmsn	Virtual machine snapshot data file.
**.delta.vmdk		Snapshot difference file. A number preceding the extension increases with more snapshots.
**.vmdk		Metadata about a snapshot.
-Snapshot#.vmsn		Snapshot of virtual machine memory. Snapshot size is equal to the size of you virtual machine’s maximum memory.

Checking Default Devices

When you create a virtual machine, you are also creating a set of default devices, based on the hardware version associated with your SDK. You can see these devices using the EnvironmentBrowser.QueryConfigOption method. For example, the IDE controllers are created by default. Many of these default devices contain properties that you cannot change.

However, you can add the following optional devices to the default set: VirtualSerialPort, VirtualParallelPort, VirtualFloppy, VirtualCdrom, VirtualUSB, VirtualEthernetCard, VirtualDisk, and VirtualSCSIPassthrough. See the VirtualDevice Data Object in the API Reference for more information about each of these optional devices.

Caution Do not try to change default device properties using the VirtualMachineConfigSpec.deviceChange method discussed in Adding Devices to Virtual Machines, because the deviceChange method is not applicable to default device properties.