VMware vSphere Blog

By William Lam, Sr. Technical Marketing Engineer

• Introduction to the vSphere API Part 1: Overview

In Part 1 of the series, we provided an overview to the vSphere API. In this article, we will explore the vSphere Object Model.

Overview

In order to retrieve properties, perform operations or modify entities within the vSphere API, it is important to understand the vSphere Object Model’s structure and relationships. The vSphere API consists of three types of objects:

• Managed Object is a server side object
• Managed Object Reference is a client reference to a Managed Object
• Data Object contains information about a Managed Object and can also be used to transfer data between a client and server

Though a Managed Object is the common base type, it can be extended to represent other types of objects and we will see this in an example below.

The vSphere Object Model is complex due to the extensive amount of functionality it provides. To help you visualize the objects and relationships, here is a UML diagram for the vSphere 5 Object Model. The object relationships can be inferred by using the vSphere API Reference. Coloring has been added to highlight some of the important objects, which will be explained later.

Note: The diagram was modified from Steve Jin’s original post here and updated to reflect the vSphere 5 API. This was a great idea by Steve to create visualization for the vSphere API Object Model.

Managed Object

A vCenter Server or an ESX(i) host is composed of many different components such as configurations (objects highlighted in green are configuration related to an ESX(i) host), administrative/management services (objects highlighted in blue) or entities in its inventory (highlighted in orange are entities such as a cluster or virtual machine) to just name a few. These components are generically refereed to as a Managed Object and reside on the server itself. Each Managed Object has a defined type to distinguish them from one another and has an associated set of properties and operations. This provides the information needed to interact with one of these objects whether that is presented through the vSphere Client UI or using one of the vSphere SDKs.

Let’s take a look at an example of a Managed Object, a Datastore:

If we look at the vSphere API reference for a vSphere Datastore, we will see it has some properties defined on the object such as summary which provides a summary information about the datastore or host which provides a reference to all ESX(i) hosts that is attached to this datastore. There are also a set of operations associated with a datastore such as DatastoreEnterMaintenanceMode which is one of the new features in vSphere 5 that allows a user to enter a datastore into maintenance mode.

We can see from the diagram that a Datastore is also a Managed Entity type which in turn is a ExtensibleManagedObject and finally a Managed Object (highlighted in yellow). This concept is a known as as inheritance in OOP (Object Oriented Programming) as a way to share/re-use code for similar objects. Another example of this is the new StoragePod object in vSphere 5, also known as a Datastore Cluster in the vSphere Client UI. From the diagram above, we can see it extends the Folder object and as documented in the vSphere API, it has it’s own unique properties and operations. The StoragePod also inherits from it’s parent object’s attributes as a way to re-use similar properties that are applicable.   

The objects that extend the Managed Entity (highlighted in orange) are the most important Managed Objects to the vSphere inventory as well as the ServiceInstance which is an entry point to a vCenter Server or ESX(i) host (highlighted in red). We will dive into these topics further in the next article.

Managed Object Reference

To interact or modify an entity such as a virtual machine or ESX(i) host, a client application like the vSphere Client or one of the vSphere SDK’s needs to be able to reference a Managed Object from the server side, as you can not access the server side objects directly. This reference encapsulates the properties and operations of the Managed Object and it makes available to the client application. This reference is always guaranteed to be unique and persistent for the lifetime of the object within vSphere.

Data Object

As you perform an operation or modifications to a Managed Object, you are transferring data between the client application which can be the vSphere Client UI or one of the vSphere SDK’s. This data that contains properties and operations of a Managed Object is called a Data Object. The data types for the property of a Data Object can be another Managed Object, a simple string, an integer or an enumeration (enum). An enumeration is just a predefined set of values such as the state of a virtual machine will always be poweredOn,poweredOff, or suspend. A Managed Object Reference is also special type of Data Object that represents a Managed Object residing on server side.

Here is a diagram of of a client application interacting with either a vSphere vCenter Server or an ESX(i) host. We can see the client has a Managed Object Reference of a virtual machine and it uses Data Objects as a way to transfer the state changes between the client and server.

Though the vSphere Object Model is complex in nature, hopefully after this you will have a better understanding of how they are represented and how to access their properties and operations within vSphere. In the next article, we will take a look at the vSphere Inventory Hierarchy and how these Managed Objects are organized.

References:

• The vSphere Web Services SDK Programming Guide
• Object Model of VMware vSphere API: A Big Picture in 2 Minutes
• ManagedObjectReference vs ManagedObject

