/ 
VMware-API-LabManager-1.2
River stage zero No dependents
/ VMware::API::LabManager

NAME

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

VERSION

$Revision: 1.2 $

SYNOPSIS

This module has been developed agains 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.

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:

    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

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

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

Arguments

  • UNCPath

  • dirUsername

  • dirPassword

  • name

  • description

  • storageName

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

Arguments

  • string

priv_LibraryCloneToWorkspace

  • libraryId

  • destWorkspaceId

  • isNewConfiguration

  • newConfigName

  • description

  • copyData

  • existingConfigId

  • isFullClone

  • 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

Arguments

  • UNCpath

  • username

  • password

  • delete

  • description

  • destStore

  • destName

  • destDesc

priv_TemplatePerformAction

Arguments

  • Template ID

  • Action

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

1 POD Error

The following errors were encountered while parsing the POD:

Around line 426:

Non-ASCII character seen before =encoding in 'public”'. Assuming UTF-8