NAME

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

VERSION

$Revision: 1.1.1.1 $

SYNOPSIS

This module has been tested using Labmanger 4.0 (4.0.1.1233).

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

 	use VMware::API::LabManager;
 
	my $labman = VMware::API::LabManager->new('LM_Username','LM_Password','LM_Hostname','Organization_Name','WorkSpace_Name');

 	#Get the id of the config you are going to check out 
 	@lib_config_id = $labman->GetSingleConfigurationByName($libraryConfigName,"id");

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

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

	#Deploy the config to DVS
	$labman->priv_ConfigurationDeployEx2($checked_out_config_id,2); # 2 is the id of the network

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

 	#Delete the config
 	$labman->ConfigurationDelete($chkd_out_id);

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

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

getLastSOAPError

Returns 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: =over 8 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' =back 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 prints a list of attributes of a Configuration matching the configuration ID passed. It will return an array if you specify which attributes you would like to access

Arguments

• Config ID

Attributes

• 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

Attributes

• 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

• Attribute(s) (optional) - if left blank, prints out and returns an array of all attributes.

Attributes

• 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. Returns an array of attributes or one or more specified attributes.

Arguments

• Configuration name

• Attribute(s) (optional) - if left blank, prints out and returns an array of all attributes.

Attributes

• 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. Shuts down a machine before turning off.

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

priv_ConfigurationCopy

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

priv_ConfigurationImport

priv_GetObjectConditions

Arguments

• objectType - Integer representing the object type:

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

• objectID - Object id number

priv_GetNetworkInfo

Arguments

• vmID - VM id number

priv_GetWorkspaceByName

name string

priv_LibraryCloneToWorkspace

public int LibraryCloneToWorkspace( int libraryId, int destWorkspaceId, bool isNewConfiguration, string newConfigName, string description, VMCopyData[] copyData, int existingConfigId, bool isFullClone, long storageLeaseInMilliseconds );

priv_ListTemplates

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

priv_NetworkInterfaceCreate

Arguments

• vmID - VM id number

• networkID

• IPAssignmentType

• IPAddress

priv_NetworkInterfaceDelete

• vmID - VM id number

• nicID

priv_StorageServerVMFSFindByName

• Storename

priv_TemplateImportFromSMB

priv_TemplatePerformAction

priv_WorkspaceCreate

Arguments

• name

• isMain

• description

• storedVMQuota

• deployedVMQuota

AUTHOR

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

CONTRIBUTIONS

Cameron Berkenpas <cberkenpas@paypal.com>

DEPENDENCIES

SOAP::Lite

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