Phillip Pollard > VMware-API-LabManager > VMware::API::LabManager

Download:
VMware-API-LabManager-2.10.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 2.10   Source  

NAME ^

VMware::API::LabManager - The VMware LabManager API

SYNOPSIS ^

This module has been developed against VMware vCenter Lab Manager 4.0 (4.0.1.1233)

Code to checkout, deploy, undeploy and delete a configuration:

        use VMware::API::LabManager;

    my $labman = new VMware::LabManager ( $username, $password, $server, $orgname, $workspace );

        # Get the id of the config you are going to check out
        my $config = $labman->GetSingleConfigurationByName("myConfigName");

        # Checkout the config
        my $checked_out_config_id  = $labman->ConfigurationCheckout($lib_config_id[0],"NEW_WORKSPACE_NAME");

        # Deploy the config
        my $ret = $labman->ConfigurationDeploy($checked_out_config_id,4); # The 4 is for the fencemode

        # Undeploy the config
        my $ret = $labman->ConfigurationUndeploy($chkd_out_id);

        # Delete the config
        my $ret = $labman->ConfigurationDelete($chkd_out_id); # You really should be sure before doing this :)

        # Check for last SOAP error
    print $labman->getLastSOAPError();

DESCRIPTION ^

This module provides a Perl interface to VMware's Labmanager SOAP interface. It has a one-to-one mapping for most of the commands exposed in the external API as well as a many commands exposed in the internal API.

Using this module you can checkout, deploy, undeploy and delete configurations. You can also get lists of configurations and guest information as well.

Lab Manager is a product created by VMware that provides development and test teams with a virtual environment to deploy systems and networks of systems in a short period of a time.

RETURNED VALUES ^

Many of the methods return hash references or arrays of hash references that contain information about a specific "object" or concept on the Lab Manager server. This is a rough analog to the Managed Object Reference structure of the VIPERL SDK without the generic interface for retireval.

Below are some of the commoned return value types and example values.

Config

  Need to add this example.

Machine

          {
            'configID' => '97',
            'status' => '0',
            'OwnerFullName' => 'Jones, Bob',
            'name' => 'VM0',
            'description' => '',
            'isDeployed' => 'false',
            'memory' => '16',
            'DatastoreNameResidesOn' => 'labmgr_01',
            'id' => '116'
          }

Network Interface (NIC)

          {
            'isConnected' => 'true',
            'macAddress' => '00:50:56:0a:00:aa',
            'networkId' => '63',
            'nicId' => '221',
            'vmxSlot' => '0',
            'ipAddressingMode' => 'DHCP',
            'resetMac' => 'false'
          }

Organization

  Need to add this example.

Workspace

The following represents a workspace called "Main" that has no configurations or resource pools.

          {
            'Configurations' => '',
            'Id' => '8',
            'ResourcePools' => '',
            'BucketType' => '3',
            'StoredVMQuota' => '0',
            'DeployedVMQuota' => '0',
            'Name' => 'Main',
            'Description' => '',
            'IsEnabled' => 'false'
          };

When a workspace is associated with a given resource pool or contains a configuration, references to those objects are returned as well.

NB: If only a single configuration or resource pool is returned, it is a direct hash reference, as below. Otherwise, if there are multiple, an arrayref of hash references will be present in that location.

          {
            'Configurations' => {
                                'Configuration' => {
                                                   'owner' => 'bjones',
                                                   'mustBeFenced' => 'NotSpecified',
                                                   'autoDeleteDateTime' => '9999-12-31T23:59:59.9999999',
                                                   'bucketName' => 'Main',
                                                   'name' => 'migration-test02',
                                                   'autoDeleteInMilliSeconds' => '0',
                                                   'description' => '',
                                                   'isDeployed' => 'false',
                                                   'fenceMode' => '0',
                                                   'id' => '95',
                                                   'type' => '1',
                                                   'isPublic' => 'false',
                                                   'dateCreated' => '2010-08-24T14:22:25.437'
                                                 }
                              },
            'Id' => '10',
            'ResourcePools' => {
                               'ResourcePool' => {
                                                 'ID' => '1',
                                                 'isBlackListed' => 'false',
                                                 'name' => 'DevPool1',
                                                 'rpValRefFullID' => 'resgroup-2411',
                                                 'path' => 'DC2/LAB-MGR/PAI',
                                                 'description' => '',
                                                 'isEnabled' => 'true',
                                                 'rpValRefShortID' => 'resgroup-2411'
                                               }
                             },
            'BucketType' => '3',
            'StoredVMQuota' => '0',
            'DeployedVMQuota' => '0',
            'Name' => 'Main',
            'Description' => '',
            'IsEnabled' => 'true'
          };

