/ 
VMware-vCloud-2.404
River stage zero No dependents
/ VMware::API::vCloud

NAME

VMware::API::vCloud - The VMware vCloud API

SYNOPSIS

my $api = new VMware::API::vCloud (
  $hostname, $username, $password, $orgname
);

my $raw_login_data = $vcd->login;

DESCRIPTION

This module provides a bare interface to VMware's vCloud REST API.

VMware::vCloud is designed for high level usage with vCloud Director. This module, however, provides a more low-level access to the REST interface.

Responses received from vCloud are in XML. They are translated via XML::Simple with ForceArray set for consistency in nesting. This is the object returned.

Aside from the translation of XML into a perl data structure, no further alteration is performed on the data.

HTTP errors are automatically parsed and die() is called. If you need to perform a dangerous action, do so in an eval block and evaluate $@.

OBJECT METHODS

These methods are not API calls. They represent the methods that create this module as a "wrapper" for the vCloud API.

new()

This method creates the vCloud object.

Arguments

  • hostname

  • username

  • password

  • organization

config()

$vcd->config( debug => 1 );
debug
0 for no debugging.
1 to turn on basic debug messages. 
2 to display learned variables on exit.
3 to show all XML transactions.
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 vCloud setup is probably not in the best shape.
hostname, orgname, 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.

REST METHODS

These are direct access to the REST web methods.

delete($url)

Performs a DELETE action on the given URL, and returns the parsed XML response.

get($url)

Performs a GET action on the given URL, and returns the parsed XML response.

get_raw($url)

Performs a GET action on the given URL, and returns the unparsed HTTP::Request object.

post($url,$type,$content)

Performs a POST action on the given URL, and returns the parsed XML response.

The optional value for $type is set as the Content Type for the transaction.

The optional value for $content is used as the content of the post.

put($url,$type,$content)

Performs a PUT action on the given URL, and returns the parsed XML response.

The optional value for $type is set as the Content Type for the transaction.

The optional value for $content is used as the content of the post.

API SHORTHAND METHODS

api_version

* Relative URL: /api/versions

This call queries the server for the current version of the API supported. It is implicitly called when library is instanced.

login

* Relative URL: dynamic, but usually: /login/

This call takes the username and password provided in the config() and creates an authentication token from the server. If successful, it returns the login data returned by the server.

In the 5.1 version of the API, this is a list of several access URLs.

logout()

Removes the current login session on the server.

admin()

* Relative URL: dynamic admin URL, usually /api/admin/

Parses the admin API URL to build and return a hash reference of key URLs for the API.

admin_extension_get()

* Relative URL: dynamic admin URL followed by "/extension"

admin_extension_vimServer_get()

admin_extension_vimServerReferences_get()

catalog_create($org_href,$conf)

$conf is a hashref that can contain:

  • name

  • description

  • is_published

Org HREF example: http://example.vcd.server/api/admin/org/{id}

catalog_get($catid or $caturl)

As a parameter, this method thakes the raw numeric id of the catalog or the full URL detailed for the catalog from the login catalog.

It returns the requested catalog.

catalog_get_access($cat_href,$org_href)

HREF example: http://example.vcd.server/api/org/{id}/catalog/{catalogId}/action/controlAccess

catalog_set_access($cat_href,$org_href,$is_shared,$level)

The sets the "organizational" sharing for a catalog.

  • is_shared - 1 or 0

  • level - one of: FullControl, Change, ReadOnly

HREF example: http://example.vcd.server/api/org/{id}/catalog/{catalogId}/action/controlAccess

datastore_list()

Connect to the System group for this query to work.

Returns a hash(ref) or datastore information.

org_create($name,$desc,$fullname,$is_enabled)

Create an organization.

  • name

  • desc

  • fullname

  • is_enabled

  • can_publish

  • deployed

  • stored

  • ldap_mode: NONE, SYSTEM or CUSTOM - Custom requires further parameters not implemented yet. Default is NONE

org_get($orgid or $orgurl)

As a parameter, this method takes the raw numeric id of the organization or the full URL detailed for the organization from the login catalog.

It returns the requested organization.

org_list()

Returns the full list of available organizations.

org_network_create($url,$conf)

Create an org network

The conf hash reference can contain:

  • name

  • desc

  • gateway

  • netmask

  • dns1

  • dns2

  • dnssuffix

  • is_enabled

  • is_shared

  • start_ip

  • end_ip

org_vdc_create($url,$conf)

Create an org VDC

The conf hash reference can contain:

  • name

  • desc

  • np_href

  • sp_enabled

  • sp_units

  • sp_limit

  • sp_default

  • sp_href

  • allocation_model

  • cpu_unit

  • cpu_alloc

  • cpu_limit

  • mem_unit

  • mem_alloc

  • mem_limit

  • nic_quota

  • net_quota

  • ResourceGuaranteedMemory

  • ResourceGuaranteedCpu

  • VCpuInMhz

  • is_thin_provision

  • pvdc_name

  • pvdc_href

  • use_fast_provisioning

org_vdc_update($url,$conf)

Create an org VDC

The conf hash reference can contain:

  • name (required)

  • desc

  • np_href

  • sp_enabled

  • sp_units

  • sp_limit

  • sp_default

  • sp_href

  • allocation_model

  • cpu_unit

  • cpu_alloc

  • cpu_limit

  • mem_unit

  • mem_alloc

  • mem_limit

  • nic_quota

  • net_quota

  • ResourceGuaranteedMemory

  • ResourceGuaranteedCpu

  • VCpuInMhz

  • is_thin_provision

  • pvdc_name

  • pvdc_href

  • use_fast_provisioning

