WilliamLam.com

VMware VSAN APIs

by // 15 Comments

For customers who are currently evaluating VMware VSAN, the vSphere Web Client is the primary interface for managing and configuring VSAN. However, these exact same VSAN operations can also be accessed programmatically from an Automation perspective. Given that I had spent quite a bit of time playing with VSAN in the lab and exploring some of its APIs, I thought it might be useful to share some of the common VSAN operations mapped to their respective APIs.

There are two main categories of operations that you should be aware of when working with VSAN:

  • VSAN specific operations
  • VM Storage Policy operations

VSAN Operations

The VSAN specific operations are available as part of the vSphere 5.5 API and the list below are the supported operations:

Enable/Disable VSAN on a vSphere Cluster (automatic claiming):

Manual Disk Claiming for an ESXi host:

  • Each ESXi host provides a vsanSystem manager at configManager->vsanSystem which provides the following methods for disk management
    • AddDisks_Task()
    • InitializeDisks_Task()
    • QueryDisksForVsan()
    • QueryHostStatus()
    • RemoveDisk_Task()
    • RemoveDiskMapping_Task()
    • UpdateVsan_Task()

Enable VSAN traffic type for a VMkernel interface

  • Use the ReconfigureComputeResource_Task() and set spec->vsanHostConfigSpec->HostSystem to the ESXi host you wish to configure and  spec->vsanHostConfigSpec->networkInfo->port->device to the specific VMkernel interface you wish to enable VSAN traffic type on

Internal VSAN manager for accessing low level CMMDS (Clustering Monitoring, Membership and Directory Services), object & disk management APIs:

  • Each ESXi host provides a vsanInternalSystem manager at configManager->vsanInternalSystem which provides the following methods for working with the lower level system of VSAN
    • QueryCmmds()
    • QueryObjectsOnPhysicalVsanDisk()
    • QueryPhysicalVsanDisks()
    • QueryVsanObjects()

Change the VM Storage Policy for a Virtual Machine Home OR Virtual Machine Home and Virtual Disk:

Change the VM Storage Policy for Virtual Machine Virtual Disk:

  • Use the ReconfigVM_Task() and set spec->deviceChange->device to the specif Virtual Disk to be reconfigured and set  spec->deviceChange->vmProfile to the VM Storage Policy ID

Enter Maintenance Mode for an ESXi host in a VSAN Cluster:

  • Use the EnterMaintenanceMode_Task() and set spec->
    maintenanceSpec->vsanMode->objectAction to the specific data accessibility mode defined here

Create and Delete directories on a VSAN Datastore:

SPBM

For VM Storage Policies, VSAN leverages the SPBM (Storage Policy Based Management) framework which allows administrators to create policies that define specific storage capabilities such as performance and reliability that can then be applied to a Virtual Machine. The SPBM API is exposed as a separate API endpoint in vCenter Server and will be required if you wish to create additional VM Storage Policy leveraging VSAN storage capabilities.

Query list of available VM Storage Profiles defined:

Create VM Storage Policy:

Delete VM Storage Policy:

Check VM Storage Policy Compliance:

Given a Virtual Machine Home or Virtual Disk, provide associated VM Storage Profile:

Given a VM Storage Profile, provide the associated Virtual Machine Home or Virtual Disk:

PbmQueryAssociatedEntity
PbmQueryAssociatedProfiles

Hopefully this provides a good overview of some of the common VSAN / SPBM operations and their associated API methods. If I have some spare cycles, I may create some sample scripts leveraging some of these API methods. In the meantime, you can check out these RVC (vSphere SDK for Ruby) modules leveraging both VSAN and SPBM APIs here and here.

Additional Resources:

How to upgrade to the latest VSAN Beta Refresh of RVC on Windows?

by // 4 Comments

A variety of new updates can be found in the latest VSAN Beta Refresh including a new RVC (Ruby vSphere Console) namespace called SPBM (Storage Policy Based Management) that allows users manage and configure VM Storage Policies. However, this update is currently only available for the VCSA (vCenter Server Appliance) and there is no update package for the Windows based vCenter Server (I hear this is being looked into).

UPDATE 12/04/13 - I just received an update from Cormac that we have just released a VSAN Beta Refresh for vCenter Server for Windows which you can download here.

For those of you who are running vCenter Server on Windows for the VSAN Beta and wish to try out the latest release of RVC which includes additional fixes as well as the new SPBM namespace can do so by just updating to the latest RVC package.

Step 1 - Download the rvc_1.3.3-1_x86_64.rpm package from the VSAN Beta website and upload that to your Windows vCenter Server.

Step 2 - Download and install 7zip on the Windows vCenter Server or another Windows server which can be used to extract the contents of the RPM package.

Step 3 - Right click on the RPM package and select the "Extract to rvc_1.3.3-1_x86_64/" option which should create a new folder that contains a new file called rvc_1.3.3-1_x86_64.cpio.