Network

          {
            'VlanID' => '583',
            'IsAddressingModeLocked' => 'false',
            'NetType' => 'Template',
            'IsPhysical' => 'true',
            'DnsSuffix' => '',
            'parentNetId' => '0',
            'Netmask' => '',
            'NetworkValref' => 'LM-DHCP-4LM10',
            'IsDeployFencedLocked' => 'true',
            'Gateway' => '',
            'IsNone' => 'false',
            'userId' => '0',
            'Dns2' => '',
            'DeployFencedMode' => 'Nonfenced',
            'Dns1' => '',
            'NetID' => '4',
            'DeployFenced' => 'false',
            'IPAddressingMode' => 'DHCP',
            'Description' => 'dhcp IP Pool',
            'Name' => 'LM-DHCP'
          },

User

          {
            'is_enabled' => 'true',
            'email_address' => 'bjones@company.com',
            'userId' => '3',
            'name' => 'bjones',
            'cache_mode' => '0',
            'full_name' => 'Jones, Bob',
            'fence_mode' => '0',
            'is_ldap' => 'true',
            'is_admin' => 'true',
            'stored_vm_quota' => '0',
            'deployed_vm_quota' => '0'
          },

EXAMPLE SCRIPTS ^

Included in the distribution of this module are several example scripts. Hopefully they provide an example of the usage of the Lab Manager API. All scripts have their own POD and accept command line parameters in a similar way to the VIPERL SDK utilities and vghetto scripts.

    conditions.pl - An example displaying an objects conditions.
    delete-all.pl - Deletes every template and configuration in a given LabMan installation
    hwupgrade.pl - Performs an upgrade on the virtual hardware of the specified configuration
    list-machines.pl - Lists all machines within the specified configuration
    list-networks.pl - Lists all the networks available to the specified user.
    list-organization.pl - Lists all the organizations available to the specified user.
    list-templates.pl - Lists all the template objects available to the specified user.
    list-users.pl - Lists all information on users in the Lab Manager system.
    list-workspaces.pl - Lists all the workspaces available to the specified user.
    move.pl - An example script of moving a config between workspaces.

PERL MODULE METHODS ^

These methods are not direct API calls. They represent the methods that create or module as a "wrapper" for the Labmanager API.

new

This method creates the Labmanager object.

Arguments

config

  $labman->config( debug => 1 );
debug - 1 to turn on debugging. 0 for none. Defaults to 0.
die_on_fault - 1 to cause the program to die verbosely on a soap fault. 0 for the fault object to be returned on the call and for die() to not be called. Defaults to 1. If you choose not to die_on_fault (for example, if you are writing a CGI) you will want to check all return objects to see if they are fault objects or not.
ssl_timeout - seconds to wait for timeout. Defaults to 3600. (1hr) This is how long a transaction response will be waited for once submitted. For slow storage systems and full clones, you may want to up this higher. If you find yourself setting this to more than 6 hours, your Lab Manager setup is probably not in the best shape.
hostname, orgname, workspace, username and password - All of these values can be changed from the original settings on new(). This is handing for performing multiple transactions across organizations.

getLastSOAPError

Returns and clears the last error reported by SOAP service.

PUBLIC API METHODS ^

This methods provide a direct mapping to the public API calls for Labmanager.

ConfigurationCapture

This method captures a Workspace configuration and saves into the library.

Arguments

Returns

ID on success. Fault object on fault.

ConfigurationCheckout

This method checks out a configuration from the configuration library and moves it to the Workspace under a different name. It returns the ID of the checked out configuration in the WorkSpace.

WARNING: If you get the following SOAP Error:

Expecting single row, got multiple rows for: SELECT * FROM BucketWithParent WHERE name = N'Main' ---> Expecting single row, got multiple rows for: SELECT * FROM BucketWithParent WHERE name = N'Main'

This is because there are multiple workspaces named "Main", in different organizations. Apparently this API call doesn't limit the check for workspace name against the organization you authenticated with.