pdvc_get($href)

task_get($href)

Returns information on the task.

template_get($templateid or $templateurl)

As a parameter, this method thakes the raw numeric id of the template or the full URL.

It returns the requested template.

template_get_metadata($tmpl_href)

Returns the response for metadata for the given template href.

HREF example: http://example.vcd.server/api/vAppTemplate/{uuid}

vdc_get($vdcid or $vdcurl)

As a parameter, this method thakes the raw numeric id of the virtual data center or the full URL detailed a catalog.

It returns the requested VDC.

vdc_list()

Returns the full list of available VDCs.

vapp_create_from_template($url,$name,$netid,$fencemode,$template_href,$IpAddressAllocationMode,$vcdid,$tmplid)

Create a vapp from a vapp template.

Given a name, VDC, template and network, instantiate the vapp template with the given settings and other defaults.

* Fencemode can be: bridged, isolated, or natRouted * IP Allocation mode can be: NONE, MANUAL, POOL, DHCP

An array(ref) is returned. The first element is the task href, if one was created. The second element is the HTTP reqest object returned by the server.

vapp_create_from_sources($url,$name,$netid,$fencemode,$template_href,$IpAddressAllocationMode,$vcdid,$sourcesref)

Given one or more source HREFs, such as VMs withing in an existing template or a VM catalog item, create a vApp.

Details of the create task will be returned.

* Fencemode can be: bridged, isolated, or natRouted * IP Allocation mode can be: NONE, MANUAL, POOL, DHCP

vapp_get($vappid or $vapp_href)

As a parameter, this method thakes the raw numeric id of the vApp or the full URL.

It returns the requested vApp.

vapp_get_metadata($vapp_href)

Returns the response for metadata for the given vApp href.

HREF example: http://example.vcd.server/api/vApp/{uuid}

vapp_recompose_add_vm($href,$vapp_name,$vapp_href,$vm_name_to_be,$vm_current_href)

Returns a task.

VM should be powered off to work.

BUGS and LIMITATIONS

Which "name" is which when recomposing a vApp

The docs on recomosing a vApp (URL below) refer to a name as an attribute of RecomposeVAppParams, a name as an arrtributed of the SourcedItem, and a name as an attribute of CreateItem or DeleteItem.

I believe the official description of all three is "A name as parameter."

Here's what they do when inserting a VM into an existing vApp:

RecomposeVAppParams name attribute - names the task. (I think)

SourcedItem name attribute - The name the new VM will be when put into the vApp. (Note that the "href" attribute right next to it will reference the CURRENT location the VM is being copied from. Got that? One attribute is for the "from" side of the action, and the other is for the "to" side. Clear as mud?)

CreateItem attribute - The name of the container vApp that is being edited. If you change the name, but retain the href for the vApp, it will rename the vApp to the new name.

LoginUrl error.

In both version 1.5 and 5.1 of the API, the "LoginUrl" returned upon log has the value of 'https://HOSTNAME/api/sessions'

To actually succeed with an API log out, however, the URL has to be "session" - singular - 'https://HOSTNAME/api/session'

This module works around this issue.

Template name validation.

Most names in the GUI (for vApps, VMs, Templates, and Catalogs) are limited to 128 characters, and are restricted to being composed of alpha numerics and standard keyboard punctuations. Notably, spaces and tabs are NOT allowed to be entered in the GUI. However, you can upload a template in the API with a space in the name. It will only be visable or usable some of the time in the GUI. Apparently there is a bug in name validation via the API.

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:

Statistics & Dogfooding - There is an implied contract in the API. That is, anything I can see and do in the GUI I should also be able to do via the API. There are no per-VM statistics available in the API. But the statistics are shown in the GUI. Please offer per-VM statistics in the API. Crosswalking the VM name and trying to find the data in the vSphere API to do this is a pain.
System - It would really help if in the API guide it mentions early on that the organization to connect as an administrator account, IE: the macro organization to which all other orgs descend from is called "System." That helps a lot.
External vs External - When you have the concept of a "fenced" network for a vApp, one of the most confusing points is the local network that is natted to the outside is referred to as "External" as is the outside IPs that the network is routed to. Walk a new user through some of the Org creation wizards and watch the confusion. Bad choice of names.

DEPENDENCIES

LWP
XML::Simple

BUGS AND SOURCE

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

VERSION

VMware::API::vCloud v2.404 (2023/09/14)

COPYRIGHT

(c) 2011-2023, Phillip Pollard <bennie@cpan.org>

LICENSE

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

AUTHORSHIP

Phillip Pollard, <bennie@cpan.org>

CONTRIBUTIONS

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

SEE ALSO

VMware vCloud Director Publications
 http://www.vmware.com/support/pubs/vcd_pubs.html
 http://pubs.vmware.com/vcd-51/index.jsp

VMware vCloud API Programming Guide v5.1
 http://pubs.vmware.com/vcd-51/topic/com.vmware.vcloud.api.doc_51/GUID-86CA32C2-3753-49B2-A471-1CE460109ADB.html
 
vCloud API and Admin API v5.1 schema definition files
 http://pubs.vmware.com/vcd-51/topic/com.vmware.vcloud.api.reference.doc_51/about.html
 
VMware vCloud API Communities
 http://communities.vmware.com/community/vmtn/developer/forums/vcloudapi

VMware vCloud API Specification v1.5
 http://www.vmware.com/support/vcd/doc/rest-api-doc-1.5-html/