vSphere API – Page 26

A kitten dies, every time you query the VCDB

03.19.2014 by William Lam // 14 Comments

Okay, maybe I am being a bit dramatic 😉 However, this is what crosses my mind every time I hear someone trying to query for something in the VCDB (vCenter Server Database) instead of using the vSphere API. Every so often I see a customer request asking for a specific SQL Query to find something in the VCDB. It just baffles me on why someone would want to go through such pain, not to mention this is not supported nor a recommended best practice.

Disclaimer: No kittens were harmed during the writing of this article

There are many disadvantages by going directly to the VCDB versus going through the vSphere API:

There are no guarantees on backwards compatibility of the database schema or database views from release to release
The data is in a very raw form, there is no abstraction which is usually provided by an API to make consumption easier
Risk of crafting queries that could negatively impact the performance of vCenter Server
Not officially supported by VMware, unless directed by VMware GSS
Pulling hair out while trying to understand the internal relationships of various objects, especially with a complex system like vCenter Server

Although the vSphere data is eventually persisted in the VCDB, the main purpose of the vSphere API, like many other software APIs is to provide a well defined interface for interacting with the underlying platform. I think there are still many vSphere/System Administrators who fear the word "API". Instead of being afraid of APIs, we should all embrace it and start to better understand how they work as it is just a way of interacting with the underlying system.

I can speak from my own personal experience, the first task for me out of college and into the real world was to look into building an application impact assessment report when an vSphere HA event occurred. We knew which Virtual Machines were restarted, but we did not have a good idea of what applications were affected. I had to correlate the impacted Virtual Machines with a list of applications and application owner from our homegrown CMDB which ran on MS SQL Server. At the time, I did not know any better and I thought best way of getting this information was to go directly to the VCDB (at the time this was Virtual Center 2.5). I found myself creating super complex SQL queries and trying to reverse engineer the relationships between all the different tables to get basic information from vCenter Server. If I knew what I know now back then, I would have gone straight to learning the VMware APIs, as I could have gotten everything I needed in just a couple of lines of code. After completing the project among few others which I leverage the VCDB directly, I realized that I needed to learn this VMware API. This early lesson has greatly helped me in my career to further automate IT/VMware infrastructure and help us move towards this new world of a Software-Defined Datacenter.

The diagram below provides an overview of some of the ways the vSphere API can be consumed by customers. An example is the vSphere Web Client and the legacy vSphere C# Client, this is a UI interface that customers can use to interact with the vSphere platform which in turns uses the vSphere API. There are also a variety of CLIs and scripting/programming languages that are built for easily extracting information and performing operations against vSphere that could be as simple as one-liner. The vSphere API can also be consumed by 3rd party companies to further abstract and provide new and interesting ways of interacting with vSphere, a great example of this is the CloudPhysics Card Builder platform that makes creating custom vSphere reports a breeze.

Note: The diagram above is just an example of some of the SDK/CLI/UIs that VMware provides to our customers. This is not meant as an exhaustive list and you can find all SDKs/CLIs for vSphere here.

Hopefully with this information, customers will better understand the benefits of using the vSphere API versus going directly to the VCDB.

Exploring VSAN APIs Part 5 – VSAN Host Status

03.17.2014 by William Lam // 1 Comment

Another useful bit of information from a troubleshooting perspective is to be able to quickly get summary of all your ESXi hosts participating in a VSAN cluster. Critical information such as the health, state, VSAN Node/Cluster UUID for each ESXi host can be queried through the vsanSystem using the QueryHostStatus() vSphere API method. To demonstrate this simple operation, I have created a vSphere SDK for Perl sample script called vsanHostDiskMapping.pl.

Disclaimer: These scripts are provided for informational and educational purposes only. It should be thoroughly tested before attempting to use in a production environment.

To show the ESXi host status, you will need to specify a vSphere Cluster running VSAN and use the following command:

./vsanHostStatus.pl --server vcenter55-1.primp-industries.com --username root --cluster VSAN-Cluster

As you can see this is an easy way to quickly get the health of ESXi host participating in the VSAN cluster.

Exploring VSAN APIs Part 4 – VSAN Disk Mappings

03.10.2014 by William Lam // Leave a Comment

A useful feature that is provided in the vSphere Web Client for VSAN is the ability to visualize the VSAN disk mappings for each ESXi host contributing to the VSAN cluster. This information will come in handy for troubleshooting as well as checking or servicing a disk failure.

You can easily retrieve the VSAN Disk Groups for each ESXi host and their respective SSD and HDD within that disk group by looking at the following property vsanSystem->config->storageInfo->diskMapping. There is a variety of information for each device such as the name, capacity, state, health, etc. of each disk. To demonstrate the above operation, I have created a vSphere SDK for Perl sample script called vsanHostTrafficTypeMgmt.pl

Disclaimer: These scripts are provided for informational and educational purposes only. It should be thoroughly tested before attempting to use in a production environment.

To show the disk mappings, you will need to specify a vSphere Cluster running VSAN using the following command:

./vsanHostDiskMapping.pl --server vcenter55-1.primp-industries.co --username root --cluster VSAN-Cluster

In the above output, you will see the VSAN Disk Groups for each ESXi host along with their respective device name and capacity. Here is another screenshot for a VSAN environment that contains multiple VSAN Disk Groups:

This is just a very tiny sub-set of the available properties for a disk, for more information take a look at the scsiLun definition within the vSphere API Reference.