VMware::vCloud - VMware vCloud Director
my $vcd = new VMware::vCloud ( $hostname, $username, $password, $orgname, { debug => 1 } ); my %vapps = $vcd->list_vapps(); my $vappid = $vapps{'My Personal vApp'}; my $vapp = $vcd->get_vapp($vappid); my $ret = $vapp->power_on();
This module provides a Perl interface to VMware's vCloud Director.
It's intention is to provide a high-level perl-style interface to vCloud Director actions.
If you are looking for a direct and low-level access to the vCloud API, you may want to look at VMware::API::vCloud, which is packaged and used by this module.
VMware marked vCloud Director as "End of Availability" on March 12, 2015. (This was as part of vCloud Suite 6. The standalone vCloud Director was EOA in September 2013.)
Correspondingly, this module will likely see no further development.
This fork is incompatible with original VMware::vCloud, as it uses only "id" as the XML key to convert its data tree into a perl hash. Not the implicit set of "name, key, id" (in that order). Name may not be unique and returned datasets can contain overwritten data when used. Due to this change, many API call wrappers will fail, without prior adjusting to either work with "id" identifier, or handling received ARRAYREF instead of HASHREF (in case of missing "id", no associative array is created).
If you wish to avoid this compatibility change, use release 2.402
Included in the distribution of this module are several example scripts. Hopefully they provide an illustrative example of the use of vCloud Director. All scripts have their own POD and accept command line parameters in a similar way to the VIPERL SDK utilities and vghetto scripts.
login.pl - An example script that demonstrates logging in to the server. org_get.pl - Selects a random organization and prints a Data::Dumper dump of it's information. list-vapps.pl - Prints a list of all VMs the user has access to.
This method instances the VMware::vCloud object and verifies the user can log onto the server.
$host, $user, and $pass are required. They should contain the login information for the vCloud server.
$org and $conf are optional.
$org is the vCloud Organization to connect to. If $org is not given, the default of 'System' is used.
$conf is an optional hasref containing tuneable parameters:
* debug - set to a true value to turn on STDERR debugging statements.
This turns debugging on and off programatically. An argument of '1' for debugging, '0' for no debugging.
This method is deprecated and will be removed in later releases.
This method roughly emulates the default login action of the API: It returns information on which organizations are accessible to the user.
It is a synonym for list_orgs() and all details on return values should be take from that method's documentation.
This method clears the in-module caching of API responses.
This module caches many API calls to reduce response times and load on the server. This cache is automatically cleared when a method that changes the status of the VCD server is called. However, there may be times when you have a lon running process, or wish to manually clear the cache yourself.
Given a name, VDC, template and network, instantiate the template with the given settings and other defaults.
Details of the create task will be returned.
Create a vApp from varied sources
Given the org HREF, call a delete on it.
Given an vApp id, it returns a vApp object for that vApp.
See the documentation on VMware::vCloud::vApp for full details on this object type.
This method returns a hash or hashref of Template names and IDs the user has access too.
Given an organization id, it returns a hash of data for that organization.
This method creates a new, empty catalog in the given organization.
$conf is a hashref that can contain:
name
description
is_published
Org HREF example: http://example.vcd.server/api/admin/org/{id}
Given the org network HREF, call a delete on it.
Given a Org href, call the disable action on it.
Given a Org href, call the enable action on it.
Given an organization id, it returns a hash or hashref of data for that organization. Returned data:
name - Name of the organization description - Description field of the organization href - anchor HREF for the organization in the API id - UUID identified in the href. contains - A hashref of contained objects catalogs = references to the catalogs within the org vdcs - references to the org VDCs within the org raw - The raw returned XML structure for the organization from the API
This method returns a hash or hashref of Organization names and IDs.
Given the org VDC HREF, call a delete on it.
Given a VDC href, call the disable action on it.
Given a VDC href, call the enable action on it.
Given an VDC href, it returns a hash of data for that vDC.
This method returns a hash or hashref of VDC names and IDs the user has access too.
The optional argument of an $orgname will limit the returned list of VDCs in that Organization.
Returns a hashref of the information on the PVDC
Returns a hashref of the information on available PVDCs
Create an org network
The conf hash reference can contain:
desc
gateway
netmask
dns1
dns2
dnssuffix
is_enabled
is_shared
start_ip
end_ip
This method returns a hash or hashref of network names and IDs.
Given an optional VDCid it will return only the networks available in that VDC.
Returns a hash or hashref of the given task.
Contents include: (but aren't limited to)
* href * operation * expiryTime * startTime * Progress * operationName * operation * status
my ($percent,$status) = $vcd->progress_of_task($task_href)
Returns the approximate percentage of completion of the task as an integer between 1 and 101.
The text status of the task is returned as well:
* queued - The task has been queued for execution. * preRunning - The task is awaiting preprocessing or administrative action. * running - The task is running. * success - The task completed with a status of success. * error - The task encountered an error while running. * cancelled - The task was canceled by the owner or an administrator. * aborted - The task was aborted by an administrative action.
Given a task href, this method will query the task every second, and only return once the task is completed.
Specifically, this method will block and continue to query the task while it has any of the following statuses:
* queued - The task has been queued for execution. * preRunning - The task is awaiting preprocessing or administrative action. * running - The task is running.
Any of the following statuses will cause this method to return:
* success - The task completed with a status of success. * error - The task encountered an error while running. * cancelled - The task was canceled by the owner or an administrator. * aborted - The task was aborted by an administrative action.
The return value will be and array or arrayref composed of two elements:
* The status code returned by the server * A hashref comprising the most recently retrived for of the task object. IE: the same output as get_task()
Returns the list of administrative action URLs available to the user.
Returns the data structure for the admin extensions available.
Requires using a sysadmin account and attaching to the System org.
Returns a hash(ref) of datastore information.
Returns a hash or hasref of all available external networks.
Returns a hash or hashref of available portgroups on the first associated vcenter server.
Returns a reference to the first associated vcenter server.
Give the vimserver type and managed object reference, this method returns the URL for viewing the object via the vSphere Web client. This is handy for finding further details on objects within vSphere.
Tl;DR - Use HREFs and not IDs.
Internally, objects are identified in the vCloud Director API via either an UUID or a HREF that references that object.
According to the API documentation, (as of 5.1) UUIDs are not guaranteed to always be consistent between connections, but HREFs are considered permanent.
Consequently, it is considered a best practice to use HREFs as the unique identifier of an object. This module implements this best practice.
Cache::Bounded VMware::API::vCloud
Bug tracking for this module: https://rt.cpan.org/Public/Dist/Display.html?Name=VMware-vCloud Source hosting: http://www.github.com/bennie/perl-VMware-vCloud
VMware::vCloud v2.404 (2023/09/14)
(c) 2011-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>
A strong thanks to all people who have helped me with direction, ideas, patches and other such items.
Dave Gress, <dgress@vmware.com> - Handling org admin issues and metadata Stuart Johnston, <sjohnston@cpan.org> - authentication and XML on API v1.0
To install VMware::vCloud, copy and paste the appropriate command in to your terminal.
cpanm
cpanm VMware::vCloud
CPAN shell
perl -MCPAN -e shell install VMware::vCloud
For more information on module installation, please visit the detailed CPAN module installation guide.