New Licensing APIs Since VMware vSphere 4

There has been a total change in vSphere licensing model since version 4. Before that, you need a special/dedicated licensing server which may be more flexible/powerful but also cause many troubles in production environment which made licensing related issues one of the top categories in tech support.

vSphere 4 has dramatically simplified the whole licensing model, and removed the licensing server. To find out how the new licensing model works, check out the VMware vSphere 4 Licensing Guide. It covers both the vSphere side and the portal with which you can easily manage your license keys: splitting/combining, etc. This article does not cover the portal part but related APIs only.

Management APIs reflect product features. If you check the latest API reference, you will find out that quite a few properties and methods of the LicenseManager managed object are deprecated and added (If you use managed object browser to view the deprecated properties, they may be null or literally “unset”). A new managed object LicenseAssignmentManager is added for assigning licenses to entities like vCenter or ESX/ESXi.

Although I covered the changes of vSphere 4 in appendix of my book published by Prentice Hall, they are pretty high level. In this post, I will give a detailed introduction on the changes related to licensing APIs, and how you should use the new licensing APIs effectively.

LicenseManager

The change in LicenseManager is dramatic in that whatever there before are deprecated and all the current ones are newly added. You can think of the LicenseManager as a brand new managed object except that it inherits the old name. I will not include the deprecated in the following discussion. If you are interested in them, please check them out in either API ref or my book.

The new responsibilities include managing new licensing keys which are 25 character strings that encapsulate information on the entitlement. Remember, it does not actually assign licenses, which is left to the new LicenseAssignmentManager (will be discussed soon.)

The 3 new properties are as follows:

The 6 new methods are shown in the following code snippet from VI Java API:

public class LicenseManager extends ManagedObject
{
  public LicenseManagerLicenseInfo addLicense(String licenseKey, KeyValue[] labels) throws RuntimeFault, RemoteException;
  public LicenseManagerLicenseInfo decodeLicense(String licenseKey) throws RuntimeFault, RemoteException;
  public void removeLicense(String licenseKey) throws RuntimeFault, RemoteException;
  public void removeLicenseLabel(String licenseKey, String labelKey) throws RuntimeFault, RemoteException;
  public void updateLicense(String licenseKey, KeyValue[] labels) throws RuntimeFault, RemoteException;
  public void updateLicenseLabel( String licenseKey, String labelKey, String labelValue) throws RuntimeFault, RemoteException;
}

Most of the methods are self explaining. The key to understand the new LicenseManager is the LicenseManagerLicenseInfo, which includes the following properties:

Seemingly easy and simple, the properties represent a learning curve here. As you can guess from its type, any item in the array can be any value (any type), meaning you put any data there. In practice, you can find string, KeyValue, long, date, and even LicenseManagerLicenseInfo (I don’t have explanation why another copy of LicenseManagerLicenseInfo is embedded in itself) as values.

In the “properties”, you can find feature definitions, as shown in the following MOB screenshot:

LicenseAssignmentManager

This newly added managed object is responsible to assign/remove/query licenses to particular entities like vCenter or ESX/ESXi. The following code snippet shows what it does exactly.

public class LicenseAssignmentManager extends ManagedObject
{
…
 public LicenseAssignmentManagerLicenseAssignment[] queryAssignedLicenses(String entityId) throws RuntimeFault, RemoteException;
 public void removeAssignedLicense(String entityId) throws RuntimeFault, RemoteException;
 public LicenseManagerLicenseInfo updateAssignedLicense( String entity, String licenseKey, String entityDisplayName) throws RuntimeFault, RemoteException;
}

One important thing here is to understand the value/format for the entityId. For ESX/ESXi server, it is the value of its MOR, for example, “host-21”; for vCenter server, it’s the value of the instanceUuid added into AboutInfo data object since 4.0, for example, “BA9CE658-75F7-4A99-ACE6-99EB1376B94A”.

You may be wondering how you can get all the assignments, meaning which license keys assigned to which entities. If it’s just a VC, it’s easy because you just get its instanceID and call the queryAssignedLicenses() method. For ESX/ESXi servers, they could be hundreds. Do you have to first grab all of their MOR values and call one by one for hundreds of times?

Luckily, you don’t have to. The parameter to the queryAssignedLicenses() is optional, and you can bypass that (In VI Java API, you use null in place of entityId; in MOB, you leave it as empty string). As a result, you will get all the mappings in the returned LicenseAssignmentManagerLicenseAssignment[] array. The following table summarizes the properties in the data object.

Again, you see properties defined as KeyAnyValue[], which can hold any types of values. The most important thing is the “inUseFeatures” key/value pairs.

With the queryAssignedLicenses(), you can retrieve all the assignments in a single call. In a fairly big environment where a license key is assigned to many ESXi servers, you have a big array returned, most of which are duplicated (see the assignedLicense property). This is of course not an ideal case but a compromise given that the method is intended for single entity at a time.

What’s Next?

You’ve learned the new license model and related APIs since vSphere 4. Just like learning any APIs, it’s always good to show some samples. That is what I will do. Please stay tuned for next post with samples based on VI Java API. If you haven’t tried VI Java API yet, it’s time to do so. Be ready for licensing samples in a future post.

•