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.

Automating VCSA Network Configurations For Greenfield Deployments

by // 6 Comments

If you deploy the VCSA (vCenter Server Appliance) or other virtual appliances directly onto an ESXi host,
you will notice the network configuration wizard for the virtual appliance is not available as you would expect when deploying to a vCenter Server.

The reason for this is that ESXi does not support some of the advanced OVF/OVA properties such as the Networking section and you will need to deploy the OVF/OVA to a vCenter Server to be able to configure these advanced options. This poses a problem if you need to deploy the VCSA in a greenfield environment where you will not have an existing vCenter Server running and you will be deploying directly to the ESXi host. Unless you have a DHCP enabled network, you will most likely need to manually go into the vSphere C# Client to change the network configuration as it was unable to obtain an IP Address.

Though this is a one time configuration, it is still not ideal and would require the use of a Windows system to access the vSphere C# Client. You can actually get around this by leveraging the GuestOperations API (previously known as VIX API) which allows you to perform operations within the guestOS that is running VMware Tools. The other nice thing about the GuestOperations API is that it does not require any network connectivity from the virtual machine.

Note: The GuestOperations API can be accessed in variety of ways and in this article I am demonstrating just two methods and does not require a Windows system. You can also access the GuestOperations API using PowerCLI if you are more comfortable with Windows and do not wish to use the vSphere C# Client to manually configure the network settings for the VCSA. I would also like to stress that though this article is about the VCSA, you can easily apply this to any VMware based virtual appliance or virtual appliance running VMware Tools.

The most important thing to identity before using the GuestOperations API is the specific command or program you wish to invoke and the argument it accepts. To configure the network configuration for the VCSA or any other VMware based virtual appliance, you would use /opt/vmware/share/vami/vami_set_network If you just run this command by itself, there are variety of options from IPv4 to IPv6, static or dhcp configuration. In our example, we will be configuring a Static IPv4 address for our VCSA and the command we would run is the following:

/opt/vmware/share/vami/vami_set_network "eth0 STATICV4 192.168.1.150 255.255.255.0 192.168.1.1"

Method 1 - Using RVC (Ruby vSphere Console)

 

RVC is a nice open-source tool for interactively managing and configuring your vSphere infrastructure. RVC can be installed on any platform, in this example, I am running RVC on my Apple OS X laptop.

Step 1 - We first need to deploy the VCSA OVA and we can do so by using the ovftool via the command-line which can also be installed on Mac OS X system.

Step 2 - We then login to our ESXi host using RVC.

Step 3 - Next we will need to "change directory" to the location of our VM, in this example my VCSA is called VCSA-5.1. We can then run the "info ." command to view the summary of our VM. We can see that our VM is powered on from our initial deployment and we are ready to apply our network configurations in the next step.

Step 4 - To be able to run the above command, we will need to first authenticate into the guestOS. To do so, we will run the "vm_guest.authenticate ." and we will be prompted for the VCSA password. By default, the command assumes the username is root but that can also be specified on the command-line. If you are successful, you should not see any errors and then we can run the "vm_guest.start_program" command. Run the following to set a IPv4 static IP Address:

vm_guest.start_program . --program-path /opt/vmware/share/vami/vami_set_network --arguments "eth0 STATICV4 192.168.1.150 255.255.255.0 192.168.1.1"

Note: All commands in RVC can be tabbed out with auto-completion.

If the command was successful, you can quit RVC and you should be able to ping the IP Address that you have just configured.

Method 2 - Using vSphere SDK for Perl Script

 

Awhile back I wrote a script called guestOperations.pl which is a vSphere SDK for Perl script that implements the new GuestOperations API. This is a generic script which can be used to remotely connect to either a vCenter Server or ESXi host and perform operations within a guestOS as long as VMware Tools is installed and running. In this example, I also have the vSphere SDK for Perl installed on my Mac OS X laptop, but you can also install this SDK on any platform as well.

Step 1 - We will first use the "validate" operation to ensure our credentials to the guestOS is correct, but more importantly ensure that VMware Tools is up and running.

If the operation was successful, we should see our guest credentials validated. If not, you may need to wait a minute or two while VMware Tools is still loading up.

Step 2 - To invoke the command to configure the network configuration, we will use the "startprog" operation and run the following:

./guestOpsManagement.pl --server mini --username root --guestusername root --vm VCSA-5.1 --operation startprog --program_path /opt/vmware/share/vami/vami_set_network --program_args "eth0 STATICV4 192.168.1.150 255.255.255.0 192.168.1.1" --working_dir /

If the command was successful, then you should now be able to ping the IP Address that you have just configured.

As you can see, with the use of the GuestOperations API, you can do more than just setup the network configuration for a VM, you can run pretty much any command within the guestOS as you normally would if you were to RDP or SSH in. This is a very powerful interface that you can leverage to help you automate your virtual machine deployment and configurations!