WilliamLam.com

vCloud Director Report 1.0.0

by // 4 Comments

Over the winter holiday I started to explore the vCloud API and one of our SDKs, vCloud SDK for PHP. VMware provides two additional vCloud SDKs: Java and .NET. I had used Java in college and I wanted to stay away from anything Windows related, so I thought I give PHP a try and it was the closest thing to Perl 😉

Since this was my first time using the vCloud API and SDK, I thought what better way to learn than to create a script similar to my vSphere Health Check Report for vCloud Director? This not only helped me to understand the objects in vCloud Director from an API perspective but no such reporting tool exists today for administrators and end users of vCloud Director.

Here is an example of what a report could look like: vCloudDirectorReport.html

To use the script, you will need the following per-requiste:

  • Install vCloud SDK for PHP, take a look at article on how to get setup.
  • Running vCloud Director 1.5 (Script uses the new API Query Service)
  • Download both config.php which includes configuration parameters for the script and vmwarevCloudDirectorReport.php script.

To get a list of the available commandline options, just type "php vmwarevCloudDirectorReport.php":

php vmwarevCloudDirectorReport.php

Error: missing required parameters
Usage:

[Script]
VMware vCloud Director Report v1.0.0

[Description]
This script provides a detail report of your VMware vCloud Director system

[Usage]
# php vCloudReport.php -s -u -p [Options]

-s|--server [req] IP or hostname of the vCloud Director.
-u|--user [req] User name in the form user@organization for the vCloud Director instance.
-p|--pswd [req] Password for user.
-t|--type [req] Type of report [system|orgadmin|orguser].

[Options]
-r|--report [opt*] Name of html output file (e.g. vCloudReport.html).

[Examples]
# php query.php -s 127.0.0.1 -u admin@system -p password -t system
# php query.php -s 127.0.0.1 -u admin@coke -p password -t orgadmin
# php query.php -s 127.0.0.1 -u admin@pepsi -p password -t orguser

The config.php can be used to store the vCloud URL and credentials or you may specify it via the commandline using -s, -u and -p arguments. In addition, you will also need to specify -t flag which is based on the type of user you are logging into whether that is system (administrator), orgadmin or orguser.

The report can easily be customized by toggling parameters in config.php which includes the following parameters:

Depending on the report type, certain flags will be applicable. By default, all flags are enabled but you my disable ones you do not wish to see.

Here is an example of the script logging into vCloud Director instance with the administrator account in the System organization:

This is the first iteration of the script, I plan on adding additional information and if you have any feedback/suggestions, please leave a comment below.

How to Use Custom VM Icons in the vSphere 5 Client

by // 3 Comments

Ever get tired of the same old virtual machine icons in the vSphere Client? Ever thought about changing it? Well with vSphere 5, you can! Here is a screenshot of some the custom icons I added for several virtual machines in my development lab.

One of the major enhancement in the vSphere 5 API is the introduction of the vCenter Solutions Manager, vSphere ESX Agent Manager, and vServices SDK. These various interfaces allows ISVs, partners and end users to easily extend the functionality of the vCenter Server and provide solutions that are tightly integrated via extensions/plugins that are aware of features such as vSphere HA, DRS and DPM.

Here what each of the interfaces provides:

vCenter Solutions Manager - is a view in the vSphere client where you can monitor and interact with the solutions that register with a vCenter Server instance. Solutions Manager shows three standard tabs for each running solution. The tabs list the virtual machines that a solution deploys and manages, show the health, name, company URL, version of the solution, and show any vServices that the solution provides.
vSphere ESX Agent Manager - automates the process of deploying and managing vSphere ESX agents. The services that ESX Agent Manager provides include out-of-the-box integration of agents with vSphere features such as DRS, AddHost, High Availability, DRM, and maintenance mode. All of these features can be difficult to integrate with manually. ESX Agent Manager also allows users to monitor the health of ESX agents, and blocks users from performing certain operations on ESX agents that might affect the virtual machines that use them. For example, ESX Agent Manager can prevent an ESX agent virtual machine from being powered off or moved from an ESX host that contains other virtual machines that use that agent.
vServices SDK - is a service that a solution provides to specific applications that run inside virtual machines and vApps. A solution can provide several types of vServices. Virtual machines or vApps can have dependencies on several types of vServices. A vService is similar to a virtual hardware device upon which virtual machines and vApps can depend. Instead of providing a piece of virtual hardware, vServices typically provide access to a service across a network. By providing a vService, a solution can expose application-aware services to virtual machines and vApps. For example, a vService can provide a backup service or a logging service to virtual machines and vApps.
For more details about these interfaces and how to implement them, take a look at the documentation here.

Even though these APIs are really meant for ISVs and partners to consume, if you would like to add a splash of color to your environment, you can use the following trick. At at high level we will be adding a new extension(s) which includes a mapping of a particular solution (e.g. logical name) to a particular icon that a virtual machine or vApp can be associated with. The icons must be 16x16 PNG format referenced by a URL. Once the custom extension has been created, you will then need to reconfigure the virtual machine(s) and associate the managedBy property to the solution's logical name key to update the virtual machine's icon.

You will need access to either the vCLI or vMA and the following two vSphere SDK for Perl scripts: registerCustomSolution.pl and updateVMManagedBy.pl You will also need access to vCenter Server 5 as this is not supported on an ESXi 5 host.