Step 4 - Right click on the CPIO package and select the "Extract to rvc_1.3.3-1_x86_64/" option which will create another folder containing the actual RVC bits.

Step 5 - Copy the contents from inside of opt\vmware\rvc to the following path on your vCenter Server C:\Program Files\VMware\Infrastructure\VirtualCenter Server\support\rvc Once you have replaced the updated RVC bits, you can now change into that directory and launch RVC by just typing "rvc" and hitting enter. To confirm that RVC has been successfully updated, you can then type "spbm." and hit tab and you should see eight new SPBM commands.

To learn more about RVC for Windows, I would highly recommend you check out Eric Bussink's blog article here.

SPBM (Storage Policy Based Management) MOB in vSphere 5.5

by // 8 Comments

A handy little tool that was useful for me which might come in handy for others too while working on my VSAN VM Storage Policy recovery article is the SPBM (Storage Policy Based Management) MOB which works similar to the vSphere MOB and FDM MOB for those of you who have used this interface before. The MOB stands for Managed Object Browser and simply put is an interface that allows you to browse the objects and properties of your vSphere environment by just using a web browser. You can also interact with the MOB by executing the same set of vSphere API methods as you would if you were to write a script or application which is useful for quickly getting a sense of what a certain property might look like or the output of an API method without writing a single line of code.

In vSphere 5.5, there is now an SPBM API which is available as a separate API endpoint on the vCenter Server. This new API allows you to manage the full lifecycle of a VM Storage Policy formally known as VM Storage Profiles from a programmatic standpoint which is very important when working with VSAN as everything is policy driven. For more more details about the new SPBM API, please take a look here. As mentioned earlier, one great way to learn about the API is by exploring the MOB and luckily the SPBM API includes one!

To access the SPBM MOB in vSphere 5.5, you will need to point your browser to your vCenter Server as that is where the endpoint is exposed using the following URL format:

http://[VC-IP-OR-HOSTNAME]:8190/mob

To access the SPBM MOB in vSphere 6.0, you will need to point your browser to your vCenter Server as that is where the endpoint is exposed using the following URL format:

http://[VC-IP-OR-HOSTNAME]/pbm/mob

You will be prompted for your vCenter Server credentials before the MOB will allow you to login. Once you are logged in you will be brought to the main service content of the SPBM endpoint similar to the vCenter Server service content and you can then click on content link to explore the various sub-managers that are available.
Note: You will be able to get more details on each of these sub-managers by taking a look at the VM Storage Policy Programming Guide and VM Storage Policy API reference guide.
To quickly show you around, I will provide a couple of examples using the ProfileManager and I am sure you can probably guess what type of functionality it provides :). The first method that we will take a look at is the PbmQueryProfile which will return the list of available VM Storage Policies that have been defined. You will need to set the resourceType property to "STORAGE" and remove the profileCategory and then click on "Invoke Method".
If you are using VSAN and you do not have any VM Storage Policies defined, there will still be two default VM Storage Policies that is automatically created when VSAN is enabled. What you will see are the internal identifiers for each of the VM Storage Policy and as you can see from the output I have 5 VM Storage Policies.
You will notice that the output does not contain the human readable display name for each VM Storage Policy, to retrieve that information we will need to use the PbmRetrieveContent which accepts a list of VM Storage Profile ID's and in return provide the human readable name as well as other properties such as the initial creation date and last modified date. Using the pre-canned input form, you can specify one or more VM Storage Profile IDs from the previous step and then click on "Invoke Method".
In my example, I specified two of my VM Storage Policies and I can see they map to the names  "Aluminum" and "Copper" which is what I named them when I first created the policies.
From here on out, we will be using the VM Storage Policy ID as that is what is used to uniquely identify a VM Storage Policy and input for majority of the SPBM API methods. Now if we want to see what objects (VM Home directory or VMDKs) are associated with a particular VM Storage Policy we can use the PbmQueryAssociatedEntity method. You will need to provide the VM Storage Policy ID and remove the entityType and then click on the "Invoke Method".
As you can see from the output this a virtualMachine object type which tells us this VM Storage Policy is used for the VM Home. Lets go ahead and specify a VM Storage Policy that is used for a Virtual Machine's VMDK and see what that looks like.
We now see the object type is virtualDiskId and you can see the particular VMDK and the associated Virtual Machine by looking at the key which has the format of vm-mo-ref:vmdk-key. Now what if we wanted to perform the reverse look up, by providing only a Virtual Machine or VMDK as input? Well, we can easily do this lookup by using the PbmQueryAssociatedProfiles method. This API method requires you to specify three parameters: objectType, key and serverUuid (technically speaking the serverUuid can be left out).
From the above examples you will get an idea of what the expected input format is for either a Virtual Machine or VMDK query.
Here is an example of a Virtual Machine query:
Here is an example of a VMDK query:
Hopefully this quick introduction of the SPBM MOB will give you a good idea on how you can leverage this interface, especially if you plan on using the new SPBM API to automate and manage your VM Storage Policies.