What's New in the New vCenter Server Plug-In

|

vRealize Orchestrator vCenter Server Plug-In | 22 NOVEMBER 2016

The new vCenter Server plug-in provides a completely redesigned and rebuilt implementation for vRealize Orchestrator. The new plug-in contains 221 workflows and exposes 2300 scripting types and 23 types of inventory objects. The key changes of the plug-in include:

  • Connection to the vSphere Server
    The new vCenter Server plug-in uses VM Object Management Infrastructure Project Leveraged Server Infrastructure (VLSI) to make API calls to the vSphere Server. The plug-in uses Java stubs and SOAP calls to communicate with the vSphere Server instances.
  • Redesigned Cache
    A PropertyCollector keeps the cache updated and the Inventory Service is not used.
  • Monitoring and Troubleshooting
    The new vCenter Server plug-in provides a method for metrics monitoring through JMX. The monitored metrics are Guava Cache metrics and ManagedObject metrics.

NOTE: For vRealize Orchestrator 7.2, you can download the plug-in from the vRealize Orchestrator Product Download page.

Plug-In Versioning and Interoperability with vSphere

The new vCenter Server plug-in maintains the versioning convention based on the supported vSphere API version, in this case the version is 6.5.

The core functionality of the plug-in, such as connectivity and inventory, is compatible with vSphere 5.5 and later.

The version of the vSphere API that is exposed for the vCenter Server plug-in Scripting API is 6.5, which means that all API methods, properties and types that are introduced in vSphere 6.5, are available in the Orchestrator scripting content. In the new vCenter Server plug-in all methods and properties have a version tag in their description. The tag is visible in the VSO.xml configuration file and in the API explorer, for example @since vSphere API 5.5.

Design Changes

