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 few commands exposed in the internal API. The most useful Internal API command is ConfigurationDeployEx2 which allows you to deploy to distributed virtual switches.

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 conecpt 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

• username

• password

• hostname

• organization

• workspace

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

• 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.

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

• Configuration ID - Use the GetConfigurationByName method to retrieve this if you do not know it.

• New workspace name - The name you want the new config in the workspace to be.

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

• Configuration ID - Use the GetConfigurationByName method to retrieve this if you do not know it.

• New workspace name - The name of the clone that is being created.

ConfigurationDelete

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

Arguments

• Configuration ID - Use the GetConfigurationByName method to retrieve this if you do not know it.

ConfigurationDeploy

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

Arguments

• Configuration ID - Use the GetConfigurationByName method to retrieve this if you do not know it.

• Fencemode - 1 = not fenced; 2 = block traffic in and out; 3 = allow out ; 4 allow in and out

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

• Configuration ID - Use the GetConfigurationByName method to retrieve this if you do not know it.

• Action - use a numerical value from the list above.

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

• Configuration ID - Use the GetConfigurationByName method to retrieve this if you do not know it.

• True or False (boolean) - Accepts true | false | 1 | 0

ConfigurationUndeploy

Undeploys a configuration in the Workspace. Nothing is returned.

Arguments

• Configuration ID - Use the GetConfigurationByName method to retrieve this if you do not know it.

GetConfiguration

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

Arguments

• Config ID

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

• Config Name

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

• Machine ID - Use GetMachineByName to retrieve this

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

• Configuration ID - Config where Guest VM lives

• Name of guest

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

• Configuration name

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

• configurationType (Configuration Type must be either 1 for Workspace or 2 for Library)

ListMachines

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

Arguments

• Configuration ID

LiveLink

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

Arguments

• config Name

MachinePerformAction

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

Arguments

• Machine ID

• Action (use numeral from list aboive)

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

• 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.

priv_ConfigurationArchiveEx

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

Arguments

• 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.

• libraryDescription

• isGoldMaster

• storageName

• storageLeaseInMilliseconds

Returns

ID on success. Fault object on fault.

priv_ConfigurationCaptureEx

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

Arguments

• 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.

• libraryDescription

• isGoldMaster

• storageName

• storageLeaseInMilliseconds

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

• configurationId

• newOwnerId

priv_ConfigurationCopy

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

Arguments

• sg_id

• name

• description

• Machines array

• storage location

priv_ConfigurationCloneToWorkspace

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

Arguments

• destWorkspaceId

• isNewConfiguration

• newConfigName

• description

• Machines array

• storage location

• existingConfigId

• isFullClone

• storageLeaseInMilliseconds

priv_ConfigurationCreateEx

Creates and empty configuration.

Arguments

• Name - The name of the configuration

• Description - The description of the configuration

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

• Configuration ID - Use the GetConfigurationByName method to retrieve this if you do not know it.

• Network ID

• Fencemode(string) - Choices: Nonfenced or FenceBlockInAndOut or FenceAllowOutOnly or FenceAllowInAndOut

priv_ConfigurationExport

Arguments

• configId

• uncPath

• username

• password

priv_ConfigurationGetNetworks

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

Arguments

• configID

• physical - true/false

This method returns an array of type Network.

priv_ConfigurationImport

Arguments

• UNCPath

• dirUsername

• dirPassword

• name

• description

• storageName

priv_ConfigurationMove

Arguments

• configIdToMove

• destinationWorkspaceId

• isNewConfiguration

• newConfigName

• newConfigDescription

• storageLeaseInMilliseconds

• existingConfigId

• vmIds

• deleteOriginalConfig

priv_GetAllWorkspaces

Arguments

NONE

Arguments

Returns an array of workspace objects.

priv_GetNetworkInfo

Returns the Network information for a specific VM.

Arguments

• vmID - VM id number

Returns

An array of Network references.

priv_GetObjectConditions

Arguments

• objectType - Integer representing the object type:

  VM = 1
  MANAGED_SERVER = 2
  RESOURCE_POOL = 3
  CONFIGURATION = 4

• objectID - Object id number

priv_GetOrganization

Arguments

• organizationId

Returns

Organization object

priv_GetOrganizations

Arguments

NONE

Arguments

Returns an array of organization refs.

priv_GetOrganizationByName

Arguments

• organizationName

priv_GetOrganizationWorkspaces

Arguments

• organizationId

Returns

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

priv_GetTemplate

Arguments

• template id

Returns

Template object.

priv_GetUser

Arguments

• userName

Returns

User object.

priv_GetWorkspaceByName

Arguments

• string

priv_LibraryCloneToWorkspace

• libraryId

• destWorkspaceId

• isNewConfiguration

• newConfigName

• description

• copyData

• existingConfigId

• isFullClone

• storageLeaseInMilliseconds

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

• machineId - machine id number

priv_NetworkInterfaceCreate

Arguments

• vmID - VM id number

• networkID

• IPAssignmentType

• IPAddress

priv_NetworkInterfaceDelete

• vmID - VM id number

• nicID

priv_NetworkInterfaceModify

Arguments

• vmID - VM id number

• info -

priv_StorageServerVMFSFindByName

• Storename

priv_TemplateChangeOwner

Changes the owner of the given template.

Arguments

• templateId

• newOwnerId

priv_TemplateExport

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

Arguments

• template_id

• UNCPath

• username

• password

priv_TemplateImport

Arguments

• UNCPath

• dirUsername

• dirPassword

• name

• description

• storageName

• parameterList

priv_TemplateImportFromSMB

Arguments

• UNCpath

• username

• password

• delete

• description

• destStore

• destName

• destDesc

priv_TemplatePerformAction

Arguments

• 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

priv_WorkspaceCreate

Arguments

• name

• isMain

• description

• storedVMQuota

• deployedVMQuota

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.

* 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.)

* 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.

* 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.

VERSION

Version: v1.8 (2010/09/13)

AUTHOR

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

CONTRIBUTIONS

Cameron Berkenpas <cberkenpas@paypal.com>

DEPENDENCIES

SOAP::Lite

LICENSE AND COPYRIGHT

Released under Perl Artistic License

SEE ALSO

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

VMWare Labmanager SOAP API Guide 
 http://www.vmware.com/pdf/lm40_soap_api_guide.pdf

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

cpanm VMware::API::LabManager

perl -MCPAN -e shell
install VMware::API::LabManager