Get notification of new blog postings and more by following VMware Automation on Twitter:  @VMWAutomation

By William Lam, Sr. Technical Marketing Engineer

Are you interested in trying out one of our three vCloud SDKs (Java, .NET and PHP)? Check out the videos below that show you how to get started in under 5minutes! You can find additional resources by visiting each of our vCloud SDK community forums including more sample codes.  

Note: For best video quality, please view the videos in HD.

vCloud SDK for Java

Download Packages:

• vCloud SDK for Java
• Eclipse

Additional Resources:

• vCloud SDK for Java Community Forum

vCloud SDK for .NET

Download Packages:

• vCloud SDK for .NET
• Visual Studio

Additional Resources:

• vCloud SDK for .NET Community Forum

vCloud SDK for PHP

Download Packages:

• vCloud SDK for PHP
• xampp
  
• HTTP_Request2
• NET_URL2

Additional Resources:

• vCloud SDK for PHP Community Forum

Get notification of new blog postings and more by following VMware Automation on Twitter:  @VMWAutomation

By William Lam, Sr. Technical Marketing Engineer

There was a recent blog article that references VMware KB 1022312 that provides a manual method of enabling a new feature in vSphere 5 for a distributed portgroup called Auto Expand. As the KB explains, Auto Expand is a new advanced option for a distributed portgroup (Static Binding only) that allows for the number of ports to automatically increase by a predefined amount (increment of 10) when it is about to run out of ports. This is a really neat feature with the distributed vSwitch and allows users to still continue to provision new virtual machines and not require a system administrator to manually increase the number of ports.

The one caveat is that this advanced option is disabled by default and there is no option within the vSphere Client UI to enable this feature. The VMware KB outlines the steps to enable Auto Expand using the vSphere MOB, but the the process is not very user friendly and can be tedious for enabling several dozen distributed portgroups.

Though enabling Auto Expand is not available through the vSphere Client, it is available using the vSphere API. The property autoExpand is under distributed portgroup and can be queried or reconfigured by calling the ReconfigureDVPortgroup_Task API method. 

We will walk through an example of how Auto Expand works and provide a sample vSphere SDK for Perl script that allows you to check whether or not Auto Expand is enabled for your distributed portgroups and allowing you to enable or disable the feature.

Disclaimer: This script is provided for informational/educational purposes only. It should be thoroughly tested before attempting to use in a production environment.

vSphere SDK for Perl

Download script: updatedvPortgroupAutoExpand.pl

Usage: To run the script you will need to have VMware vCLI installed on either a Windows/Linux system or you can use the VMware vMA appliance.

Here is an example of a distributed vSwitch with several portgroups, we will focus on the Stage portgroup which currently is only configured with 2 ports:

To get a listing of all portgroups (Static Binding only), the number of ports configured and whether Auto Expand is enabled or not, use the “list” operation:
vi-admin@vma5:~> ./updatedvPortgroupAutoExpand.pl --server pod-vc --username root --operation list
Enter password:
dvSwitch: dvSwitch1
   dvSwitch-DVUplinks-462    4    false
   Development    10    false
   Stage    2    false
dvSwitch: dvSwitch2
   dvSwitch2-DVUplinks-476    0    false
   dvPortGroup    128    false

You can also specify the optional --dvswitch flag to only view from a specific distributed vSwitch:
vi-admin@vma5:~> ./updatedvPortgroupAutoExpand.pl --server pod-vc --username root --operation list --dvswitch dvSwitch1
Enter password:
dvSwitch: dvSwitch1
   dvSwitch-DVUplinks-462    4    false
   Development    10    false
   Stage    2    false

To enable Auto Expand for a particular dvPortgroup, use the “enable” operation and specifying the portgroup by using the --dvportgroup param (to disable just use “disable” operation):
vi-admin@vma5:~> ./updatedvPortgroupAutoExpand.pl --server pod-vc --username root --operation enable --dvportgroup Stage
Enter password:
Enabling Auto Expand for dvPortgroup "Stage" ...
   Successfully reconfigured dvPortgroup!

To view the changes, you can run the “list” operation again:
vi-admin@vma5:~> ./updatedvPortgroupAutoExpand.pl --server pod-vc --username root --operation list --dvswitch dvSwitch1
Enter password:
dvSwitch: dvSwitch1
   dvSwitch-DVUplinks-462    4    false
   Development    10    false
   Stage    2    true