A workaround is to make sure you use this call on a uniquely name workspace or to use a private call (such as priv_LibraryCloneToWorkspace) instead.

Arguments

ConfigurationClone

This method clones a Workspace configuration, saves it in a storage server, and makes it visible in the Workspace under the new name. Arguements:

Arguments

ConfigurationDelete

This method deletes a configuration from the Workspace. You cannot delete a deployed configuration. Doesn't return anything. Arguments:

Arguments

ConfigurationDeploy

This method allows you to deploy an undeployed configuration which resides in the Workspace.

Arguments

ConfigurationPerformAction

This method performs one of the following configuration actions as indicated by the action identifier:

  1 : Power On. Turns on a configuration.
  2 : Power Off. Turns off a configuration. Nothing is saved.
  3 : Suspend. Freezes the CPU and state of a configuration.
  4 : Resume. Resumes a suspended configuration.
  5 : Reset. Reboots a configuration.
  6 : Snapshot. Saves a configuration state at a specific point in time.

Arguments

ConfigurationSetPublicPrivate

Use this call to set the state of a configuration to public or private. If the configuration state is public, others are able to access this configuration. If the configuration is private, only its owner can view it.

Arguments

ConfigurationUndeploy

Undeploys a configuration in the Workspace. Nothing is returned.

Arguments

GetConfiguration

This method retruns a reference to a Configuration matching the configuration ID passed.

Arguments

Returns

A hashref to a configuration. Example keys: mustBeFenced, autoDeleteDateTime, bucketName, name, autoDeleteInMilliSeconds, description, isDeployed, fenceMode, id, type, isPublic, dateCreated

GetConfigurationByName

This method retruns a reference to a Configuration matching the configuration ID passed.

Arguments

Returns

An array of configurations matching this name. Example keys: mustBeFenced, autoDeleteDateTime, bucketName, name, autoDeleteInMilliSeconds, description, isDeployed, fenceMode, id, type, isPublic, dateCreated

GetMachine

This call takes the numeric identifier of a machine and returns its corresponding Machine object.

Arguments

Returns

A hashref to a machine. Example elements: configID, macAddress, status, OwnerFullName, name, description, isDeployed, internalIP, memory, DatastoreNameResidesOn, id

GetMachineByName

This call takes a configuration identifier and a machine name and returns the matching Machine object.

Arguments

Returns

A hashref to a machine. Example elements: configID, macAddress, status, OwnerFullName, name, description, isDeployed, internalIP, memory, DatastoreNameResidesOn, id

GetSingleConfigurationByName

This call takes a configuration name, searches for it in both the configuration library and workspace and returns its corresponding Configuration object.

Arguments

Returns

A hashref to a configuration. Example elements: mustBeFenced, autoDeleteDateTime, bucketName (aka workspace), name, autoDeleteInMilliSeconds, description, isDeployed, fenceMode, id, type, isPublic, dateCreated

ListConfigurations($type)

This method returns an array or arrayref of configuration objects for the current workspace or library.

It depends on configuration type requested.

Arguments

ListMachines

This method returns an array of type Machine. The method returns one Machine object for each virtual machine in a configuration.

Arguments

LiveLink

This method allows you to create a LiveLink URL to a library configuration. Responds with a livelink URL

Arguments

MachinePerformAction

This method performs one of the following machine actions as indicated by the action identifier:

Arguments

INTERNAL API METHODS ^

This methods provide a direct mapping to internal API calls for Labmanager. These calls are not publically supported by VMware and may change between releases of the Labmanager product.

priv_ConfigurationAddMachineEx

Arguments

priv_ConfigurationArchiveEx

This method captures a Workspace configuration and saves into the library.

Arguments

Returns

ID on success. Fault object on fault.

priv_ConfigurationCaptureEx

This method captures a Workspace configuration and saves into the library.

Arguments

Returns

ID on success. Fault object on fault.

NB: API docs are wrong on this one. It accepts ConfigurationId and not ConfigurationID

priv_ConfigurationChangeOwner

Changes the owner of the given config.

Arguments

priv_ConfigurationCopy

This method copys a configuration to a new datastore. (Full clone)

Arguments

priv_ConfigurationCloneToWorkspace

This method copys a configuration to a new datastore. (Full clone)

Arguments

priv_ConfigurationCreateEx

