How to convert vSAN RVC commands into PowerCLI and/or other vSphere SDKs?

A common request that I see come up from our field and customers is getting specific vSAN Ruby vSphere Console (RVC) commands to be made more generally available in other vSphere CLI/SDKs like PowerCLI for example. Funny enough, many folks do not realize that this functionality has been there since vSAN 6.2 and specifically with the release of the vSAN Management APIs which exposes all vSAN functionality programmatically whether you are consuming it from the vSphere Web Client, Embedded Host Client or from RVC. All of these tools have been built using the vSAN Management APIs.

Although we have supported a variety of vSAN Management SDKs (language bindings) since its first release, I will say that PowerCLI consumption of the vSAN Management API has only been made available recently with PowerCLI 6.5.1 and it supports the latest release of vSAN 6.6 and can go all the way back to vSAN 6.2. Even with PowerCLI support, I still continue to see vSAN RVC requests come up time after time and it seems like folks still have not made the connection that RVC is just simply using the vSAN Management API just like UI does.

What is even more interesting is that the source code of RVC can be viewed by anyone to see how each command is implemented and which APIs are being used. RVC is built using rbvmomi (vSphere SDK for Ruby) which provides access to both the vSphere and vSAN Management APIs. Given the number of requests that I have seen, I am going to assume that this is not common knowledge and I figured the best way to show how this work is with a real world example. I decided to take the vsan.check_limits RVC command and create an equilvenet PowerCLI script that uses the vSAN Management API to provide the exact same information.

Note: You will need to know how to use the vSphere/vSAN Management APIs and knowing a little of Ruby can also help. If you are new to vSAN Management APIs, have a look at this blog post on how to get started.

Here is a screenshot of running the vsan.check_limits RVC command:

Here is a screenshot of running the PowerCLI script that I have created:

As you would expect, the data is exactly the same since they both consume the same underlying vSAN Management API.

So, how do we get started?

First, you will need access to the vSAN RVC source code. The easiest way to use the vCenter Server Appliance (VCSA) which automatically bundles the latest version of RVC based on the particular release of vCenter Server. All RVC source code can be found in /opt/vmware/rvc/lib/rvc and .rb extension file are the Ruby source code files. The primary vSAN RVC commands can be found in /opt/vmware/rvc/lib/rvc/modules/vsan.rb and the four other vSAN sub-namespaces such as vsan.health, vsan.iscsi_target, vsan.perf and vsan.stretchdcluster can be found in the modules/vsan directory. For your convenience, I have listed them below:

• /opt/vmware/rvc/lib/rvc/modules/vsan/health.rb
• /opt/vmware/rvc/lib/rvc/modules/vsan/iscsi_target.rb
• /opt/vmware/rvc/lib/rvc/modules/vsan/perf.rb
• /opt/vmware/rvc/lib/rvc/modules/vsan/stretchedcluster.rb

Now that you know where to look for source code, we now just need to search for the specific command we are interested in. Since vsan.check_limits command is part of the main vSAN RVC module vsan.rb, we can open that file and look for the specific operation which in this case it is called check_limits. If we do a search for this, we should see the following which defines the RVC operation.

opts :check_limits do
  summary "Gathers (and checks) counters against limits"
  arg :hosts_and_clusters, nil, :lookup => [VIM::HostSystem, VIM::ClusterComputeResource], :multi => true
end

Directly underneath, we can then see the implementation of the check_limits method and the specific vSAN Management APIs that are used.

def check_limits hosts_and_clusters, opts = {}
  conn = hosts_and_clusters.first._connection
  pc = conn.propertyCollector
...
...

Note: It is a fairly common practice to reference other helper functions within a given method, so you may need to search for other functions as you go through a particular RVC command. For example, check_limits calls query_limits function which does the actual data gathering before it is processed and displayed back to the users.

Here is the final PowerCLI VSANCheckLimits.ps1 sample script and below is a high level break down of what is going on within the script:

L19-21 - Process requirement parameter which is a string containing the name of the vSAN Cluster

L26-32 - Retrieve all ESXi hosts and ensure the host is connected and that vSAN is enabled on the host before proceeding

L34 - Get access the vsanInternalSystem manager for reach ESXi host which will be used to call specific vSAN Management APIs

L37-38 - Retrieve the RDT data using the QueryVsanStatistics() API method and process the results which will be returned as a JSON object

L41-56 - Process the JSON information and extract the data that we are interested in, referencing vsan.rb source code

L60-61 - Retrieve the component and usage data using the QueryPhysicalVsanDisks() API method and process the results which will be returned as a JSON object

L65-82 - Process the JSON data and extract the information that we are interested in, , referencing vsan.rb source code

L103-108 - Construct the data that will be shown for each ESXi host using a custom psobject (for display purposes)

L111 - Display the results which should match the RVC vsan.check_limits command

Although you have the source code in front of you, it may still take you a few try to extract or interpret the information. I am no Ruby expert, so it also took me a few trial/error before getting the output right. Do not get frustrated and just take your time. If you get stuck, the best recommendation is to take a break and walk away for a few hours. Nine out of ten times, when you come back refreshed, you will have a different perspective and usually you will get to the answer pretty quickly, at least I have personally found that to be the case for me when I get stuck. Happy Automating!

Additional vSAN Management API Resources:

• vSAN Management API Quick Reference
• Getting started w/the new PowerCLI 6.5.1 Get-VsanView cmdlet
• Correlating vSAN perf metrics from vSphere Web Client to both PowerCLI & vSAN Mgmt API
• Managing & silencing vSAN Health Checks using PowerCLI
• SMART drive data now available using vSAN Management 6.6 API