VMware::API::LabManager - The VMware LabManager API
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::API::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();
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.
VMware ended support for Lab Manager on May 31, 2014.
Correspondingly, this module will likely see no further development.
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.
Need to add this example.
{ 'configID' => '97', 'status' => '0', 'OwnerFullName' => 'Jones, Bob', 'name' => 'VM0', 'description' => '', 'isDeployed' => 'false', 'memory' => '16', 'DatastoreNameResidesOn' => 'labmgr_01', 'id' => '116' }
{ 'isConnected' => 'true', 'macAddress' => '00:50:56:0a:00:aa', 'networkId' => '63', 'nicId' => '221', 'vmxSlot' => '0', 'ipAddressingMode' => 'DHCP', 'resetMac' => 'false' }
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' };
{ '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' },
{ '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' },
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.
These methods are not direct API calls. They represent the methods that create or module as a "wrapper" for the Labmanager API.
This method creates the Labmanager object.
Arguments
username
password
hostname
organization
workspace
$labman->config( debug => 1 );
Returns and clears the last error reported by SOAP service.
This methods provide a direct mapping to the public API calls for Labmanager.
This method captures a Workspace configuration and saves into the library.
Configuration ID - Use the GetConfigurationByName method to retrieve this if you do not know it.
New library name - The name that you want the captured config to be.
Returns
ID on success. Fault object on fault.
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.
New workspace name - The name you want the new config in the workspace to be.
This method clones a Workspace configuration, saves it in a storage server, and makes it visible in the Workspace under the new name. Arguements:
New workspace name - The name of the clone that is being created.
This method deletes a configuration from the Workspace. You cannot delete a deployed configuration. Doesn't return anything. Arguments:
This method allows you to deploy an undeployed configuration which resides in the Workspace.
Fencemode - 1 = not fenced; 2 = block traffic in and out; 3 = allow out ; 4 allow in and out
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.
Action - use a numerical value from the list above.
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.
True or False (boolean) - Accepts true | false | 1 | 0
Undeploys a configuration in the Workspace. Nothing is returned.
This method retruns a reference to a Configuration matching the configuration ID passed.
Config ID
A hashref to a configuration. Example keys: mustBeFenced, autoDeleteDateTime, bucketName, name, autoDeleteInMilliSeconds, description, isDeployed, fenceMode, id, type, isPublic, dateCreated
Config Name
An array of configurations matching this name. Example keys: mustBeFenced, autoDeleteDateTime, bucketName, name, autoDeleteInMilliSeconds, description, isDeployed, fenceMode, id, type, isPublic, dateCreated
This call takes the numeric identifier of a machine and returns its corresponding Machine object.
Machine ID - Use GetMachineByName to retrieve this
A hashref to a machine. Example elements: configID, macAddress, status, OwnerFullName, name, description, isDeployed, internalIP, memory, DatastoreNameResidesOn, id
This call takes a configuration identifier and a machine name and returns the matching Machine object.
Configuration ID - Config where Guest VM lives
Name of guest
This call takes a configuration name, searches for it in both the configuration library and workspace and returns its corresponding Configuration object.
Configuration name
A hashref to a configuration. Example elements: mustBeFenced, autoDeleteDateTime, bucketName (aka workspace), name, autoDeleteInMilliSeconds, description, isDeployed, fenceMode, id, type, isPublic, dateCreated
This method returns an array or arrayref of configuration objects for the current workspace or library.
It depends on configuration type requested.
configurationType (Configuration Type must be either 1 for Workspace or 2 for Library)
This method returns an array of type Machine. The method returns one Machine object for each virtual machine in a configuration.
Configuration ID
This method allows you to create a LiveLink URL to a library configuration. Responds with a livelink URL
config Name
This method performs one of the following machine actions as indicated by the action identifier:
1 Power on. Turns on a machine.
2 Power off. Turns off a machine. Nothing is saved.
3 Suspend. Freezes a machine CPU and state.
4 Resume. Resumes a suspended machine.
5 Reset. Reboots a machine.
6 Snapshot. Save a machine state at a specific point in time.
7 Revert. Returns a machine to a snapshot state.
8 Shutdown Guest. Shuts down a machine before turning off.
9 for Consolidate
10 for Eject CD
11 for Eject Floppy
12 for Deploy
13 for Undeploy
14 for Force Undeploy
Machine ID
Action (use numeral from list aboive)
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.
id - ID of the configuration.
template_id - ID of the template to be used.
name - The name for the virtual machine.
desc - Description for the virtual machine.
boot_seq - Boot sequence order (0 by default).
boot_delay - Boot delay (0 by default).
netInfo - Array of network information for the virtual machine.
libraryDescription
isGoldMaster
storageName
storageLeaseInMilliseconds
NB: API docs are wrong on this one. It accepts ConfigurationId and not ConfigurationID
Changes the owner of the given config.
configurationId
newOwnerId
This method copys a configuration to a new datastore. (Full clone)
sg_id
name
description
Machines array
storage location
destWorkspaceId
isNewConfiguration
newConfigName
existingConfigId
isFullClone
Creates and empty configuration.
Name - The name of the configuration
Description - The description of the configuration
ID of the configuration on success.
A fault object on fault.
This method allows you to deploy an undeployed configuration which resides in the Workspace to a Distributed Virtual Switch. Arguments:
Network ID
Fencemode(string) - Choices: Nonfenced or FenceBlockInAndOut or FenceAllowOutOnly or FenceAllowInAndOut
configId
uncPath
Returns an array of physical or virtual network IDs for the specified configuration.
configID
physical - true/false
This method returns an array of type Network.
UNCPath
dirUsername
dirPassword
configIdToMove
destinationWorkspaceId
newConfigDescription
vmIds
deleteOriginalConfig
Returns an array of workspace objects.
Returns the Network information for a specific VM.
vmID - VM id number
An array of Network references.
objectType - Integer representing the object type:
VM = 1 MANAGED_SERVER = 2 RESOURCE_POOL = 3 CONFIGURATION = 4
objectID - Object id number
organizationId
Organization object
Returns an array of organization refs.
organizationName
An array of Workspace objects that are in the given organizations.
template id
Template object.
userName
User object.
string
libraryId
copyData
This method returns an array of type Network. The method returns one Network object for each network configured.
This method returns an array of type TransportNetwork. The method returns one Network object for each network configured.
This method returns an array of type Users. The method returns one User object for each User imported into LabMan.
machineId - machine id number
networkID
IPAssignmentType
IPAddress
nicID
info -
Storename
Changes the owner of the given template.
templateId
Exports a template out to a UNC path for later import.
template_id
parameterList
UNCpath
delete
destStore
destName
destDesc
Template ID
Action
The action is a number representing any of the following:
1 for Deploy 2 for Undeploy in Discard State 3 for Delete 4 for Reset 5 for Make Shared 6 for Make Private 7 for Publish 8 for Unpublish 9 for Undeploy in Save State
isMain
storedVMQuota
deployedVMQuota
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.
This call does not currently build the correct Ethernet driver information.
If you get the following SOAP Error:
This is a known issue with LabManager 4.
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.
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:
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.)
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.)
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.
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.
Net::SSL SOAP::Lite
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
VMware::API::LabManager v2.12 (2023/09/18)
(c) 2004-2023, Phillip Pollard <bennie@cpan.org>
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
Phillip Pollard, <bennie@cpan.org> David F. Kinder, Jr, <dkinder@davidkinder.net>
John Barker, <john@johnrbarker.com> Cameron Berkenpas <cberkenpas@paypal.com>
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
To install VMware::API::LabManager, copy and paste the appropriate command in to your terminal.
cpanm
cpanm VMware::API::LabManager
CPAN shell
perl -MCPAN -e shell install VMware::API::LabManager
For more information on module installation, please visit the detailed CPAN module installation guide.