What’s New in vSphere API 5.0
Because vSphere 5.0 is now released, I can talk about the changes of the API in public. As you may have heard me saying many times, management APIs are the “view” to the product. New features can be exposed via APIs. Understanding the changes in APIs helps you understand the product itself.
The API Reference 5.0 has the first page “New and Changed Managed Object Elements in 5.0” summarizing all the changes. To support vSphere 5.0 in new VIJava API , I’ve gone through all these changes. I will write a separate article on VIJava new release soon.
Time to learn how to "Google" and manage your VMware and clouds in a fast and secure
HTML5 AppNew Managed Object Types
Nine new managed object types have been added into 5.0: GuestAuthManager, GuestFileManager, GuestOperationsManager, GuestProcessManager, HostCacheConfigurationManager, HostEsxAgentHostManager, HostImageConfigManager, IscsiManager, StoragePod.
As you can see, the first 4 of them are related guest OS management. The VIX APIs is now integrated into vSphere API, meaning you no longer have limitation on programming languages as imposed by VIX. The GuestOperationsManager is the entry point which you can get from ServiceInstance. From there, you can get GuestAuthManager for authentication, GuestFileManager for guest file management including copying in and out, and GuestProcessManager for guest OS process management.
The latter 4 is closely related to HostSystem. You can get hold of these managed objects from a HostSystem object. HostCacheConfigurationManager provides access to performance tuning features of ESXi using solid state drive based cache. HostEsxAgentHostManager. HostEsxAgentHostManager “configures agent virtual machine resource configuration, such as what network and datastore to use for agent virtual machines.” HostImageConfigManager “configures ESXi software image, including properties such as acceptance level. It is currently designed to be host agent specific.” IscsiManager manages “mapping VMkernel NIC to iSCSI Host Bus Adapter.” (Note: I changed ESX to ESXi here.)
The last one “StoragePod” is a subtype of Folder that “aggregates the storage resources of associated Datastore objects into a single storage resource for use by virtual machines. The storage services such as Storage DRS (Distributed Resource Scheduling), enhance the utility of the storage pod.” StoragePod does not define any additional method but two properties.
New Methods to Existing Managed Object Types
There are 15 existing managed object types that have new methods. The following table from API reference lists all of them.
AuthorizationManager | HasPrivilegeOnEntity |
ClusterComputeResource | ClusterEnterMaintenanceMode |
Datastore | DatastoreEnterMaintenanceMode |
DatastoreExitMaintenanceMode | |
DistributedVirtualSwitch | AddNetworkResourcePool |
RemoveNetworkResourcePool | |
DistributedVirtualSwitchManager | RectifyDvsOnHost |
ExtensionManager | QueryManagedBy |
Folder | CreateStoragePod |
HostActiveDirectoryAuthentication | ImportCertificateForCAM |
JoinDomainWithCAM | |
HostFirewallSystem | UpdateRuleset |
HostProfileManager | CheckAnswerFileStatus |
ExportAnswerFile | |
QueryAnswerFileStatus | |
QueryProfileStructure | |
RetrieveAnswerFile | |
UpdateAnswerFile | |
HostStorageSystem | AttachScsiLun |
DetachScsiLun | |
DiscoverFcoeHbas | |
MarkForRemoval | |
MountVmfsVolume | |
UnmountVmfsVolume | |
Profile | RetrieveDescription |
SessionManager | AcquireGenericServiceTicket |
StorageResourceManager | ApplyStorageDrsRecommendation |
ApplyStorageDrsRecommendationToPod | |
CancelStorageDrsRecommendation | |
ConfigureStorageDrsForPod | |
RecommendDatastores | |
RefreshStorageDrsRecommendation | |
VirtualMachine | ConsolidateVMDisks |
EstimateStorageForConsolidateSnapshots |
New Managed Object Properties
Here is the least change with only one new property called “licensableResource” defined in HostSystem. The type for the new property is HostLicensableResourceInfo, which are essentially key/value pairs.
Changed Methods With Additional Parameters
There are 11 methods in 8 managed object types having additional parameters.
HostDatastoreSystem | QueryVmfsDatastoreCreateOptions |
HostProfileManager | ApplyHostConfig |
CreateDefaultProfile | |
QueryHostProfileMetadata | |
HostStorageSystem | ComputeDiskPartitionInfo |
ComputeDiskPartitionInfoForResize | |
HostSystem | ReconnectHost |
ProfileComplianceManager | QueryExpressionMetadata |
ProfileManager | QueryPolicyMetadata |
VirtualMachine | RemoveAllSnapshots |
VirtualMachineSnapshot | RemoveSnapshot |
As I mentioned in previous blog, vSphere Web Services APIs are wire compatible but not code compatible, meaning your existing application that use any of these 11 methods will need to change for upgrading to vSphere 5.0. The change may as simple as adding a null in place of the new parameters.
To help mitigate the compatibility issue, I’ve kept the old method and route it to the new method with null in place of the new parameters. So if you are using VIJava API, your code does not need to recompile at all.
New Data Objects
There are much more data object types than managed object types in vSphere API. Same is true for new data object type types and new managed object types. When we work with vSphere APIs, the most important part is the managed object types. The data object types are secondary.
Given the fact that there are too many data objects to cover and they are not so important, I will just leave them out in this article. You can always check out here for the information.
Hi Steve,
Thank you for this information.
I tried to search for ManagedEntities of type Datastore like below on vCenter5.0. Somehow I didn’t get any objects in return.
ManagedEntity[] datastores = new InventoryNavigator(rootFolder).searchManagedEntities(“Datastore”);
So, I went ahead getting it from HostSystem using hostSystemObj.getDatastores(); that works just fine.
Did anything else change that prevents searchManagedEntities from working for Datastore?
Regards,
Tulsi
Hi Tulsi,
Thanks for letting me know the issue. Are you using vijava 5.0 beta I posted yesterday? Thanks!
Steve
Hi Steve,
I was using the vijava 2.1 for that test. That could be the reason. I’ve started using the vijava 5.0 beta.
Thank you.
Regards,
Tulsi
Hi Steve,
It works fine on vijava 5.0 beta. I.e. the newer api returns the ManagedEntities while searching for Datastore or Network using searchManagedEntities method.
The earlier version didn’t work this way on vCenter5.0 did the class version or something change?
Thank you
Regards,
Tulsi
Hi Tulsi,
Thanks for your feedback. Could you file a bug in the project home http://vijava.sf.net? Thanks!
-Steve
Sure Steve.
Regards,
Tulsi
Hi Steve,
I created a Bug. The update is I couldn’t search for VirtualApp either.
Just a quick question is there an API to know the version of the vSphere that we are talking to?
Regards,
Tulsi
Oops. I’m able to search for VirtualApp.
Regards,
Tulsi
Hi Tulsi,
Check out the VerUtil.java in the API code:
http://vijava.svn.sourceforge.net/viewvc/vijava/trunk/src/com/vmware/vim25/mo/util/
Steve
Hi,
is it possible to configure autodeploy using the java sdk instead of powershell?
thanks!
Eric
Hi Eric,
Great question. I don’t know the answer and will try autodeploy later. In the meantime, if you find anythere, please let us know.
Thanks!
Steve
Hi Steve,
I am trying to create portgroup in vsphere 5.0. Please let me know the code changes need to be done in the DistributedVirtualSwicth.addPortGroup_task method…
Regards,
Udaya
Hi,
Is there anyway I can know the VIJAVA SDK version that a Application is using programmatically ?
thanks, krishna
Hi Krishna,
That is a good question. We don’t have it from the API itself. Any use case in which you have to have it?
BTW, if you meant for the version of the vSphere SDK version, it can be easily found out from the AboutInfo object.
Steve
Hello Steve,
Can you please post code snip to show how to differentiate a StoragePod from a Folder?
I am trying to use ‘instance of’ to identify a StoragePod. Here is the code snip-
ManagedEntity mes[] = parent.getChildEntity();
for (ManagedEntity m : mes) {
ManagedEntity mes[] = parent.getChildEntity();
for (ManagedEntity m : mes) {
if (m instanceof StoragePod) {
//execute storagepod related logic
}
}
Above code is not working for me though. Can you please tell me what am I missing?
Did you find StoragePod instance in the child property whichh is an array of ManagedEntity?
Steve