WilliamLam.com

New SRM 5 APIs

by // 2 Comments

There was a question about in one of my previous articles HBR (Host Based Replication) CLI for SRM 5 on whether there were any new/updates to the SRM 5 APIs. There are no official VMware SRM SDK's today as far as I know that can be consumed by toolkits such as PowerCLI, vSphere SDK for Perl, VI Java, etc. There is however an SRM Web Services API that can be used and has existed since the early days of SRM 1.0 as noted here in the documentation. Users that would like to use this API would need to create their own language bindings (stubs) based on WSDL (Web Services Description Language) provided by VMware.

Here are the list of available operations in the SRM 1.0 API:

  • SrmLogin
  • SrmLogout
  • GetApiVersion
  • ListRecoveryPlans
  • RecoveryPlanSettings
  • RecoveryPlanStart
  • RecoveryPlanPause
  • RecoveryPlanResume
  • RecoveryPlanCancel
  • RecoveryPlanAnswerPrompt
  • GetFinalStatus

In the SRM 5 API, there are 33 new operations not including the existing ones from 1.0:

  • ListProtectionGroups
  • ListInventoryMappings
  • GetInfo
  • GetPeer
  • ListProtectedVms
  • ListProtectedDatastores
  • ListAssociatedVms
  • GetProtectionState
  • ProtectionGroupListRecoveryPlans
  • ProtectionGroupQueryVmProtection
  • ProtectVms
  • UnprotectVms
  • AssociateVms
  • UnassociateVms
  • GetTasks
  • IsComplete
  • GetProtectionStatus
  • ListPlans
  • GetHistory
  • RecoveryPlanGetInfo
  • RecoveryPlanGetPeer
  • Start
  • Cancel
  • ListPrompts
  • AnswerPrompt
  • GetResultCount
  • GetRecoveryResult
  • GetResultLength
  • RetrieveStatus
  • RetrieveContent
  • SrmLoginLocale
  • SrmLoginSites
  • SrmLogoutLocale

During the SRM 5 beta, I did not see an updated API documents but I suspect the details and the implementation of these new operations will be available when SRM 5 is GA (generally available).

In the meantime, if you are on the SRM 5 beta and would like to get more details, you can retrieve the WSDL in several ways.

The first option is view the WSDL from your web browser by pointing it to your SRM server using the following URL: http://[srm-hostname]:8096/srm.wsdl

 
Note: Make a note of the URL protocol, it actually does not support HTTPS, but just normal HTTP when retrieving the WSDL

The second option is to browse the filesystem of the SRM server and the WSDL file can be found under the following path: C:\Program Files (x86)\VMware\VMware vCenter Site Recovery Manager\www

The Dreaded fault.RestrictedVersion.summary Error

by // 9 Comments

The question about the fault.RestrictedVersion.summary error message comes up pretty often on the VMTN community forums, specifically for new users of VMware vSphere. This particular error message is usually generated when trying to use one of the VMware SDK toolkits such as the vCLI, PowerCLI, VI Java, etc. or directly interfacing with the vSphere API for automation. The reason for this error message is due to the use of the free vSphere Hypervisor license (formally known as free ESXi).

Here is an example of the error trying to use vCLI to put an ESXi host into maintenance mode:

 
Here is an example of the error trying to use PowerCLI to power on a virtual machine:

Though the message is not easy to decipher for new users, it is a VMware license restriction placed on the vSphere Hypervisor license edition. Users only have the ability to perform read-only operations against the vSphere API which includes all the vSphere toolkits/management tools such as the vCLI, vMA, PowerCLI, VI Java, etc. Any operations that requires the change of state such as powering on a virtual machine or putting an ESXi host into maintenance mode is considered a write operation and is NOT allowed using the vSphere Hypervisor license type. When using the vSphere Client to manage an ESXi host, users have complete read and write access to these types of operations, they just can not be automated using the vSphere APIs or the various SDKs.

I personally think the error message should be updated to be a bit more clear and state that this particular license type (free ESXi) does not allow for any changes using the APIs. There is a small VMware KB article regarding the configuration of Jumbo Frames using the vCLI, but as you can see this error is not just applicable to vCLI but across the vSphere API/toolkits.

Now there are three types of licenses I consider an ESXi host can be configured and we'll walk through each of them. In the following example, I will be using the vSphere SDK for Perl script licenseManagement.pl to demonstrate the various license types which is allowed since it is only querying the license information which is a read operation to the APIs. 

1. Evaluation License - When you first install vSphere Hypervisor (free ESXi) and before applying your free license key, the host is automatically configured to be in this mode. In the evaluation state (60 days), you are basically licensed with ALL features just as if you have paid for the highest license type which is Enterprise Plus. You have full read and write access to the vSphere API and all the various vSphere toolkits for 60 days as part of the eval, once the 60 days are up, you will be configured just like the free version of ESXi. 

Here is an example of querying the license information for an evaluation ESXi host:

If we take a look at the License section using the vSphere Client, we'll see all the features included with this particular license type:

2. Free License - This is the free license that is provided from VMware once you have registered and downloaded vSphere Hypervisor (free ESXi)

Here is an example of querying the license information on a free ESXi host:

Notice the editionKey which is the first column and the name of the license in the second column which is "vSphere 4 Hypervisor" which represents the use of the free edition/license of ESXi. Both of these string text can also be used in conjunction to determine programmatically that you are running the free edition of ESXi.

If we take a look at the vSphere Client we also notice the list of features is quite small compared to the evaluation version:

3. All other licenses - This is all other vSphere edition license available which includes Essentials, Essentials Plus, Standard, Advanced, Enterprise and Enterprise Plus. For more details about the various license editions, please take a look a the vSphere Edition Comparison chart.

There is not a specific license feature that allows for the read and write access to the vSphere API and toolkits but by using any of the paid editions, you automatically have complete full read and write access to the vSphere APIs and the various vSphere toolkits.

Here is an example of querying the licensing information on a host with Enterprise Plus license type:

Here is an example of the features available via the vSphere Client:

So now you can easily check the vSphere edition you are running to determine whether or not you have the ability to use some of the awesome vSphere toolkits and management tools to automate your vSphere infrastructure which I highly recommend you do.

vSphere Tagging Feature Not So Invisible

by // 9 Comments

This evening I was reading a new blog post Tagging: An Invisible Feature in vSphere by Steve Jin in which he describes a hidden vSphere feature for tagging particular managed entities in your vSphere environment. The main consumer of this hidden feature is primarily VMware and it provides a level of meta data tagging to denote the importance of an entity. These tags are used in workflows in various vSphere products such as vCenter Server, vCenter Update Manager and View to just name a few.

Here is a screenshot of a VM entity using the vSphere MOB and as you can see from the tags, VMware can identify that this particular VM is running both vCenter Server and vCenter Update Manager.

If you have a VM that is a View Replica/Linked Clone, you may see these tags associated with the VM:

SYSTEM/COM.VMWARE.SIM.SVIMANAGEDOBJECT
SYSTEM/COM.VMWARE.VIM.SVIMANAGEDOBJECT

This feature can be really useful to allow users to tag particular objects in their environment of importance and easily correlate/integrate with a provisioning system and/or CMDB without having to resort to a separate database to store the meta data. You might say that custom fields exists today that can provide the same level of functionality, but they are actually pretty limited in scope. It only allows you to create custom attributes at a global vCenter level, host and virtual machine but not all managed objects such as Datastore, Networks, Resource Pool, etc.

So what if you wanted to create your own custom tags? Since these are hidden methods from VMware and they are not exposed through the public vSphere API, how might we access it? I spent a few minutes of digging and I was able to identify the two methods that pertained to tag management in the vSphere API:

addTag - Adds a tag to a managed entity
removeTag - Removes a tag to a managed entity

You can access both of these methods using the vSphere MOB as none of the official vSphere SDKs have these methods implemented. These methods are only supported when connecting to vCenter Server and are not exposed at an ESX(i) level.

In this example, I will create a custom tag at the Datacenter level called "WWW.VIRTUALLYGHETTO.COM"

Here is the path to a Datacenter object using the vSphere MOB:

If we scroll down on the page, you will notice a property called "tag" and as you can see in the screenshot below, no tags have been defined:

I will now craft the URL to the "addTag" method using the Datacenter as a point of reference:

https://reflex.primp-industries.com/mob/?moid=datacenter-1246&method=addTag

As you can see the method accepts an array of tags which can be defined within the section. All tags MUST begin with "SYSTEM/" and then a unique string following, in our example I used "SYSTEM/WWW.VIRTUALLYGHETTO.COM". Once you have created your tag, you will then click on the "Invoke Method" to add the tag. Since this method does not return anything, the return result is void.

Now if we go back to the Datacenter page and refresh the page, you should see the new tag that was just created:

To delete a tag, you will generate the same URL but replace "add" with "remove":

https://reflex.primp-industries.com/mob/?moid=datacenter-1246&method=removeTag

You will again fill in the tags to be removed and then click on "Invoke Method":

As you can see, you now have the power to create your own tags on various managed entities in your vSphere environment. If you want to automate this through a script or command line, you can create simple HTTP POST operations to the vSphere MOB or create the appropriate interface methods to the SDK bindings to support these hidden methods. I'll leave the latter as an exercise for the readers.