Creates and empty configuration.

Arguments

Returns

ID of the configuration on success.

A fault object on fault.

priv_ConfigurationDeployEx2

This method allows you to deploy an undeployed configuration which resides in the Workspace to a Distributed Virtual Switch. Arguments:

Arguments

priv_ConfigurationExport

Arguments

priv_ConfigurationGetNetworks

Returns an array of physical or virtual network IDs for the specified configuration.

Arguments

This method returns an array of type Network.

priv_ConfigurationImport

Arguments

priv_ConfigurationMove

Arguments

priv_GetAllWorkspaces

Arguments

NONE

Arguments

Returns an array of workspace objects.

priv_GetNetworkInfo

Returns the Network information for a specific VM.

Arguments

Returns

An array of Network references.

priv_GetObjectConditions

Arguments

priv_GetOrganization

Arguments

Returns

Organization object

priv_GetOrganizations

Arguments

NONE

Arguments

Returns an array of organization refs.

priv_GetOrganizationByName

Arguments

priv_GetOrganizationWorkspaces

Arguments

Returns

An array of Workspace objects that are in the given organizations.

priv_GetTemplate

Arguments

Returns

Template object.

priv_GetUser

Arguments

Returns

User object.

priv_GetWorkspaceByName

Arguments

priv_LibraryCloneToWorkspace

priv_ListNetworks

This method returns an array of type Network. The method returns one Network object for each network configured.

priv_ListTemplates

This method returns an array of type Machine. The method returns one Machine object for each virtual machine in a configuration.

priv_ListTransportNetworksInCurrentOrg

This method returns an array of type TransportNetwork. The method returns one Network object for each network configured.

priv_ListUsers

This method returns an array of type Users. The method returns one User object for each User imported into LabMan.

priv_MachineUpgradeVirtualHardware

Arguments

priv_NetworkInterfaceCreate

Arguments

priv_NetworkInterfaceDelete

priv_NetworkInterfaceModify

Arguments

priv_StorageServerVMFSFindByName

priv_TemplateChangeOwner

Changes the owner of the given template.

Arguments

priv_TemplateExport

Exports a template out to a UNC path for later import.

Arguments

priv_TemplateImport

Arguments

priv_TemplateImportFromSMB

Arguments

priv_TemplatePerformAction

Arguments

priv_WorkspaceCreate

Arguments

BUGS AND LIMITATIONS ^

Authentication and latentcy

The API is designed by VMware to require an authentication header with every SOAP action. This means that you are re-autneticated on each action you perform. As stated in the VMware Lab Manager SOAP API Guide v2.4, pg 13:

  Client applications must provide valid credentials - a Lab Manager user account
  and password - with each Lab Manager Web service method call. The user account
  must have Administrator privileges on the Lab Manager Server. The Lab Manager
  Server authenticates these credentials.

If your Lab Manager is configured for remote authentication and is slow to log-in, this means you will see a performance drop in the speed of this API. Every method call on this module (a method call in this module representing an API SOAP method call) will take the same amount of time it takes you to initially log into the Lab Manager interface plus the actual processing time of the action.

This is complicated by a known issue that some complex API calls will internally perform several actions in Lab Manager, and you might pay that authentication call 4 or 5 times as the action processes. This known issue, is slated to be resolved on the next major release of Lab Manager.

The web interface to Lab Manager allows you to cache credentials after initial login. The web API does not. (See above quote.) You will pay for authentication time on all API calls.

One potential workaround is to use a local user account for API actions. Local accounts can be created and co-exist while remote (LDAP/AD) authentication is used. Local user accounts authenticate much quicker than other forms.

priv_ConfigurationAddMachineEx()

This call does not currently build the correct Ethernet driver information.

ConfigurationCheckout() API errors.

If you get the following SOAP Error:

Expecting single row, got multiple rows for: SELECT * FROM BucketWithParent WHERE name = N'Main' ---> Expecting single row, got multiple rows for: SELECT * FROM BucketWithParent WHERE name = N'Main'

This is because there are multiple workspaces named "Main", in different organizations. Apparently this API call doesn't limit the check for workspace name against the organization you authenticated with.

A workaround is to make sure you use this call on a uniquely name workspace or to use a private call (such as priv_LibraryCloneToWorkspace) instead.

This is a known issue with LabManager 4.