API Compatibility and Compatibility with the Existing Content

  1. Enums Handling

    The new vCenter Server plug-in changes the way the Scripting API interprets the enumetated types from the vSphere API. The enums are no longer wrapped but are exposed directly. In a JavaScript code, the following expressions are not valid anymore because the enum object maps to a string representation of an enumerated type.

    base_vm.summary.runtime.connectionState == VcVirtualMachineConnectionState.orphaned.value
    base_vm.summary.runtime.connectionState == VcVirtualMachineConnectionState.connected.value

    You must use the following expressions instead:

    base_vm.summary.runtime.connectionState == VcVirtualMachineConnectionState.orphaned
    base_vm.summary.runtime.connectionState.value == VcVirtualMachineConnectionState.connected.value
    base_vm.summary.runtime.connectionState.value == "connected"

    For compatibility reasons, the value property is preserved and the get and set methods invoke the name() method.

  2. Dunes Uri

    The format of the Dunes Uri is now different. If you have a virtual machine with an ID vm-23 and the URL of the vCenter Server is https://vCenter_Server_IP_address:443/sdk, then the Dunes Uri becomes:

    dunes://service.dunes.ch/CustomSDKObject?id='vCenter_Server_IP_address_or_DNS_name,id:vm-23'&dunesName='VC:VirtualMachine

    Compared to an Uri from an earlier version of the plug-in:

    dunes://service.dunes.ch/CustomSDKObject?id='https://vCenter_Server_IP_address:443/sdk/vm-23'&dunesName='VC:VirtualMachine

    The new vCenter Server plug-in can recognize both formats, so the second example is readable for the new plug-in. However, in case of downgrade, the IDs that are created with the new plug-in cannot be used by the old plug-in.

  3. VcPlugin.refreshObjects Method

    The VcPlugin.refreshObjects method is deprecated in the new vCenter Server plug-in. The method is preserved for scripting compatibility, but if you invoke this method, the returned result is the value passed to the method.

    The change of VcPlugin.refreshObjects method is because of the redesigned architecture of the plug-in caching schema.

  4. Implicit Preloading of Properties

    When fetching a managed entity, such as VirtualMachine, Datastore, Network, or other inventory objects, by using a finder or a scripting method of the VcPlugin or SdkConnection objects, the old plug-in preloads certain properties in cache. This type of implicit caching is deprecated and the new plug-in does not use an implicit preloading of properties.

    If you want to preload properties, you must do this explicitly through listing all required properties in the method calls of the VcPlugin or SdkConnection objects. For example:

    var properties = ["config", "summary"];
    var vms = sdkConnection.getAllVirtualMachines(properties, query);

  5. ManagedObjectReference Objects

    In the new vCenter Server plug-in, all managed property values, method parameters, and return values of the type ManagedObjectReference are implemented as stubs. The implemented types derive from the ManagedObject type. For example, the following command sets a snapshot to the VirtualMachineCloneSpecification:

    spec.snapshot = snapshot.reference;

    In the new vCenter Server plug-in, the properties snapshot and reference are no longer VcManagedObjectReference but are of the VcSnaphot type. Two changes derive from this implementation:

    • You must use the new moref property if you want to call a VcManagedObjectReference explicitly.
    • To maintain compatibility with VcManagedObjectReference, every ManagedObject scripting type implements a type property and the VcManagedObjectReference::value with a different name. The new name is id.
  6. Finders Might Return Non-Existing Objects

    It is possible that the new vCenter Server plug-in finder returns a non-existing object and not show an exception. The result that the finder returns is an object stub. If the stub represents a managed object that does not exist on the server, the vCenter Server plug-in returns the object but shows an exception when you call a finder method or access a finder property.

    The code in the following example behaves exactly as described because it uses a finder implicitly:

    Server.fromUri(someDunesUri);

    If the client code is expected to retrieve an object by additionally checking the presence of the object at the time the vSphere Server method is called, this code can use the following API method:

    • SdkConnection methods:
      • getAll... methods by providing a query for matching the required id. For example:

        var vms = sdkConnection.getAllVirtualMachines(null, "xpath:matches(id,'name')");

      • getAllVimManagedObjects method
      • getManagedObjects method
    • VcPlugin methods:
      • getAll... methods matching the corresponding SdkConnection methods
      • getAllVimManagedObjects
      • getManagedObjectsForIds
      • getManagedObjectsForTypesAndIds
  7. Scripting Objects Equality

    The new vCenter Server plug-in treats scripting objects in the scripting content differently regarding object equality. Using equality operators applied to two objects that represent the same model object, for example Vc:SdkConnection, might lead to incorrect results. Objects obtained through a plug-in factory method and objects returned from methods of other objects, are actually wrapper objects that are created in real time and they represent the same model object, for example SdkConnection. For this reason, equality check on these objects does not return the expected result, even if these objects represent the same model object.

    If vc is a Vc:SdkConnection object.

    var connections = [vc];
    System.log(connections.indexOf(vc)); // Returns 0.
    var loadedConnections = VcPlugin.allSdkConnections;
    System.log(loadedConnections.indexOf(vc)); // Returns -1.

    The second instance of the indexOf method fails to find an SdkConnection. The indexOf method uses a strict equality check (===) operator that does not return a False value because the the loadedConnections array contains a different object that represents the required SdkConnection object.

    To avoid an inconsistent behavior between the old vCenter Server plug-in and the new plug-in, you can rework the script to compare object properties that are relevant to the particular use case. The example below compares the connections objects based on the instanceUuid of the service.

    1 == attrVCs.filter(function (item) { return item.about.instanceUuid == vc.about.instanceUuid}).length

  8. Property Values of Findable Objects

    You can retrieve the managed values for properties of findable objects only by fetching them with every use.

    Example: If a script accesses the status of VMware Tools of a virtual machine, the system log prints the status as it was retrieved with the first line of code.

    var guest = vm.guest;
    // meanwhile do something
    System.log(guest.toolsStatus);

    To retrieve the current value of the VMware Tools status, you must use the following syntax:

    System.log(vm.guest.toolsStatus);

  9. InstanceOf Operator

    Folder objects that are returned by either plug-in factory methods or API scripting methods are instances of specific folder types, such as VcVmFolder, VcDatastoreFolder, VcDatacenterFolder, VcNetworkFolder or VcHostFolder. The specific type depends on the type of folder that the childType property of the managed object returns.

    The specific folder types have all methods and properties of the VcFolder type and can be used where a VcFolder type is expected, with one exception - the folder instanceOf VcFolder expression no longer works. You can rework the expression by using the specific folder types, for example:

    folder instanceOf VcVmFolder
    folder instanceOf VcHostFolder

  10. Non-Persistent Properties Changes

    Modifying the properties of an object that is retrieved by accessing managed properties is not persisted. For example,

    var guest = vm.guest;
    System.log(guest.toolsStatus); // Prints 'toolsOk'

    guest.toolsStatus = 'toolsNotRunning'
    System.log(guest.toolsStatus); // Prints 'toolsOk'

    The reason is that the vm.guest call retrieves the value of the managed property from the server or from the internal cache of the plug-in, if the property is cached.

Known Issues

  1. Plug-In Policies Support

    Currently the new vCenter Server plug-in does not support policies for events or managed entities.