Virtual Disk API Programming Guide - Documentation - VMware

Virtual Disk Programming Guide
Communicating With the Server
In a typical vSphere deployment with many ESXi hosts, an instance of vCenter Server manages the ESXi hosts,
and can move virtual machines from host to host (vMotion) to balance load and possibly save electricity by
powering off an ESXi host. VMware therefore recommends that backup applications communicate with the
vCenter Server instead of with individual ESXi hosts.
The vCenter Server provides location transparency for vSphere Web Services developers. The vCenter Server
tracks virtual machines as they move (through vMotion) from one ESXi host to another, and vCenter Server
directs SDK operations to the ESXi host that currently runs a virtual machine. Using the vSphere Web Services
API, it is possible to back up all the virtual disks associated with a virtual machine.
The handling of the vCenter or an individual ESXi host is essentially equivalent when using the vSphere SDK.
With vCenter management, there is no need to contact individual ESXi hosts directly. The remainder of this
chapter uses the term vSphere to indicate either a vCenter Server or an ESXi host.
To reduce the resources used by vSphere, VMware recommends that the number of connections (or Sessions)
be minimized. It is in the best interests of any program that communicates with vSphere to create one Session
and share it with all elements of the program that need to exchange information with vSphere. This means that
if your program supports multiple threads, your program should multiplex the use of connection objects by
use of access control locks (mutex and the like).
It is also important that all vSphere SDK operations proceed from one instance of the “Session” object that your
application requests after logging into vSphere. Using the vSphere API your application can create objects that
are “Session specific” and therefore would not be known to other portions of your application that might use
a different Session.
Information Containers as Managed Objects
VMware documentation introduces you to the concept of the managed object and its handle, called a managed
object reference (moRef). You might be tempted to get configuration and status information of managed
objects using a piecemeal approach. This has the severe disadvantage of creating a lot of chatter over the server
connection, so it is very slow. A mechanism has been created to provide status information efficiently: the
PropertyCollector, discussed in “PropertyCollector Data” on page 59.
More About Managed Objects
The documentation for the vSphere API and object model introduces a large number of managed objects.
There are five basic types of managed objects that describe the organization of a server. Other managed objects
can be considered as details expanding on these five basic types:
Folder
Datacenter
ComputeResource
ResourcePool
VirtualMachine
It is a characteristic of all managed objects that they have a moRef to the managed object that serves as the
parent to the managed object. This parent moRef allows you to reconstruct the object hierarchy exposed by the
vSphere SDK. In general the hierarchy is a tree‐like structure along the lines of:
Root Folder > Datacenter > ComputeResource > ResourcePool > VirtualMachine
There are variations on this theme, depending on whether you connect to vCenter or directly to an ESXi host,
but the overall organization is like the structure above. Each managed object also has a Name property.
The virtual machine that you want to back up, and the snapshot you take of it (the extensible managed object
VirtualMachineSnapshot) are both designated by their moRef.
58 VMware, Inc.