Now we will create a new virtual machine with three network cards and assign all three to “Stage” distributed portgroup. Once the portgroup is about to run out, it will automatically increase the number of ports by 10 and bring the new total to 12 as you can see from the screenshot below:

Though this feature can be really useful, it would also be good to know when this occurs to ensure that the networking environment is being sized and configured correctly. You can easily do so by configuring a custom vCenter  alarm to notify you when this occurs for distributed portgroups that have Auto Expand feature.

The alarm must be created on a per distributed portgroup level, click on the “Alarms” tab of the portgroup and create a new alarm:
Next you under the “Event”, add a new trigger called “dvPort group reconfigured” and then click on Advanced Conditions. Select “configSpec.autoExpand” and use the “equal to” to “true”. 

This will allow you to monitor when port count is automatically increased and take the appropriate action such as an email or an SNMP trap.

Get notification of new blog postings and more by following VMware Automation on Twitter:  @VMWAutomation

By William Lam, Sr. Technical Marketing Engineer

The question of uniquely identifying virtual machines in either a vSphere or vCloud environment is one that comes up from time to time. I hear you asking, why is this import to me? One such reason is to help track virtual machine assets using external systems such as a CMDB (Configuration Management Database) and being able to uniquely identify a VM across multiple vCenter Servers and/or vCloud Director Cells.

In Part 1 of this article, I will provide an overview of what is needed to uniquely identify a VM in both vSphere vCenter and vCloud Director. In Part 2, we will dive into an example using the vSphere API and vCloud API showing the relationships.

vSphere

In vSphere, to uniquely identify a virtual machine, you can use the MoRef ID (Managed Object Reference ID) or the instanceUuid of a VM which is available using the vSphere API.  

The MoRef ID is a VMware internal identifier that is generated by vSphere when new objects are created in vCenter (e.g. adding ESXi host or creating a VM). This MoRef ID is used by all VMware solutions to reference objects within vCenter. The instanceUuid is a new property that was introduced in the vSphere 4.0 API to provide an easy way to uniquely identify a VM. Previous to this, the BIOS uuid of a VM was being used to identify a VM, but it was not always guaranteed to be unique and hence a vCenter specific UUID was created.

An example of a MoRef ID for a VM would be vm-415 where “vm” identifies the object type and 415 is just a counter. An example of an instanceUuid for a VM would be 501d6aa3-54fc-8b8d-99a2-e448463ead18 which represents a 128bit identifier.

If you are managing a single vSphere environment and using vCenter Server, then you can use either property from the vSphere API to uniquely identify your VMs. If you are managing multiple vSphere environments, then you need to combine the either the MoRef ID or instanceUuid VM with the unique identifier for a given vCenter Server. Within the vCenter Server, there is also a property in the vSphere API called instanceUuid which uniquely identifies a vCenter Server. This then allows you to uniquely identify a VM across multiple vCenter Servers as the individual instanceUuid of a VM is only guaranteed to be unique across a single vCenter Server instance.

vCloud

With vCloud Director, to uniquely identify a virtual machine, you would use the vCloud Director Object ID that is automatically generated by vCloud Director when a new virtual machine is created. The vCloud Director Object ID is available using the vCloud API.

An example of a vCloud Director Object ID for a VM would be urn:vcloud:vm:71d5b81a-f82d-495a-9e58-4b95a645c841 which is expressed in URN format.

To automatically handle uniqueness of a VM across a single or multi vCloud Director Cell, there is an object reference property called href that is provided as a URL that contains information about the vCloud Director Cell and VM vCloud Director Object ID.

An example of an href for a VM would be https://vcloudurl/api/vApp/vm-71d5b81a-f82d-495a-9e58-4b95a645c841 where the UUID of the VM is captured as part of the URL.

By using the href property, you are guaranteed a unique key within vCloud Director.

vSphere and vCloud

If you need to uniquely identify a virtual machine in both vSphere and vCloud, you can still use the identifiers listed above in their respective stack but how do you go about correlating the two? As mentioned earlier, all VMware solutions leverage the MoRef ID to reference objects within vCenter. Since vCloud Director sits on top of vSphere, it too also uses the MoRef ID to map entities between the two environments. As part of the vCloud API, there is a vCloud Extension API that provides information about the underlying vSphere infrastructure including the MoRef ID of a VM and vCenter Server instanceUuid.

Here is a diagram to help visualize the unique properties between vSphere and vCloud:

From a vCloud Director VM, we can map it to a specific vCenter Server using the vCloud Extension API to retrieve the MoRef ID of the VM and instanceUuid of the vCenter Server. Using the instanceUuid, we can then correlate that back to a specific vCenter Server and find the VM with matching MoRef ID. 

It is recommended that you leverage the MoRef ID as the common identifier between vCloud and vSphere. If you are only within vCloud, then you can use href property.

If you would like more details on the importance of the MoRef ID within vCloud Director, Chris Colotti wrote an excellent article here. I would highly recommend you take a look at his article.

Additional Notes:

• If you move a VM to another Organization vDC, the href and UUID will change
• If you Import a VM from vSphere to vCloud, the VM MoRef ID will stay same if you use “move” operation. If you use “copy”, the MoRef ID will change.

Additional resources:

• vSphere API Programing Guide
• vCloud API Programming Guide
• When Do vSphere MoRef's Change?

Thanks to Michael Haines and Timo Sugliani for their feedback on the article.

Get notification of new blog postings and more by following VMware Automation on Twitter:  @VMWAutomation

By William Lam, Sr. Technical Marketing Engineer

Our documentation team just posted the vCloud API Reference HTML version online. This was previously only available as a download zip file. You can now browse the vCloud API Reference under the vCloud Director Documentation page.

In addition to vCloud API Programming Guide and the vCloud API Reference to help you get started with the vCloud API 1.5. There are two additional documents that are useful to help users who are migrating from vCloud API 1.0 to 1.5 (Thanks to Michael Haines for the tip).

• vCloud API 1.5 Migration Guide
• vCloud API 1.0 and 1.5 Differences

Here is a screenshot of what the vCloud API 1.0 to 1.5 Difference document looks like:

Get notification of new blog postings and more by following VMware Automation on Twitter:  @VMWAutomation

By William Lam, Sr. Technical Marketing Engineer

In our previous article, we quickly looked at the differences between an API and an SDK. In this article, we will take a look at a high level summary of what makes up the vSphere API.

Overview

The vSphere API provides an interface for users to access the capabilities and features of the vSphere platform which includes the vCenter Server and ESX(i) hosts. Capabilities such as host management, virtual machine provisioning, monitoring, etc. are exposed as a Web Services API from both a vCenter Server and ESX(i) host. Depending on the feature, certain functionalities of the API will only be available at the vCenter Server (e.g. VM Cloning or Storage DRS).

Documentation

The complete vSphere API is documented in the vSphere API Reference guide which is available online and can also be downloaded here.

Licensing

Access to the vSphere API is governed by the various vSphere Editions which provides both read and write access to the API. If you are using vSphere Hypervisor (free edition of ESXi), the vSphere API will only be available as read-only.

Object Model

In order to retrieve properties, perform operations or modify entities within the vSphere API, it is important to understand the vSphere Object Model’s structure and relationships. The vSphere API consists of three types of objects: Managed Object which is a server side object, Managed Object Reference which is a client reference to a Managed Object and Data object which contains information about a Managed object.  

Inventory Hierarchy

The vSphere API organizes its entities (Datacenter, HostSystem, VirtualMachine, etc) in an inventory hierarchy. This inventory hierarchy structure is similar for both a vCenter Server and an ESX(i) host, but for a vCenter Server, it can be more complex. Understanding the hierarchy and the object relationships is crucial for navigating and searching through the vSphere API. 

Property Collector

The property collector is a very important interface in the vSphere API as it provides a way to monitor and retrieve properties of managed objects in the vSphere inventory. The property collector may seem complex, but it is a very powerful tool once you understand how it works. The functionality of the property collector is abstracted in some of our vSphere SDKs to make it easy to use but is also available directly for advanced users who want to leverage the full capabilities of the property collector.

Permissions, Roles and Privileges

Users must be authorized to perform any type of operation using the vSphere API. This authorization is governed by permissions, roles and privileges which are constructs within the vSphere API.

• A Permission associates a user or group with a role
• A Role is assigned to one or more privilege
• A Privilege defines a basic right (e.g. power on or reset a VM)

An entity in vSphere can have multiple permissions, but only one permission per user or group.

Hopefully this introduction provided you with a good overview of the vSphere API. In the next few articles, we will dive into more details on the vSphere Object Model, Inventory Hierarchy and Property Collector. Stay tuned!

Get notification of new blog postings and more by following VMware Automation on Twitter:  @VMWAutomation

By William Lam, Sr. Technical Marketing Engineer

Prior to vSphere 5, unpresenting a LUN from a set of ESX(i) hosts was not the easiest of tasks, as it took several steps that included masking rules on an ESX(i) host before and after the removal of a LUN (see this KB for more information). In vSphere 5, this process has been simplified by introducing an “unmount” datastore operation and “detach” storage device operation in the vSphere Client.

The unmount operation is a single step, but there is a caveat when an administrator detaches the LUN which is required prior to unpresenting it from the storage array. The administrator must go to each host that the LUN is attached to and detach it. This is trivial for one or two hosts, but can be quite tedious across several dozen hosts or having more than one LUN to unpresent.

Administrators also have the option of performing the unmount and detach operation using the command line via esxcli, but the commands are still required to be executed on each and every host the LUN is attached to.

How do we make this easier for administrators with lots of hosts? We can leverage the power of the vSphere API to connect to the vCenter Server, select a datastore and perform an unmount and/or detach operation across all ESX(i) hosts.

Below we have a PowerCLI and vSphere SDK for Perl script that allows a user to connect either to a vCenter Server and/or directly to an ESX(i) host to easily perform a “unmount” and “detach” operation for unpresenting a LUN.

Disclaimer: This script is provided for informational/educational purposes only. It should be thoroughly tested before attempting to use in a production environment.

PowerCLI

Download script: DatastoreFunctions.ps1

Usage: To run this script you will need the latest version of PowerCLI installed and PowerShell v2.

List all datastores and their mount/detach status by passing your datastore object(s) into the Get-DatastoreMountInfo advanced function as shown below:


To unmount a datastore pass your datastore object(s) to the Unmount-Datastore advanced function as seen below, this will unmount the datastore from all attached hosts:

Once unmounted you will then be able to detach the datastore from the hosts using the Detach-Datastore cmdlet as shown below:

vSphere SDK for Perl

Download script: lunManagement.pl

Usage: To run the script you will need to have VMware vCLI installed on either a Windows/Linux system or you can use the VMware vMA appliance. The script will prompt users to confirm both “unmount” and “detach” operation before proceeding.

List all datastores and their mount/detach status using the “list” operation:

To unmount a datastore, specify the datastore using --datastore and “unmount” operation:

To verify the “unmount” operation was successful, we will re-run the “list” operation and look for the “UNMOUNTED” string:

To detach the LUN, specify the datastore using --datastore and “detach” operation:

To verify that the detach operation was successfully, we will re-run the “list” operation again and look for the “DETACHED” string:

Get notification of new blog postings and more by following VMware Automation on Twitter:  @VMWAutomation

By William Lam, Sr. Technical Marketing Engineer

If you are not a developer or programmer, the term API and SDK maybe foreign words to you. If you have heard of either of these words, often times they are miss-used or used interchangeably with one or another which can cause confusion. So what is an API and SDK?

Wikipedia’s defines an API as:
An application programming interface (API) is a source code based specification intended to be used as an interface by software components to communicate with each other. An API may include specifications for routines, data structures, object classes, and variables.

Wikpedia’s defines an SDK as:
A software development kit (SDK or "devkit") is typically a set of software development tools that allows for the creation of applications for a certain software package, software framework, hardware platform, computer system, video game console, operating system, or similar platform.

Basically, an API provides an interface for users to access the underlying platform capabilities and features. An SDK may provide a set of tools, helper classes (e.g. additional code that simplifies the access of an API), specific language bindings and sample code to help users develop and use the API. In general, you could have a single API exposing a set of functionality and have multiple SDKs to access that API. An SDK may not always exists for an API, but it is helpful when one is provided.

Let’s take a look at an example using one of VMware’s common API and SDK, the vSphere API and vSphere SDK.

The underlying platform in this case is VMware vSphere which consists of VMware vCenter Server and VMware ESX(i). The vSphere API exposes the various functionalities of the platform such as host management, virtual machine provisioning, monitoring, etc. as a Web services API. VMware provides several SDKs that target particular programming/scripting languages such as Java, .NET, and Perl to name a few, that helps users get started and develop against the vSphere API. Users may bypass the vSphere SDK and use the vSphere web Service API directly, but the SDKs are much friendly from a development standpoint.

Hopefully this gave you a better understanding between an API and an SDK. In the next post, we will dive into an introduction of the vSphere API and the various components that make up the API. Stay tuned!

Get notification of new blog postings and more by following VMware Automation on Twitter:  @VMWAutomation