There is a very simple example in registerCustomSolution.pl which creates two extensions: one that includes custom icons and tabs that can link to any webpage (vGhetto) and one that only includes custom icons (Custom Application). You will need to edit the script so it fits your environment and there is a special variable in the script called "editedScript" which is set to 0 that prevents the script from running. This will ensure you do not accidentally create these extensions based on information in my development environment. Once you have updated the script, go ahead and change the value to a 1.

When you are ready, you will use the registerCustomSolution.pl script to create the extensions, here is an example:

To verify that the extensions were created properly with the information you provide, you can use pluginExtensionManager.pl to list all registered extensions. The command is the following: ./pluginExtensionManager.pl --operation list

You should see at the bottom of the output the extensions that were just registered and the associated configurations URL + icons. It is important to make note of the extension key (e.g. com.vmware.vGhetto) and the solution type string as that will be needed in the next section.

Now all we need to do is associate a particular virtual machine with the solution to update the virtual machine's default icon. You will use the updateVMManagedBy.pl script and using the extension key and type from the output from the previous screen.

To verify the icons have been updated, you will need to login to the vCenter Server and check out your virtual machines.You will also notice that on the right hand side of the virtual machine summary screen, there is a new "Managed By" section which includes a link to the vCenter Solution Manager.

Note: If you would like to reset or revert back to the original icons, you just need to use the  updateVMManagedBy.pl script and specify a empty string for the key. If you would like to unregister and remove the extension all together, you can use pluginExtensionManager.pl and perform remove operation.

Another way to view all the vCenter Solutions is on the home page and by clicking on the vCenter Solutions Manager icon.

From here you will see all registered vCenter extensions including some information about the vendor, version and health of the extension.

Here is a drill down into one of the extensions that contains several tabs to some URLs

As you can see, you can link to some useful URLs that can easily be accessible through the vSphere Client without having to go to your browser. Another neat feature of the tabs is to include any web management interfaces for a particular solution/vApp so that you can easily configure and manage the system from a single pane of glass.

In addition to this, you can also get a summary of the registered virtual machines with a given solution by clicking on the "Virtual Machines" tab and selecting "Managed By" box, the "Server" and "Agents" are reserved for ESX Agents.

There are also two caveats to be aware of if you decide to create custom icons for your virtual machines. The first is when you edit a virtual machine, you will get an annoying pop-up that states changes to the solution is not recommended. Under normal circumstance, where a solution/extension is provided by a 3rd party, you definitely do not want to manually tweak the virtual machine but in this scenario, it is fine.

The second thing I noticed is the custom icons do not properly show up in the nextgen vSphere Web Client, a default icon is used instead for virtual machines who have custom icons. I am not sure if this is a display bug with the vSphere Web Client or with the APIs.

So there you have it, if you are bored at looking at the same old icons and would like to differentiate some or all of your virtual machines, you now have the option to use custom icons.

VMware API Related Acronyms

by // 3 Comments

Duncan Epping recently wrote an article about VMware related acronyms and shared with the community  the history and origins of some of the acronyms (e.g. ESX, GSX). After reading Duncan's article, I realized the acronym list primarily focused on product names and features. They did not cover some of the API related acronyms that I was curious about. If you have worked with the VMware APIs, SDKs or vmkernel, vmkwarning, hostd, vpxa, vpxd, etc. logs you may have noticed some of these acronyms and wondered what they actually stood for.

Here is my compiled list of VMware API related acronyms that I have been able to dig up by looking at these various locations:

DMS: Data Management Service
EAM: ESX Agent Manager
FDM: Fault Domain Manager
HMO: Host Managed Object
LS: License Service
MOB: Managed Object Browser
MOR: Managed Object Reference
OMS:  Operation Management Service
RBD: Rule Based Deployment (Auto Deploy)
SMS: Storage Monitoring Service
SPS:  Storage Policy Service
STOREMON: Storage Utilization Monitoring
VCI: (vci-integrity deals with VMware Update Manager, but no info on acronym)
VMAM: VM Application Monitoring
VMODL: VMware Managed Object Design Language
VMOMI: VMware Managed Object Management Interface
VOD: VPX Operational Dashboard
VOB/VOBD: VMkernel Observation 
VORB: VMOMI Object Request Broker Library/Application
VSM: vService Manager
VWS: VMware Web Services
WOE: Workflow Orchestration Engine

Disclaimer: These namespaces may change without notice as they are part of the internal VMware APIs. These are not publicly documented by VMware and should not be relied on other than for informative purposes.

There was also a recent VMTN question regarding the following two licensed features that is displayed for a given ESX(i) host and it was not clear what they were used for:

Here are the actual names and purposes:

dpvmotion: Direct Path vMotion (VM DirectPath I/O)
dvfilter: vNetwork Appliance API (dvfilter was an internal name)

The following are not VMware acronyms, but you may see these from time to time if you work with the vSphere API/SDKs:

API: Application Programming Interface
SDK: Software Developement Kit
WSDL: Web Services Definition Language
SOAP: Simple Object Access Protocol

I would also like to thank both Steve Jin and Reuben Stump from VMware in helping me track down the last few acronyms that I could not figure out.

If there are any additional acronyms that I missed or ones I should add to the list, please feel free to leave me a comment.