priv_ConfigurationCaptureEx()

The API documents for these calls have a typo. The parameter accepted by the SOAP call is ConfigurationId and not ConfigurationID. Reviewing the WSDL shows the correct parameters accepted by ther server.

CONFUSING ERROR CODES ^

By design, the textual error codes presented by this module are directly passed from Lab Manager. They are not generated by this library.

That being said, sometimes Lab Manager does not provide the clearest error description. Hopefully the following hints can help you save time when debugging:

"The configuration you were looking at is no longer accessible."

This means that the config ID you used references a non-existant configuration. This is commonly caused by a mistake in what ID you are using on a given call. (A machine id accidentally used in place of a config id, etc.)

"Server was unable to read the request. There is an error in XML document."

This bit of engrish most commonly crops up when the wrong data type is used as a parameter in a call. A good example is using a configuration name when a configuration ID is expected. (String vs Int causing the server to refuse the XML document.)

"Object reference not set to an instance of an object."

This lovely gem usually pops up when a required parameter is missing in a given SOAP call. This probably reflects a typo or capitalization error in the underlying wrapper call. (AKA: A mistake that I made.) Let me know if you figure out what is up. As is referenced in the BUGS AND LIMITATIONS section, the documentation for the API is incorrect in some places. The WSDL on the server is considered authorative and I'd check that first for resolution.

WISH LIST ^

If someone from VMware is reading this, and has control of the API, I would dearly love a few changes, that might help things:

* A way to submit multiple actions, or to cache credentials for speed. See "Authentication and latentcy" under the BUGS section.

* A way to look up a VM's vsphere name. This information is displayed in the UI but is unavailable in the API.

* Originating template for a VM. This information is displayed in the UI but is unavailable in the API.

* The template object should reference "owner" and not "ownerFullName." All ownership in the rest of the API is associated with the username, which is unique. To figure out who owns a template you have to crosswalk the full name back to username and the full name is not guarenteed to be unique.

* The template object should list the organization it is based in. Short of doing a list of all templates in each organization and diffing them, there is no quick way to determine if a template belongs only to this group, or is global and shared. (Oh, and if you do diff them for that information, a template in global shared to only one organization looks exactly the same as a template that exists only in one organization. So it's not a foolproof workaround.)

* LabManagerInternal.UserPerformAction()

It would be really nice if there was an list of what the action's this method accepts. An anonymous friend in VMware did an opengrok search for me and found these possible values in use for this call:

  1 == Enable, 2 == Disable, 3 == Delete.

Official confirmation or documentation would be very helpful.

* Consistent naming and capitalization.

  UNCPath vs uncPath
  userName vs username
  configurationId vs configurationID
  templateId vs template_id

* A way to look at the underlying ID numbers for items in the Lab Manager UI.

Boy would this make my life easier to debug issues quickly.

DEPENDENCIES ^

  Net::SSL
  SOAP::Lite

BUGS AND SOURCE ^

        Bug tracking for this module: https://rt.cpan.org/Dist/Display.html?Name=VMware-API-LabManager

        Source hosting: http://www.github.com/bennie/perl-VMware-API-LabManager

VERSION ^

        VMware::API::LabManager v2.10 (2014/04/30)

COPYRIGHT ^

    (c) 2004-2014, Phillip Pollard <bennie@cpan.org>

LICENSE ^

This source code is released under the "Perl Artistic License 2.0," the text of which is included in the LICENSE file of this distribution. It may also be reviewed here: http://opensource.org/licenses/artistic-license-2.0

AUTHORSHIP ^

  Phillip Pollard, <bennie@cpan.org>
  David F. Kinder, Jr, <dkinder@davidkinder.net>

CONTRIBUTIONS ^

  John Barker, <john@johnrbarker.com>
  Cameron Berkenpas <cberkenpas@paypal.com>

SEE ALSO ^

 VMware Labmanger
  http://www.vmware.com/products/labmanager/

 VMware Labmanager SOAP API Guide (External API)
  http://www.vmware.com/pdf/lm40_soap_api_guide.pdf

 VMware Labmanager 4.0 Internal API documentation
  http://communities.vmware.com/docs/DOC-10608

 VMware Lab Manager: Automated Reconfiguration of Transiently Used Infrastructure
  http://www.vmware.com/files/pdf/lm_whitepaper.pdf
syntax highlighting: