vcd 10 api guide

vCloud API Programming GuidevCloud API 1.0

This document supports the version of each product listed andsupports all subsequent versions until the document is replacedby a new edition. To check for more recent editions of thisdocument, see http://www.vmware.com/support/pubs.

EN-000180-01

http://www.vmware.com/support/pubs

VMware, Inc.3401 Hillview Ave.Palo Alto, CA 94304www.vmware.com

2 VMware, Inc.

vCloud API Programming Guide

You can find the most up-to-date technical documentation on the VMware Web site at:

http://www.vmware.com/support/

The VMware Web site also provides the latest product updates.

If you have comments about this documentation, submit your feedback to:

[email protected]

Copyright © 2009, 2011 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. VMware products are covered by one or more patents listed at http://www.vmware.com/go/patents.

VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.

http://www.vmware.com/support/

http://www.vmware.com/support

mailto:[email protected]

http://www.vmware.com/go/patents

http://www.vmware.com/go/patents

VMware, Inc. 3

Contents

About This Book 11

1 Introducing the VMware vCloud API 13vCloud Object Taxonomy 13

vCloud Organizations 13

Objects, References, and Representations 15

Links and Link Relations 15

vCloud Client Workflow Overview 17

Requests 17

Responses 18

Configuring the vCloud API URL 19

Related Publications 19

About the Examples 19

2 Hello vCloud: A Structured REST Workflow Example 21Logging In and Getting an Organization List 21

Browsing an Organization 22

Finding a vApp Template 23

Getting Information About a vDC 24

Instantiating the Template in the vDC 24

Deploying and Powering On the vApp 26

Getting Information About the vApp 27

Displaying the Console 29

Retrieve a Screen Ticket 29

Use the Ticket with vmware‐vmrc 30

Deleting the vApp 30

Logging Out 30

Moving on to Additional Use Cases 31

3 Browsing 33Summary of Browsing Requests 33

Discovering the Contents of an Organization, Catalog, or vDC 34

List the Organizations in a vCloud 34

List the Contents of an Organization 34

List the Contents of a Catalog 35

Get Information About a CatalogItem 36

List the Contents of a vDC 37

Getting More Information About an Object 38

Get Information About a Media Image 38

Get Information About a vAppTemplate 39

Get Information About a vApp or Virtual Machine 40

Get Information About a Network 40

4 Provisioning 41Summary of Provisioning Requests 41

Upload OVF to Create a vApp Template 42


4 VMware, Inc.

Restrictions on Uploaded Content 43

Initiate the Upload 43

Including a Manifest 45

Uploading the Files 45

View the OVF Descriptor of a vApp Template 47

Download a vApp Template as OVF 47

Enable a vApp Template for Download 48

Disable a vApp Template for Download 49

Upload a Media Image 50

Copying and Moving 50

Copy or Move a Media Image 51

Copy or Move a vApp Template 51

Copy or Move a vApp 52

Changing a Name or Description 53

Change the Name or Description of a vAppTemplate 53

Change the Name or Description of a vApp 53

Change the Name or Description of a Media Image 54

Delete a vAppTemplate, vApp, or Media Image 54

Cataloging vApp Templates and Media Images 54

Add an Item to a Catalog 54

Remove an Item from a Catalog 56

Catalog Links in a VApp Template or Media Image 56

Controlling Access 56

Control Access to Catalogs 56

5 Datacenter Operations 59Summary of Datacenter Operations Requests 59

vApp Lifecycle 60

Instantiate a vApp Template 61

About Instantiation Parameters 62

About vApp Networks 62

Instantiating a vAppTemplate Using Default Parameters 62

Instantiating a vApp Template Using Additional Parameters 62

Retrieve or Modify the CustomizationSection of a vApp Template 64

Compose a vApp 65

Finding Virtual Machine URLs to Use in a Composition Item 66

Recompose a vApp to Add or Remove Virtual Machines 67

Capture a vApp to Create a vApp Template 68

Reconfiguring vApps and Virtual Machines 69

Reconfigure a vApp 69

Reconfigure a Virtual Machine 73

Deploying and Controlling vApps and Virtual Machines 80

Deploy a vApp or Virtual Machine 80

Undeploy a vApp or Virtual Machine 81

Power On a vApp or Virtual Machine 81

Power Off a vApp or Virtual Machine 82

Reset a vApp or Virtual Machine 82

Suspend a vApp or Virtual Machine 83

Discard the Suspended State of a vApp or Virtual Machine 83

Shut Down a vApp or Virtual Machine 84

Reboot a vApp or Virtual Machine 84

List Media Devices of a Virtual Machine 85

Insert Media Into a Virtual Machine 85

Eject Media from a Virtual Machine 86

Get a Screen Thumbnail for a Virtual Machine 86

VMware, Inc. 5

Contents

Get a Screen Ticket for a Virtual Machine 87

Provide User Input Requested by a Virtual Machine 87

Control Access to vApps 89

Retrieve a Task 89

6 Administrative Operations 91Summary of Administrative Requests 91

Administrator Credentials and Privileges 93

Administrative Objects and URLs 93

Get an Administrative View of a Cloud 93

Organization Administration 94

Create an Organization 95

Get an Administrative View of an Organization 96

List All Tasks Owned by an Organization 97

Modify an Organization 97

Enable or Disable an Organization 98

Remove an Organization 99

Network Administration 99

View the Properties of an External Network 99

Add a Network to an Organization 100

Get an Administrative View of an Organization Network 101

Modify an Organization Network 101

Remove an Organization Network 102

vDC Administration 102

Examine the Contents of a Provider vDC 103

List the Organization vDCs Supported by a Provider vDC 104

Allocate a vDC to an Organization 104

Get an Administrative View of a vDC 106

Modify a vDC 106

Enable or Disable a vDC 107

Remove a vDC 107

Catalog Administration 107

Create a Catalog 107

Get an Administrative View of a Catalog 108

Publish a Catalog 109

Modify Catalog Metadata 109

Remove a Catalog 110

User Administration 110

Create or Import a User 110

Get an Administrative View of a User 112

Modify User Metadata 112

Remove a User 113

Group Administration 113

Import a Group 113

View Group Metadata 114

Modify Group Metadata 114

Remove a Group 114

Role Administration 114

Create a Role 114

View Role Metadata 115

Modify a Role 116

Remove a Role 116

View a Right 116


6 VMware, Inc.

7 VMware vSphere Platform Operations 117Summary of vSphere Platform Operations Requests 117

List vSphere Platform Operations and Objects for a vCloud 119

List Provider vDCs in a vCloud 120

List External Networks in a vCloud 120

List Network Pools in a vCloud 120

List vCenter Servers Registered to a vCloud 120

Get Information About a vCenter Server 120

List Available Resource Pools on a vCenter Server 121

Modify vCenter Server Settings 122

Register a vCenter Server and vShield Manager 122

Unregister a vCenter Server and vShield Manager 123

Force Reconnection to a vCenter Server 124

List ESX/ESXi Hosts in a vCloud 124

Get Information About a Host 124

Prepare a Host 125

Unprepare a Host 126

Enable or Disable a Host 126

Repair a Host 126

Upgrade a Host Agent 127

Create a Provider vDC 127

Examine the vSphere Objects in a Provider vDC 131

Modify a Provider vDC 131

Enable or Disable a Provider vDC 132

Remove a Provider vDC 132

Create an External Network 133

Get Information About an External Network 134

Modify an External Network 135

Remove an External Network 135

Create a Network Pool 136

Get Information About a Network Pool 137

Modify a Network Pool 137

Remove a Network Pool 138

Import a Virtual Machine from vCenter 138

Discover the Virtual Machines in a vCenter 138

Import a Virtual Machine as a vApp 139

Import a Virtual Machine as a vApp Template 140

8 XML Representations in the vCloud API 141About Object Representations 141

Schema 141

Content Type 142

Object Reference Prototype 142

Common Datatypes 142

Primitive XML Datatypes 142

Complex Types 143

Common Attributes 143

name 144

href 144

type 144

status 144

XML Namespace Identifiers 145

Common Elements 146

Description 146

Error 146

VMware, Inc. 7

Contents

Link 147

API Versioning 147

SupportedVersions 148

VersionInfo 148

Extensibility 148

VCloudExtension 149

9 User API Reference 151OrgList 151

Org 151

Vdc 152

StorageCapacity 153

ComputeCapacity 153

AvailableNetworks 153

ResourceEntities 154

ResourceEntity 154

OrgNetwork 154

Configuration 155

Catalog 160

CatalogItems 160

CatalogItem 160

Media 161

VAppTemplate 161

Children 162

VApp 162

Vm 163

Section 163

LeaseSettingsSection 164

StartupSection 164

CustomizationSection 164

NetworkConfigSection 165

NetworkConnectionSection 165

VirtualHardwareSection 167

OperatingSystemSection 167

GuestCustomizationSection 167

RasdItemsList 168

ScreenTicket 168

TasksList 168

Tasks 168

Task 168

10 Request Parameters Reference 171UploadVAppTemplateParams 171

InstantiateVAppTemplateParams 172

InstantiationParams 172

ComposeVAppParams 173

Item 173

NetworkAssignment 174

RecomposeVAppParams 174

DeployVAppParams 175

UndeployVAppParams 175

CaptureVAppParams 175

CloneMediaParams 176

CloneVAppTemplateParams 176


8 VMware, Inc.

CloneVAppParams 176

MediaInsertOrEjectParams 177

VmPendingQuestion 177

VmQuestionAnswer 177

ControlAccessParams 177

AccessSettings 178

11 Administrative API Reference 179VCloud 179

OrganizationReferences 180

ProviderVdcReferences 180

RightReferences 180

RoleReferences 180

Networks 180

ExternalNetwork 180

AdminOrg 180

Settings 181

Users 185

Groups 185

Catalogs 185

Catalog 186

Vdcs 186

ProviderVdc 186

ComputeCapacity 187

StorageCapacity 188

NetworkPoolReferences 188

NetworkPoolReference 188

VdcReferences 188

AdminVdc 188

AllocationModel 190

User 190

Group 191

Role 191

RightReferences 191

RightReference 191

Right 192

12 vSphere Platform Extensions Reference 193VMWExtension 193

VMWProviderVdcReferences 194

VMWExternalNetworkReferences 194

VMWNetworkPoolReferences 194

VMWVimServerReferences 194

VMWHostReferences 194

VimServer 194

VmObjectRefsList 195

VimObjectRef 195

ResourcePoolList 196

ResourcePool 196

ShieldManager 196

VMWProviderVdc 197

VMWNetworkPool 198

FencePoolType 198

PortGroupPoolType 198

VlanPoolType 198

VMware, Inc. 9

Contents

VMWExternalNetwork 199

VlanRange 199

VMWHostReferences 199

Host 199

Request Parameters 200

PrepareHostParams 200

RegisterVimServerParams 200

ImportVmAsVAppParams 201

ImportVmAsVAppTemplateParams 201

A OVF and the vCloud API 203About OVF 203

About OVF Packages 204

About OVA Files 204

How the vCloud API Uses OVF 204

Virtual Machines 204

Virtual Disk Files 205

Networks 205

B An Introduction to REST for vCloud API Users 207How REST Works 207

Using the vCloud REST API 207

RESTful Workflow Patterns 208

For More Information About REST 208

Index 209


10 VMware, Inc.

VMware, Inc. 11

The vCloud API Programming Guide provides information about version 1.0 of the vCloud API.

VMware provides many different APIs and SDKs for various applications and goals. This book provides

information about the vCloud API for developers that are interested in creating RESTful clients of VMware

Cloud Director.

To view the current version of this book as well as all VMware API and SDK documentation, go to

http://www.vmware.com/support/pubs/sdk_pubs.html.

Revision History This book is revised with each release of the product or when necessary. A revised version can contain minor

or major changes. Table 1 summarizes the significant changes in each version of this book.

Intended Audience This guide is intended for software developers who are building VMware Ready Cloud Services, including

interactive clients of VMware Cloud Director. This guide assumes you are familiar with Representational State

Transfer (REST) and RESTful programming conventions, the Open Virtualization Format Specification, and

VMware Virtual machine technology. Familiarity with other widely‐deployed technologies such as XML,

HTTP, and the Windows or Linux operating systems is also assumed.

VMware Technical Publications GlossaryVMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions

of terms as they are used in VMware technical documentation go to http://www.vmware.com/support/pubs.

Document FeedbackVMware welcomes your suggestions for improving our documentation. Send your feedback to

[email protected].

About This Book

Table 1. Revision History

Revision Date Description

08MAR11 GuestCustomizationSection not allowed in InstantiationParams

30AUG10 Version 1.0

http://www.vmware.com/support/pubs/sdk_pubs.html





12 VMware, Inc.

Technical Support and Education ResourcesThe following sections describe the technical support resources available to you. To access the current versions

of other VMware books, go to http://www.vmware.com/support/pubs.

Online and Telephone Support

To use online support to submit technical support requests, view your product and contract information, and

register your products, go to http://www.vmware.com/support.

Support Offerings

To find out how VMware support offerings can help meet your business needs, go to

http://www.vmware.com/support/services.

VMware Professional Services

VMware Education Services courses offer extensive hands‐on labs, case study examples, and course materials

designed to be used as on‐the‐job reference tools. Courses are available onsite, in the classroom, and live

online. For onsite pilot programs and implementation best practices, VMware Consulting Services provides

offerings to help you assess, plan, build, and manage your virtual environment. To access information about

education classes, certification programs, and consulting services, go to http://www.vmware.com/services.


http://www.vmware.com/support

http://www.vmware.com/support/services

http://www.vmware.com/services/

VMware, Inc. 13

1

The VMware vCloud API provides support for developers who are building interactive clients of VMware

Cloud Director using a RESTful application development style. vCloud API clients and servers communicate

over HTTP, exchanging representations of vCloud objects. These representations take the form of XML

elements. HTTP GET requests are used to retrieve the current representation of an object, HTTP POST and

PUT requests are used to create or modify an object, and HTTP DELETE requests are typically used to delete

an object.

This chapter introduces the vCloud API and includes the following topics:

“vCloud Object Taxonomy” on page 13

“Objects, References, and Representations” on page 15

“Links and Link Relations” on page 15

“vCloud Client Workflow Overview” on page 17

“About the Examples” on page 19

vCloud Object TaxonomyThe vCloud API defines a set of objects common to cloud computing environments. Figure 1‐1 illustrates the

principal object types.

vCloud Organizations

A vCloud contains one or more organizations. A vCloud organization is a unit of administration for a

collection of users, groups, and computing resources. Users authenticate at the organization level, supplying

credentials established by an organization administrator when the user was created or imported.

vCloud Users and Groups

An organization can contain an arbitrary number of users and groups. Users can be created by the

organization administrator or imported from a directory service such as LDAP. Groups must be imported

from the directory service. Permissions within an organization are controlled through the assignment of rights

and roles to users and groups.

vCloud Networks

An organization can be provisioned with one or more networks. These organization networks can be

configured to provide services such as DHCP, NAT, and firewalls.

Introducing the VMware vCloud API 1


14 VMware, Inc.

Figure 1-1. vCloud Object Taxonomy

vCloud Virtual Datacenters

A vCloud virtual datacenter (vDC) is an allocation mechanism for resources such as networks, storage, CPU,

and memory. In a vDC, computing resources are fully virtualized, and can be allocated based on demand,

service level requirements, or a combination of the two.

There are two kinds of vDCs:

Provider vDCs. These vDCs contain all the resources available from the vCloud service provider.

Provider vDCs are created and managed by vCloud system administrators.

Organization vDCs. These vDCs provide an environment where virtual systems can be stored, deployed,

and operated. They also provide storage for virtual media, such as floppy disks and CD ROMs.

An organization administrator specifies how resources from a provider vDC are distributed to the vDCs in an

organization.

vCloud Catalogs

Catalogs contain references to virtual systems and media images. A catalog can be shared to make it visible to

other members of an organization, and can be published to make it visible to other organizations. A vCloud

system administrator specifies which organizations can publish catalogs, and an organization administrator

controls access to catalogs by organization members.

vCloud Tasks

Long‐running operations initiated by members of an organization create tasks, which are kept on the

organization’s tasks list.

Catalog 2

Catalogitemememem

Catalog 1

Catalog 3

vDC2 CatalogitemCatalogitemCatalogitemCatalogitem

users

Media

vApptemplate

Media

vApp

TasksList

Organization

vDC1

Media

vApptemplate

Media

vApp

NetworkNetwork

Catalogitemememem

groups

VMware, Inc. 15

Chapter 1 Introducing the VMware vCloud API

Virtual Systems and Media Images in a vCloud

Virtual systems and media images are stored in a vDC and can be included in a catalog. Media images are

stored in their native representation (ISO or floppy). Virtual systems are stored as templates, using an open

standard format (OVF 1.0). These templates can be retrieved from catalogs and transformed into virtual

systems, called vApps, through a process called instantiation, which binds a template’s abstract resource

requirements to resources available in a vDC. A vApp contains one or more individual virtual machines (Vm elements), along with parameters that define operational details such as:

How the contained virtual machines are connected to each other and to external networks.

The order in which individual virtual machines are powered on or off.

End‐user license agreement terms for each virtual machine.

Deployment lease terms (typically inherited from the containing organization) that constrain the vApp’s

consumption of vDC resources

Access control information specifying which users and groups can perform operations such as deploy,

power on, modify, and suspend on the vApp and the virtual machines it contains.

Objects, References, and RepresentationsThe vCloud API represents objects in the vCloud as XML documents in which object properties are encoded

as elements and attributes with typed values and an explicit object hierarchy defined by an XML schema.

Every object in a vCloud is uniquely identified by a URL. This URL is constructed by the server and returned

in the value of the href attribute of the XML element that represents the object. It also appears in various

elements of LinkType and ReferenceType. This URL serves as a unique identifier that persists for the life of the object and is never re‐used. Although URLs have a well‐known syntax and a well‐understood

interpretation, a client should treat each href as an opaque string. The rules that govern construction of href strings by the server might change in future releases.

Object types, specified as MIME content types, are included in the XML representations of first‐class objects

such as the ones shown in Figure 1‐1. For more information, see “Content Type” on page 142.

Links and Link RelationsThe vCloud API makes extensive use of links (URLs) to provide references to objects and the actions that they

support. These links are the primary mechanism by which a server tells a client how to access and operate on

an object. Links are created by the server, and are read‐only at the client. (If a client request body includes a

link, the server ignores it.)

In the XML representation of a vCloud object, each link is defined in a Link element that has the following

form:

<Link rel="relationship" type="application/vnd.vmware.vcloud.type+xml" href="URL" name="string"/>

The rel attribute value defines the relationship of the object whose XML representation contains the Link to a target object. The relationship also indicates the HTTP request type to use when making a request

with the href attribute of the link, as shown in Table 1‐1:

Table 1-1. Link Relationships and HTTP Request Types

rel Attribute Value Relation Description HTTP Request

add adds an item to this container POST

alternate a link to an alternate representation of this object GET

catalogItem a link to the catalogItem that contains a reference to this object. GET

controlAccess apply access controls POST

copy not supported in this release N/A

deploy deploy this object POST


16 VMware, Inc.

The type attribute value defines the media type (HTTP Content‐Type) of the request or response

document. This attribute is present only for links to objects. It is not present for links to actions.

The href attribute value is a URL, which should be considered an opaque identifier (one that the client

should not attempt to parse or interpret). An href uniquely identifies, and persists for the life of, the referenced object. These identifiers are never re‐used.

The name attribute value of the Link is the same as the name of the referenced object. Action links do not

include a name attribute.

disable disable this object POST

discardState discard the suspended state of this virtual machine POST

down the referenced object is contained by this object GET

download:alternate not supported in this release N/A

download:default default download location for this file GET

edit modifies this object PUT

enable enable this object POST

extension not supported in this release N/A

media:ejectMedia eject virtual media from a virtual device POST

media:insertMedia insert virtual media in a virtual device POST

move not supported in this release N/A

ova not supported in this release N/A

ovf the OVF representation of this vAppTemplate GET

power:powerOff power off the referenced object POST

power:powerOn power on this object POST

power:reboot reboot this object POST

power:reset reset this object POST

power:shutdown shut down this object POST

power:suspend suspend this object POST

publish publish this catalog POST

recompose recompose this vApp POST

reconnect reconnect this vCenter Server POST

register register this vCenter Server POST

remove remove this object DELETE

repair repair this host POST

screen:acquireTicket acquire a screen ticket for this virtual machine GET

screen:thumbnail thumbnail view of a virtual machine screen, in png format GET

task:cancel not supported in this release N/A

undeploy undeploy this object POST

unregister unregister this vCenter Server POST

up the referenced object contains this object GET

upgrade upgrade this host POST

upload:alternate not supported in this release N/A

upload:default default upload location for this file PUT

Table 1-1. Link Relationships and HTTP Request Types (Continued)

rel Attribute Value Relation Description HTTP Request

VMware, Inc. 17


Links provide a way for the server to inform a client about object relationships and the operations that objects

support. For example, a container such as an organization or catalog can return links to the objects it contains,

and a virtual system (a vApp or Vm) can contain action links that enable operations such as power state changes

or virtual device reconfiguration. Links to actions and contained objects are omitted from responses if the

request was made by a user who has insufficient privileges to access the object or perform the action. Action

links are also omitted when the action cannot be performed (powering on a virtual machine that is already

powered on, for example).

vCloud Client Workflow OverviewClients of the vCloud API implement a RESTful workflow, making HTTP requests to the server and retrieving

the information they need from the server’s responses.

Requests

Clients make HTTP requests to vCloud URLs, href attribute values which are typically provided by the server

in response to GET requests by the client. Every vCloud has a well‐known URL from which a client can get the

server’s login URL and the list of vCloud API versions that the server supports, along with additional

information (see “API Versioning” on page 147). After a client has logged in, all vCloud API URLs can be

discovered by making GET requests to URLs listed in the login response and the URLs contained in responses

to those requests.

Request Headers

All requests from authenticated clients must include an authentication header. See “Authentication” on

page 18.

Requests that include a document body must start with the appropriate HTTP Content‐Type header. The type attribute of a response body indicates the content type of the document. For example, this response fragment

indicates that the content type associated with a CatalogItem entity is application/vnd.vmware.vcloud.catalogItem+xml.

<CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221" name="Ubuntu Template with vsftpd"/>

Any request that includes a CatalogItem requires the following Content‐Type header:

Content-Type: application/vnd.vmware.vcloud.catalogItem+xml

When it appears as the value of a Content‐Type header or the type attribute of an element in the vCloud API,

this string is case‐insensitive in requests, and can be returned in either mixed case or lowercase characters in

responses.

For more information, see “Content Type” on page 142.

Request Bodies

This release of Cloud Director uses a validating XML parser that requires elements in a request body to agree

in both order and number with the schema. Request bodies are rejected as invalid unless they meet the

following criteria:

XML namespace attributes must be supplied for all namespaces represented by elements in the request.

See “XML Namespace Identifiers” on page 145.

If multiple namespaces are represented in the request, XML namespace attributes must include an

identifying prefix, and that prefix must be used with elements from that namespace. See “XML

Namespace Prefixes in Request and Response Bodies” on page 146.

NOTE When a client uses a link to reference an object, only the href attribute is required. The name and type

are ignored.


18 VMware, Inc.

All required elements must appear in request bodies. All elements that appear in request bodies must

appear in the order established by the schema, and with content that conforms to the type constraint

specified in the schema. See “Schema Validation” on page 142.

Authentication

HTTP communications between a vCloud client and server are typically secured with SSL. In addition, the

vCloud API implements Basic HTTP Authentication, as defined by RFC 2617, which enables a client to obtain

a token that it can use to authenticate individual HTTP requests.

To obtain and use an authentication token, a client must first discover the server’s login URL, and then POST

a login request to that URL, supplying the credentials of an authorized user.

To obtain and use an authentication token

1 Make an API version request to a vCloud service to obtain the login URL for that service. For more

information, see “API Versioning” on page 147.

2 Make an HTTP POST request to the login URL, as shown in Example 2‐1 on page 21.

If the authentication header is missing, the server returns HTTP response code 401.

If the credentials supplied in the authentication header are invalid, the server returns HTTP response

code 401.

If the request is successful, the server returns HTTP response code 200 (OK) and headers that include

an authorization header of the form:

x-vcloud-authorization: token

This header must be included in each subsequent vCloud API request.

The response body is an OrgList element, which is a list of all organizations that the user can access.

The authentication token expires after a configurable interval of client inactivity. The default is 30 minutes after

the token is created. After the token expires, all requests fail with HTTP response code 401 until the client logs

in again to obtain a new token.

Responses

All responses include an HTTP status code and, unless the status code is 204 (No Content), a Content‐Type

header. Response content depends on the request. Some responses include a document body, some include

only a URL, and some are empty.

Status Codes

Table 1‐2 lists the subset of HTTP status codes that a vCloud API client can expect in a response.

NOTE Certain administrative operations have special authentication requirements. For more information, see

“Administrator Credentials and Privileges” on page 93.

Table 1-2. HTTP Status Codes Returned by the vCloud API

Status Code Status Description

200 OK The request is valid and was completed. The response includes a document body.

201 Created The request is valid. The requested object was created and can be found at the URL specified in the Location header.

202 Accepted The request is valid and a task was created to handle it. This response is usually accompanied by a task URL.

204 No Content The request is valid and was completed. The response does not include a body.

303 See Other The response to the request can be found at the URL specified in the Location header.

400 Bad Request The request body is malformed, incomplete, or otherwise invalid.

VMware, Inc. 19


Configuring the vCloud API URL

The base URL used in href values includes the fully‐qualified domain name of the server host. In cases where

this hostname cannot be resolved from the client (for example, if the Cloud Director installation includes

multiple server hosts that you access through a load balancer) you can specify a URL for the server to use when

constructing href strings. For more information, see Configure the External REST API Base URI in the Cloud

Director Administratorʹs Guide.

Related PublicationsThe VMware Cloud Director Administratorʹs Guide and VMware Cloud Director User’s Guide contain detailed

information about many of the objects and operations referred to in this guide. Most users of the vCloud API

will find the information in those documents valuable when developing client applications. To access the

current versions of these and other VMware books, go to http://www.vmware.com/support/pubs.

About the ExamplesThis guide includes many examples of HTTP requests and responses. These examples are intended to show

the workflow and content associated with specific types of operations such as browsing, managing inventory,

and operating virtual systems. Example requests generally conform to the rules listed in “Request Bodies” on

page 17. Most example responses show only those elements and attributes that are relevant to the operation

being discussed. Ellipses (…) indicate omitted content within response bodies.

HTTP Content‐Type headers are shown where needed for all examples that are not fragments of some larger

example that includes this header. Although the examples show these strings using the character case in which

they are defined by the implementation, these strings are case‐insensitive in requests, and can be returned in

either mixed case or lowercase characters in responses. Other HTTP headers, such as Date, Content‐Length,

and Server, are omitted because they are not relevant to the specifics of any example. The XML version and

encoding header (<?xml version="1.0" encoding="UTF-8"?>) is not included in most examples, although

it is a required part of all requests and responses that contain an XML body.

In addition:

Unsecured URLs (http://) are used in the examples. In practice, most sites will require the use of SSL

(https://).

Object IDs shown in href attribute values appear as small integers (for example vapp-7 or org/3). In the vCloud API supported by Cloud Director, object IDs are 10‐digit decimal integers (for example

vapp-124237959 or org/5738592905).

401 Unauthorized An authorization header was expected but not found.

403 Forbidden The requesting user does not have adequate privileges to access one or more objects specified in the request.

404 Not Found One or more objects specified in the request could not be found in the specified container.

405 Method Not Allowed

The HTTP method specified in the request is not supported for this object.

500 Internal Server Error

The request was received but could not be completed due to an internal error at the server.

501 Not Implemented The request is not implemented by the server.

503 Service Unavailable

One or more services needed to complete the request are not available on the server.

Table 1-2. HTTP Status Codes Returned by the vCloud API (Continued)

Status Code Status Description



20 VMware, Inc.

VMware, Inc. 21

2

This chapter presents a simple example of a structured REST workflow for discovering and deploying a

particular vApp (in this case, an FTP server with a connection to the public Internet).

This chapter includes the following topics:

“Logging In and Getting an Organization List” on page 21

“Browsing an Organization” on page 22

“Finding a vApp Template” on page 23

“Getting Information About a vDC” on page 24

“Instantiating the Template in the vDC” on page 24

“Deploying and Powering On the vApp” on page 26

“Getting Information About the vApp” on page 27

“Deleting the vApp” on page 30

“Logging Out” on page 30

Logging In and Getting an Organization ListEvery vCloud has a login URL that a client can obtain by making an unauthenticated GET request to the

vCloud’s versions URL, as shown in Example 8‐2 on page 147. Because all other vCloud API requests must

be authenticated, any vCloud API workflow has to begin with a login request that supplies user credentials in

the form required by Basic HTTP authentication (MIME Base64 encoding of a string having the form

user@vcloud‐organization:password). Example 2‐1 shows a login request and response for a vCloud whose login

URL is http://vcloud.example.com/api/v1.0/login.

Example 2-1. Login Request and Response

Request:

POST http://vcloud.example.com/api/v1.0/loginAuthorization: Basic encoded-credentials

Response:

200 OKDate: request-datex-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM=Content-Type: application/vnd.vmware.vcloud.orgList+xml...<?xml version="1.0" encoding="UTF-8"?><OrgList ... href="http://vcloud.example.com/api/v1.0/org/" ... >

<Org type="application/vnd.vmware.vcloud.org+xml" name="ExampleOrg" href="http://vcloud.example.com/api/v1.0/org/5"/>

Hello vCloud: A Structured REST Workflow Example 2


22 VMware, Inc.

<Org .../><Org .../>

</OrgList>

The response includes an authentication token supplied in the x-vcloud-authorization header, and a list of the organizations to which the authenticated user has access. Each Org has a URL (in its href attribute value) that the client can use to get more information about objects that the organization contains. For more

information about authentication, see “Authentication” on page 18.

Browsing an OrganizationYou can use an HTTP GET request and one of the Org URLs returned by the login request to discover the contents of an organization, as shown in Example 2‐2. (For a more complete version of this example, see

Example 3‐1 on page 34.)

Example 2-2. List the Contents of an Organization

Request:

GET http://vcloud.example.com/api/v1.0/org/5

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.org+xml...<Org name="ExampleOrg" type="application/vnd.vmware.vcloud.org+xml"

href="http://vcloud.example.com/api/v1.0/org/5" ... ><Link ... /><Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml"

href="http://vcloud.example.com/api/v1.0/catalog/32" name="MainCatalog"/><Link ... /><Link rel="down" type="application/vnd.vmware.vcloud.vdc+xml"

href="http://vcloud.example.com/api/v1.0/vdc/5" name="ExampleVdc01"/><Link ... /><Link rel="down" type="application/vnd.vmware.vcloud.network+xml"

href="http://vcloud.example.com/api/v1.0/network/14" name="IsolatedOrgNet"/><Link rel="down" type="application/vnd.vmware.vcloud.network+xml"

href="http://vcloud.example.com/api/v1.0/network/54" name="Internet"/><Description>Example Corp’s Primary Organization</Description>

</Org>

Links in the response whose rel attribute has a value of down are references to objects that the organization contains. Example 2‐2 shows the subset of those items that you will need for this exercise:

A catalog named MainCatalog, at URL http://vcloud.example.com/api/v1.0/catalog/32, where you can

look for vApp templates.

A vDC named ExampleVdc01, at URL http://vcloud.example.com/api/v1.0/vdc/5, where you can deploy

the vApp.

Two networks: one named Internet, at URL http://vcloud.example.com/api/v1.0/network/54, and one

named IsolatedOrgNet, at URL http://vcloud.example.com/api/v1.0/network/14. You can connect

connect the vApp to either of these networks.

NOTE This example, like other examples in this guide, omits certain required HTTP headers and other content

so that it can provide a concise, readable subset of an actual request and response. For more information, see

“About the Examples” on page 19.

VMware, Inc. 23

Chapter 2 Hello vCloud: A Structured REST Workflow Example

Finding a vApp TemplateThe client can use the catalog URL shown in Example 2‐2 as the target of a GET request that returns the

contents of the catalog, as shown in Example 2‐3.

Example 2-3. Finding a vApp Template in a Catalog

Request:

GET http://vcloud.example.com/api/v1.0/catalog/32

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.catalog+xml...<Catalog name="MainCatalog" type="application/vnd.vmware.vcloud.catalog+xml"

href="http://vcloud.example.com/api/v1.0/catalog/32" ...>...<Description>Main Org Catalog</Description><CatalogItems>

...<CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu Template

with vsftpd" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/>...

</CatalogItems>...

</Catalog>

Every vApp template or media image that has been added to the catalog is represented as a CatalogItem element. When a client browses a catalog, it can read only the name, type, and href of each CatalogItem. To retrieve an item from the catalog, more information is required. In Example 2‐4, the client makes a GET request

to a CatalogItem URL (its href value). The response provides more information, including a description of

the referenced object and another URL that the client can use to retrieve a representation of the object.

Example 2-4. Getting the vApp Template URL From a CatalogItem

Request:

GET http://vcloud.example.com/api/v1.0/catalogItem/221

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.catalogItem+xml...<CatalogItem name="Ubuntu Template with vsftpd"

href="http://vcloud.example.com/api/v1.0/catalogItem/221" ...>...<Description>Ubuntu Template with vsftpd</Description><Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"

type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/>

...</CatalogItem>

This response shows that a suitable vApp template can be found at

http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate‐111.


24 VMware, Inc.

Getting Information About a vDCInstantiation, deployment, and operation of a vApp all take place in the context of a vDC. The XML

representation of a vDC object defines that context in detail. For this exercise, you need only two pieces of

information from the vDC:

The URL that a client can use to request an instantiateVAppTemplate operation in the vDC

A list of networks to which the vApp can connect.

Example 2‐5 shows this subset of vDC contents. (For a more complete look at those contents, see Example 3‐4

on page 37.)

Example 2-5. List the Contents of a vDC

Request:

GET http://vcloud.example.com/api/v1.0/vdc/5

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.vdc+xml...<Vdc name="ExampleVdc01" type="application/vnd.vmware.vcloud.vdc+xml"

href="http://vcloud.example.com/api/v1.0/vdc/5" ...>...<Link rel="add" type="application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml"

href="http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate"/>

...<AvailableNetworks>

<Network href="http://vcloud.example.com/api/v1.0/network/14" type="application/vnd.vmware.vcloud.network+xml" name="IsolatedOrgNet"/>

<Network href="http://vcloud.example.com/api/v1.0/network/54" type="application/vnd.vmware.vcloud.network+xml" name="Internet"/>

</AvailableNetworks>...

</Vdc>

The information you need is available here in two places:

An Link element containing an action URL,

http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate. The rel attribute of this Link has a value of add, indicating that it implements an action that adds an object to the vDC.

A list of AvailableNetworks that includes all the networks owned by the organization that contains this

vDC. Since we want this FTP server to be accessible on the public Internet, we will connect the vApp to

the network named Internet.

Both these pieces of information are put to use in Example 2‐6.

Instantiating the Template in the vDCTo create a vApp from this template, you must bind its abstract resource requirements, such as network

connections, storage resources, memory, and CPU capacity, to appropriate resources in the target vDC. This

binding operation is called instantiation. Although a client can specify these bindings in detail, a simple

instantiation, which relies on organization and vDC defaults, requires only a few pieces of information:

A name for the vApp that the request creates

The URL of the template to instantiate. In this case, the URL (retrieved in Example 2‐4) is

http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate‐111.

VMware, Inc. 25


Creation parameters for a vApp network. A vApp network defines how the vApp connects to an

organization network available in the target vDC. For more information, see “About vApp Networks” on

page 62.

The instantiateVAppTemplate request in Example 2‐6 supplies these parameters in the following places:

The name is supplied in the name attribute of the InstantiateVAppTemplateParams request. (This request also provides a description, which is optional but a good practice.)

The template URL is suppled in the Source element

The vApp network is specified in the NetworkConfigSection element. This specification includes three

parameters:

A name for the network, supplied in the name attribute of the NetworkConfigSection element. If

the vApp template includes an ovf:Network element, the name you specify for the vApp network

must match the name specified in that element’s ovf:name attribute.

A reference to the organization network to which the vApp network connects, specified in the

ParentNetwork element. The URL used here is one returned in Example 2‐5, in the

AvailableNetworks element of the vDC.

A fence mode, specified in the FenceMode element. A value of bridged indicates that the vApp network is connected directly to the organization network.

The target of the request is the instantiateVAppTemplate URL of this vDC (see Example 2‐5). Because the

operation creates a new object (a vApp), the HTTP request type is POST.

Example 2-6. Instantiating a vApp Template

Request:

POST http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplateContent-Type: application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml...<InstantiateVAppTemplateParams name="Linux FTP server" xmlns="http://www.vmware.com/vcloud/v1"

xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" ><Description>Example FTP Server vApp</Description><InstantiationParams>

<NetworkConfigSection><ovf:Info>Configuration parameters for vAppNetwork</ovf:Info><NetworkConfig networkName="vAppNetwork">

<Configuration><ParentNetwork href="http://vcloud.example.com/api/v1.0/network/54"/><FenceMode>bridged</FenceMode>

</Configuration></NetworkConfig>

</NetworkConfigSection></InstantiationParams><Source href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/>

</InstantiateVAppTemplateParams>

Response:

201 CreatedContent-Type: application/vnd.vmware.vcloud.vApp+xml

<VApp deployed=”false” status="0" name="Linux FTP server" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...>

<Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/>

<Description>Example FTP Server vApp</Description><Tasks>


26 VMware, Inc.

<Task status="running" startTime="2010-06-25T08:00:55.402-07:00" operation="Creating Virtual Application Linux FTP server(7)" expiryTime="2010-09-23T08:00:55.402-07:00" type="application/vnd.vmware.vcloud.task+xml" href="http://vcloud.example.com/api/v1.0/task/1awvdrn82atz7yzsdey">

<Owner type="application/vnd.vmware.vcloud.vApp+xml" name="LinuxFtpServer" href="http://vcloud.example.com/vApp/vapp-7"/>

</Task> </Tasks></VApp>

The response to the instantiation request is a sparsely populated vApp body, which includes the following

information:

The status of the vApp. The status value 0 indicates that the vApp is unresolved, because instantiation has not completed.

The name of the vApp, as supplied in the request

The vApp URL, shown in the href attribute of the VApp body

A task created to track the instantiation. The Task element has an operation attribute that describes what

is happening, and contains an Owner element that is a reference the vApp being created. For more

information, see “Task” on page 168.

Deploying and Powering On the vAppAfter the instantiation task completes, the template has been transformed into a vApp. The vApp body no longer includes a Tasks element, and it now includes a number of Link elements that you can use to deploy

and operate the vApp. Example 2‐7 shows a request and response for a deploy action. The request URL is the rel="deploy" link returned in the vApp body (see Example 2‐8). The request body is a DeployVAppParams element, which specifies deployment details.

Example 2-7. Deploy and Power On a vApp

Request:

POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/deployContent-type: application/vnd.vmware.vcloud.deployVAppParams+xml...<DeployVAppParams powerOn="true" deploymentLeaseSeconds="2592000"

xmlns="http://www.vmware.com/vcloud/v1"/>

Response:

202 Accepted<Task xmlns="http://www.vmware.com/vcloud/v1" status="running"

startTime="2010-06-25T11:15:55.558-07:00" operation="Starting Virtual Application Linux FTP server(7)" expiryTime="2010-09-23T08:00:55.402-07:00" type="application/vnd.vmware.vcloud.task+xml" href="http://vcloud.example.com/api/v1.0/task/i9h1djqzsyllf0zvdy" ...>


</Task>

Because deployment is a long‐running operation that can fail for a variety of reasons (inability of the vDC to

satisfy the vApp’s resource requirements, for example), the response is a Task.

NOTE A vApp template might include a license agreement or other terms that you must accept before you

can create a vApp from it. In this example, the template contains no such terms. If it did, the request would

fail if it did not include an AllEULAsAccepted element, as shown in Example 5‐1 on page 63.

VMware, Inc. 27


Because the deployment request specified powerOn="true", the vApp is powered on and ready for use when

the task completes. The client can wait for a suitable interval and check the task status (see “Retrieve a Task”

on page 89), or simply begin requesting operations on the powered‐on vApp and checking the task status if

those requests fail. See “Deploying and Controlling vApps and Virtual Machines” on page 80.

Getting Information About the vAppAs other examples have shown, a client can always use an HTTP GET request to discover the current state of

any vCloud object, including a vApp. The response in Example 2‐8 reveals several things:

The vApp is deployed (its deployed attribute is set to true) and powered on (status="4").

The Vm in its Children collection is also powered on and deployed. The Vm is connected to the vApp network created during instantiation (see Example 2‐6). Properties of this network are included in the

NetworkConfigSection of the vApp, though most are not shown here.

Action links for all operations except powerOn are present in both the vApp itself and its child Vm. Because the vApp is already powered on, that operation is invalid for the vApp in its current state, so the link is

not part of the response. (The link for deploy is always present, even in a deployed vApp, because the

deploy action is always valid.) The Vm element also includes several links for actions that not applicable

to a vApp: actions like acquiring a screen ticket or thumbnail, and inserting or removing media, are

specific to a virtual machine. Other actions like shutdown and reboot, can be applied to either object. See “Deploying and Controlling vApps and Virtual Machines” on page 80.

Much additional information is available, though most of it is not shown here. The example does show

where to find the IP address of the vApp, in the IpAddress element of the NetworkConnection.

Example 2-8. Get Information About the vApp

Request:

GET http://vcloud.example.com/api/v1.0/vApp/vapp-7

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.vApp+xml...<VApp status="4" name="Linux FTP server" type="application/vnd.vmware.vcloud.vApp+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ... ><Link rel="power:reboot"

href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/reboot"/><Link rel="power:powerOff"

href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/powerOff"/><Link rel="undeploy" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/undeploy"/><Link rel="deploy" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/deploy"/><Link rel="power:shutdown"

href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/shutdown"/><Link rel="power:reset"

href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/reset"/><Link rel="power:suspend"

href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/suspend"/><Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/controlAccess/"/><Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/controlAccess/"/><Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml"

href="http://vcloud.example.com/api/v1.0/vdc/5"/><Link rel="edit" type="application/vnd.vmware.vcloud.vApp+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vapp-7"/><Description>Example FTP Server vApp</Description><LeaseSettingsSection ...>

...</LeaseSettingsSection><ovf:StartupSection ... >

...


28 VMware, Inc.

</ovf:StartupSection><ovf:NetworkSection ... >

<ovf:Info/><ovf:Network ovf:name="vAppNetwork">

<ovf:Description/></ovf:Network>

</ovf:NetworkSection><NetworkConfigSection

href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/" ovf:required="false">

<Link rel="edit" type="application/vnd.vmware.vcloud.networkConfigSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/"/>

<ovf:Info>Configuration parameters for vAppNetwork</ovf:Info><NetworkConfig networkName="vAppNetwork">

<Configuration><IpScope>

...</IpScope><ParentNetwork type="application/vnd.vmware.vcloud.network+xml" name="Internet"

href="http://vcloud.example.com/api/v1.0/network/54"/><FenceMode>bridged</FenceMode>

</Configuration><IsDeployed>true</IsDeployed></NetworkConfig>

</NetworkConfigSection><Children>

<Vm deployed="true" status="4" name="ubuntu10-x86" type="application/vnd.vmware.vcloud.vm+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4">

<Link rel="power:reboot" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/action/reboot"/>

<Link rel="power:powerOff" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/action/powerOff"/>

<Link rel="undeploy" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/action/undeploy"/>

<Link rel="deploy" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/action/deploy"/>

<Link rel="power:shutdown" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/action/shutdown"/>

<Link rel="power:reset" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/action/reset"/>

<Link rel="power:suspend" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/action/suspend"/>

<Link rel="up" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7"/>

<Link rel="screen:thumbnail" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/screen"/>

<Link rel="screen:acquireTicket" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/screen/action/acquireTicket"/>

<Link rel="media:insertMedia" type="application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/media/action/insertMedia"/>

<Link rel="media:ejectMedia" type="application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/media/action/ejectMedia"/>

<Description/><ovf:VirtualHardwareSection ...>

...</ovf:VirtualHardwareSection>...<NetworkConnectionSection>

...<NetworkConnection network="vAppNetwork">

...

VMware, Inc. 29


<IpAddress>10.147.122.134</IpAddress><IsConnected>true</IsConnected><MACAddress>00:50:56:01:01:49</MACAddress>...

</NetworkConnection>...

</NetworkConnectionSection><GuestCustomizationSection ...>

...</GuestCustomizationSection><VAppScopedLocalId>20ea086f-1a6a-4fb2-8e2e-23372facf7de</VAppScopedLocalId>

</Vm></Children>

</VApp>

Displaying the ConsoleAfter the vApp has been powered on, you can retrieve a screen ticket from one of its virtual machines and use

that ticket to gain access to the console of the virtual machine.

Retrieve a Screen Ticket

A screen ticket is a string that includes the virtual machine’s IP address, its managed object reference, and a

string that has been encoded as described in RFC 2396. Each Vm element in a vApp includes a link where

rel="screen:acquireTicket". You can use that link to request a screen ticket that you can use with the

vmware-vmrc utility to open a VMware Remote Console for the virtual machine represented by that Vm element. Example 2‐9 makes such a request using the acquireTicket link returned in Example 2‐8.

Example 2-9. Get a Screen Ticket for a Virtual Machine

Request:

POST http://vcloud.example.com/api/v1.0/vApp/vm-4/screen/action/acquireTicket

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.screenTicket+xml...<ScreenTicket xmlns="http://www.vmware.com/vcloud/v1"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1 ...>

mks://10.147.43.171/vm-61?ticket=Pznh4HMb7k%2FlniSLwyAD1fmlPIXOuSACKgEReF7ylTIn4qRkxhFv9QT7I3SLTAQu%2F7W5RxVpDxjVKuuHQ4VIwu59F%2FG1WL1OmYMWistJC9tkRjQ1RRQiB1Oem5E7qX9O

</ScreenTicket>

The ticket itself has the following form:

mks://ip-address/VM-MoRef/ticket=encoded-ticket

where:

ip‐address is the IP address of the virtual machine

VM‐MoRef is the managed object reference of the virtual machine

encoded‐ticket is the encoded screen ticket. You must decode this ticket using a function such as

URLDecoder (Java) or url_escape (PERL) before you can use it.

The ticket is valid for 30 seconds.


30 VMware, Inc.

Use the Ticket with vmware-vmrc

The vmware-vmrc plug‐in is installed by your browser whenever you use the Cloud Director Web Console to

access the console of a running virtual machine. After this plug‐in has been installed, you can find it in the

folder that your browser uses for plug‐ins.

To use a screen ticket with vmware-vmrc, open a command shell in the folder where vmware-vmrc.exe is installed and run a command that has the form:

vmware-vmrc -h ip-address -p decoded-ticket -M VM-MoRef

For the ticket shown in Example 2‐9, the command line would look similar to this one.

vmware-vmrc -h 10.147.43.171 -p 9XVUXZ... -M vm-61

The command contacts the specified IP address, presents the decoded ticket for validation, and displays a

VMware Remote Console window. If the ticket is valid, you can access the virtual machine’s console in the

window. If the ticket is improperly decoded or has timed out, and error message is displayed.

Deleting the vAppYou can use an HTTP DELETE request to delete a vApp, as shown in Example 2‐10. (You must power off and

undeploy the vApp before you delete it.) The response is a Task body. Because the task tracks a deletion, it does not include an Owner element. (The owner is the object being deleted.)

Example 2-10. Delete a vApp

Request:

DELETE http://vcloud.example.com/api/v1.0/vApp/vapp-7

Response:

202 Accepted<Task xmlns="http://www.vmware.com/vcloud/v1" status="running"

startTime="2010-06-25T08:10:23.650-07:00" operation="Deleting Virtual Application Linux FTP server (7)" expiryTime="2010-09-23T08:00:55.402-07:00" type="application/vnd.vmware.vcloud.task+xml" href="http://vcloud.example.com/api/v1.0/task/jul1tndoojgaesymci" ... >

<Owner type="application/vnd.vmware.vcloud.vApp+xml" name="Linux FTP server" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7"/>

</Task>

Logging OutTo log out and end a session, a vCloud API client makes a POST request to the logout URL, as shown in

Example 2‐11.

Example 2-11. Log Out

Request:

POST http://vcloud.example.com/api/v1.0/logoutx-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM=

Response:

200 OK

NOTE The version of vmware-vmrc included with Cloud Director cannot be used to access virtual machines

in vCenter. In addition, it is incompatible with the version of vmware-vmrc installed by VMware vSphere Web

Access, which is also installed as a browser plug‐in, and cannot co‐exist with the Cloud Director version of

vmware-vmrc.

VMware, Inc. 31


Moving on to Additional Use CasesThis “Hello” exercise, while simplified, demonstrates a pattern common to many vCloud API use cases:

browsing to discover a template, instantiating the template, then deploying and operating the vApp described

in the template. The remainder of this guide provides expanded examples of these and other use cases,

including:

Creating vApp templates by uploading OVF packages or capturing vApps (“Provisioning” on page 41)

Non‐default instantiation using detailed instantiation parameters (“Instantiate a vApp Template” on

page 61)

Creating a copy of a vApp by cloning, or composing a vApp from multiple vApps or templates

Reconfiguration of a vApp to add or remove virtual hardware, modify network connections, and change

other vApp properties (“Reconfiguring vApps and Virtual Machines” on page 69)

Administrative operations to create vDCs and Catalogs, and to administer users, groups, and roles

(“Administrative Operations” on page 91).

Operations that a system administrator can use to access the vSphere platform that supports a vCloud

roles (“VMware vSphere Platform Operations” on page 117).

This guide also includes complete reference information on XML elements defined by the vCloud API (see

Chapter 9, “User API Reference,” on page 151 and Chapter 11, “Administrative API Reference,” on page 179),

and those defined by the vSphere platform extensions (see Chapter 12, “vSphere Platform Extensions

Reference,” on page 193). It also includes an introduction to OVF Appendix A, “OVF and the vCloud API,” on

page 203, which concentrates on those aspects of OVF that might be of interest to advanced vCloud API

programmers.


32 VMware, Inc.

VMware, Inc. 33

3

A vCloud API client can use HTTP GET requests to browse containers such as organizations, catalogs, and

vDCs. Responses to these requests include metadata about the container itself and references to the objects it

contains. These references are provided in Link elements, which have href attributes whose values the client

can use in requests to get more information about the objects themselves. This hierarchical structure of

containers lends itself to graphical representation as a folder hierarchy or tree view of vCloud objects, and

enables clients to use the same set of objects and operations to implement a breadth‐first or depth‐first

approach to browsing.


“Summary of Browsing Requests” on page 33

“Discovering the Contents of an Organization, Catalog, or vDC” on page 34

“Getting More Information About an Object” on page 38

Summary of Browsing RequestsTable 3‐1 summarizes browsing requests supported in this release. The table uses the following conventions:

API‐URL is a URL of the form http://vcloud.example.com/api/v1.0

id is an integer

Browsing 3

Table 3-1. Summary of Browsing Requests

Operation Request Request Body Response

Show Login URL and List Supported API Versions

GET http://hostname/api/versions None SupportedVersions

Log in POST API‐URL/login None OrgList

Log out POST API‐URL/logout None 200 OK

List the Organizations in a vCloud GET API‐URL/org None OrgList

List the Contents of an Organization GET API‐URL/org/id None Org

Get Information About a Network GET API‐URL/network/id None OrgNetwork

List the Contents of a Catalog GET API‐URL/catalog/id None Catalog

Get Information About a CatalogItem GET API‐URL/catalogItem/id None CatalogItem

List the Contents of a vDC GET API‐URL/vdc/id None Vdc

Get Information About a Media Image GET API‐URL/media/id None Media

Get Information About a vAppTemplate

GET API‐URL/vAppTemplate/vappTemplate‐id None VAppTemplate

Get Information About a vApp or Virtual Machine

GET API‐URL/vApp/vapp‐id None VApp


34 VMware, Inc.

Discovering the Contents of an Organization, Catalog, or vDCThe vCloud API defines three principal containers: organizations, catalogs, and vDCs. A client can use an

HTTP GET request to discover the contents of any of them.

List the Organizations in a vCloud

The response to a login request includes a list of the organizations to which the authenticated user has access.

If an authenticated client needs to retrieve this list, it can make a GET request to the URL shown in the href attribute of the OrgList that was returned in the response to its original login request. To retrieve the OrgList returned in Example 2‐1 on page 21, an authenticated client would issue the following request:

GET http://vcloud.example.com/api/v1.0/org/

For more information, see “Logging In and Getting an Organization List” on page 21.

List the Contents of an Organization

A vCloud organization is a high‐level abstraction that provides a unit of administration for objects and

resources. As viewed by a user, an organization (represented by an Org element) can contain Catalog, Network, and vDC elements. If there are any queued, running, or recently completed tasks owned by a member

of the organization, it also contains a TasksList element. As viewed by an administrator, an organization also

contains users, groups, and other information. For more information, see “Org” on page 151 and “AdminOrg”

on page 180.

A client can obtain a list of organizations in a vCloud by logging in to the server to get an OrgList (see “Authentication” on page 18). This lists includes only those organizations to which the logged‐in user has

access. The client can use a URL from this list to make an HTTP GET request that returns an Org document in

the response body. This document, a representation of the organization object, includes links to objects that the

organization contains and metadata about the organization itself. Example 3‐1 shows such a request and

response.

Example 3-1. List the Contents of an Organization

Request:


Response:

200 OKContent-Type: application/vnd.vmware.vcloud.org+xml...<Org name="ExampleOrg" type="application/vnd.vmware.vcloud.org+xml"

href="http://vcloud.example.com/api/v1.0/org/5" ...><Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml"

href="http://vcloud.example.com/api/v1.0/catalog/32" name="MainCatalog"/><Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml"

href="http://vcloud.example.com/api/v1.0/catalog/32/controlAccess/"/><Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml"

href="http://vcloud.example.com/api/v1.0/catalog/32/action/controlAccess/"/><Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml"

href="http://vcloud.example.com/api/v1.0/catalog/37" name="Shared Catalog"/><Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml"


href="http://vcloud.example.com/api/v1.0/catalog/37/action/controlAccess/"/><Link rel="down" type="application/vnd.vmware.vcloud.vdc+xml"

href="http://vcloud.example.com/api/v1.0/vdc/5" name="ExampleVdc01"/><Link rel="down" type="application/vnd.vmware.vcloud.tasksList+xml"

href="http://vcloud.example.com/api/v1.0/tasksList/5"/>

VMware, Inc. 35

Chapter 3 Browsing

<Link rel="down" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/14" name="IsolatedOrgNet"/>

<Link rel="down" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/54" name="Internet"/>

<Description>Example Corp’s Primary Organization</Description></Org>

This response shows that the organization contains these objects, each of which is referenced by a Link whose

rel attribute has a value of down (indicating that the link references an object contained by the organization):

A catalog named MainCatalog, whose URL is http://vcloud.example.com/api/v1.0/catalog/32

A catalog named SharedCatalog, whose URL is http://vcloud.example.com/api/v1.0/catalog/37

A link to the organization’s TasksList

A vDC named ExampleVdc01 whose URL is http://vcloud.example.com/api/v1.0/vdc/5

Two networks: one named IsolatedOrgNet whose URL is

http://vcloud.example.com/api/v1.0/network/14, and one named Internet whose URL is

http://vcloud.example.com/api/v1.0/network/54

Action links that enable an administrator to control access to the catalogs

List the Contents of a Catalog

A client can use the href value from any of the rel="down" links in an Org body to get more information

about the object to which the link refers, as shown in Example 3‐2, which requests more information about one

of the catalogs in the organization.

Example 3-2. List the Contents of a Catalog

Request:

GET http://vcloud.example.com/api/v1.0/catalog/32

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.catalog+xml...<Catalog name="MainCatalog" type="application/vnd.vmware.vcloud.catalog+xml"

href="http://vcloud.example.com/api/v1.0/catalog/32" ...><Link rel="up" type="application/vnd.vmware.vcloud.org+xml"

href="http://vcloud.example.com/api/v1.0/org/5"/><Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml"

href="http://vcloud.example.com/api/v1.0/catalog/32/catalogItems"/><Description>Main Org Catalog</Description><CatalogItems>

<CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu Template with vsftpd" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/>

<CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu Boot Floppy" href="http://vcloud.example.com/api/v1.0/catalogItem/222"/>

<CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu ISO Image" href="http://vcloud.example.com/api/v1.0/catalogItem/223"/>

...</CatalogItems><IsPublished>true</IsPublished>

</Catalog>


36 VMware, Inc.

This response body includes:

A Link element that references the organization that contains this catalog:

<Link rel="up" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/5"/>

A Link element that you can use to add an item to the catalog:

<Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/catalogItems"/>

Several CatalogItem elements. Each of these elements includes an href attribute whose value is a URL

that you can GET to obtain more information about the item, as shown in Example 3‐3.

An IsPublished element whose value indicates whether this catalog is visible to other organizations.

For more information about creating catalogs and managing their contents, see “Cataloging vApp Templates

and Media Images” on page 54 and “Catalog Administration” on page 107. For more information about the

Catalog element schema, see “Catalog” on page 160.

Get Information About a CatalogItem

A CatalogItem element can reference a vApp template or a media object. Requests to get more information

about a CatalogItem return a CatalogItem document that includes:

The URL of the referenced object

Link elements that enable an authorized user to modify or remove the CatalogItem

An Entity element that includes the href, type, and name of the object that the CatalogItem references. An Entity can appear in at most one Catalog.

Optional Property elements, each of which is a key=value pair. An organization can use Property elements to implement a key‐based lookup scheme for catalog items.

Example 3-3. Get Information About a CatalogItem

Request:

GET http://vcloud.example.com/api/v1.0/catalogItem/221

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.catalogItem+xml...<CatalogItem name="Ubuntu Template with vsftpd"

href="http://vcloud.example.com/api/v1.0/catalogItem/221" ...><Link rel="edit" type="application/vnd.vmware.vcloud.catalogItem+xml"

href="http://vcloud.example.com/api/v1.0/catalogItem/221"/><Link rel="remove" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/><Description>Ubuntu Template with vsftpd</Description><Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"

type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/>

<Property key="Company">Example</Property></CatalogItem>

VMware, Inc. 37

Chapter 3 Browsing

List the Contents of a vDC

The response in Example 3‐1 also contains several Vdc elements, each of which represents a vDC object.

Example 3‐4 shows a request to browse one of those vDCs and shows a subset of the response.

Example 3-4. List the Contents of a vDC

Request:

GET http://vcloud.example.com/api/v1.0/vdc/5

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.vdc+xml...<Vdc name="ExampleVdc01" type="application/vnd.vmware.vcloud.vdc+xml"

href="http://vcloud.example.com/api/v1.0/vdc/5" ...><Link rel="up" type="application/vnd.vmware.vcloud.org+xml"

href="http://vcloud.example.com/api/v1.0/org/5"/><Link rel="add" type="application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml"

href="http://vcloud.example.com/api/v1.0/vdc/5/action/uploadVAppTemplate"/><Link rel="add" type="application/vnd.vmware.vcloud.media+xml"

href="http://vcloud.example.com/api/v1.0/vdc/5/media"/><Link rel="add" type="application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml"

href="http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate"/>

<Link rel="add" type="application/vnd.vmware.vcloud.cloneVAppParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/cloneVApp"/>

<Link rel="add" type="application/vnd.vmware.vcloud.captureVAppParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/captureVApp"/>

<Link rel="add" type="application/vnd.vmware.vcloud.composeVAppParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/composeVApp"/>

<AllocationModel>AllocationPool</AllocationModel><Description>Example Corp. Primary vDC</Description><StorageCapacity>

<Units>MB</Units><Allocated>1000</Allocated><Limit>1000</Limit><Used>512</Used><Overhead>0</Overhead>

</StorageCapacity><ComputeCapacity>

<Cpu><Units>MHz</Units><Allocated>100</Allocated><Limit>100</Limit><Used>32</Used><Overhead>0</Overhead>

</Cpu><Memory>

<Units>MB</Units><Allocated>100</Allocated><Limit>100</Limit><Used>64</Used><Overhead>0</Overhead>

</Memory></ComputeCapacity><ResourceEntities>

<ResourceEntity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/>

<ResourceEntity href="http://vcloud.example.com/api/v1.0/media/112" type="application/vnd.vmware.vcloud.media+xml" name="Ubuntu Boot Floppy"/>

<ResourceEntity href="http://vcloud.example.com/api/v1.0/media/113" type="application/vnd.vmware.vcloud.media+xml" name="Ubuntu ISO Image"/>


38 VMware, Inc.

<ResourceEntity href="http://vcloud.example.com/vApp/vapp-413" type="application/vnd.vmware.vcloud.vApp+xml" name="Example Corp. CRM"/>

...</ResourceEntities><AvailableNetworks>

<Network href="http://vcloud.example.com/api/v1.0/network/14" type="application/vnd.vmware.vcloud.network+xml" name="IsolatedOrgNet"/>

<Network href="http://vcloud.example.com/api/v1.0/network/54" type="application/vnd.vmware.vcloud.network+xml" name="Internet"/>

</AvailableNetworks><NicQuota>0</NicQuota><NetworkQuota>0</NetworkQuota><VmQuota>0</VmQuota><IsEnabled>true</IsEnabled>

</Vdc>

The response is a detailed description of the vDC and its contents. It includes:

Link elements whose rel attribute has a value of add. Each of these links has an href attribute whose

value is a URL that a client can use to add vApps, vApp templates, and media images to vDC inventory.

Several methods of adding inventory are supported, including upload, clone, and compose.

ResourceEntity elements that reference vApps that have been instatiated in or imported to this vDC,

and vApp templates and virtual media images that have been uploaded to the vDC.

A list of organization networks that are available in the vDC.

Other metadata, including quota and vDC state information.

For more information, see “Vdc” on page 152.

Getting More Information About an ObjectAn object in a vCloud can be represented by links in various types of XML containers. Regardless of where the

link appears, the object reference it contains (its href attribute value) is always the same. An organization

network can be represented by a link with rel="down" in an organization, or as a member of the

AvailableNetworks element of a vDC.

Catalogs provide a level of indirection for references to media images and vApp templates. A vApp template

or media image can be referenced by a CatalogItem in a catalog or a ResourceEntity in a vDC. The CatalogItem shown in Example 3‐2, a VAppTemplate whose URL is

http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate‐111, is also contained by the vDC

referenced in Example 3‐4. In the Vdc body, the VAppTemplate is represented as ResourceEntity element,

which includes a link (the value of the href attribute) to the template. The Catalog, on the other hand, contains only CatalogItem elements, each of which includes a link that a client can use to get more

information about the object that the CatalogItem represents. Both the ResourceEntity in the Vdc and the CatalogItem in the Catalog refer to the same vApp template. The ResourceEntity element includes a link

that a client can use to GET a representation of the vApp, but a client must first GET a CatalogItem to obtain that kind of link, which is not contained in the Catalog itself.

A ResourceEntity element appears in a Vdc element as soon as the underlying vApp template or media

image has been created. References to those objects do not appear in a catalog until the catalog owner adds

them to it. In most cases, the objects cannot be used until they have been added to a catalog.

Get Information About a Media Image

A client can discover the URL of a media image by browsing in a catalog and examining a CatalogItem to find the Entity element that references the image, or by browsing in a vDC for a ResourceEntity element

that references the image. After client has the image’s URL, it can use it as the target of a GET request, as shown

in Example 3‐5.

If the media image has been included in a catalog, the Media element in the response includes a link to the

CatalogItem that references it.

VMware, Inc. 39

Chapter 3 Browsing

Example 3-5. Get Information About a Media Image

Request:

GET http://vcloud.example.com/api/v1.0/media/254

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.media+xml...<Media xmlns="http://www.vmware.com/vcloud/v1" size="242131" imageType="iso" status="1"

name="sql2000.iso" type="application/vnd.vmware.vcloud.media+xml" href="http://vcloud.example.com/api/v1.0/media/254" ... >


<Link rel="catalogItem" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/211"/>

<Link rel="remove" href="http://vcloud.example.com/api/v1.0/media/123"/><Link rel="edit" type="application/vnd.vmware.vcloud.media+xml"

href="http://vcloud.example.com/api/v1.0/media/123"/><Description>ISO Database Image</Description></Media>

Get Information About a vAppTemplate

A client can discover the URL of a vApp template by browsing in a catalog and examining a CatalogItem to find the Entity element that references the template, or by browsing in a vDC for a ResourceEntity element

that references the template. After client has the template’s URL, it can use it as the target of a GET request, as

shown in Example 3‐6, which uses the href of the CatalogItem returned in Example 3‐3.

Example 3-6. Get Information About a vAppTemplate

Request:

GET http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.vAppTemplate+xml...<VAppTemplate ovfDescriptorUploaded="true" status="8" name="Ubuntu Template with vsftpd"

type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111" ... >

<Description>Description of Ubuntu Template with vsftpd</Description><Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml"

href="http://vcloud.example.com/api/v1.0/vdc/10"/><Link rel="catalogItem" type="application/vnd.vmware.vcloud.catalogItem+xml"

href="http://vcloud.example.com/api/v1.0/catalogItem/221"/><Link rel="remove" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/><Link rel="edit" type="application/vnd.vmware.vcloud.vAppTemplate+xml"

href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/><Link rel="ovf" type="text/xml"

href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111/ovf"/><Children>

...</Children>

</VAppTemplate>


40 VMware, Inc.

Get Information About a vApp or Virtual Machine

Catalogs cannot contain references to vApps or the virtual machines (Vm objects) that they contain. A client can discover the URL of a vApp by browsing in a vDC for a ResourceEntity element that references it. After

client has the template’s URL, it can use it as the target of a GET request, as shown in Example 2‐8 on page 39

to retrieve the vApp representation and the Vm elements it contains.

Get Information About a Network

Network (OrgNetwork) elements can be contained by Org and Vdc elements. If an organization contains any

networks, each one is referenced by a Link element where rel="down" in the Org body. Each organization network is a member of the AvailableNetworks element in each of the organization’s vDCs.

To get information about a network, make a GET request to its URL, as shown in Example 3‐7.

Example 3-7. Get Information About a Network

Request:

GET http://vcloud.example.com/api/v1.0/network/54

Response:

200 OK Content-Type: application/vnd.vmware.admin.network+xml...<OrgNetwork xmlns="http://www.vmware.com/vcloud/v1" name="Internet"

type="application/vnd.vmware.admin.network+xml" ref="http://vcloud.example.com/api/v1.0/admin/network/54" ...>

<Link rel="alternate" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/54"/>

<Link rel="edit" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/54"/>

<Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/network/54"/><Link rel="up" type="application/vnd.vmware.admin.organization+xml"

href="http://vcloud.example.com/api/v1.0//org/26"/><Description>Bridged to the Public Internet</Description><Configuration>

<IpScope><IsInherited>true</IsInherited><Gateway>10.147.56.253</Gateway><Netmask>255.255.255.0</Netmask><Dns1>10.147.115.1</Dns1><Dns2>10.147.115.2</Dns2><DnsSuffix>example.com</DnsSuffix><IpRanges>

<IpRange><StartAddress>10.147.56.1</StartAddress><EndAddress>10.147.56.255</EndAddress></IpRange>

</IpRanges></IpScope><ParentNetwork type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1"

href="http://vcloud.example.com/api/v1.0/admin/network/7"/><FenceMode>bridged</FenceMode>

</Configuration></OrgNetwork>

VMware, Inc. 41

4

The vCloud API supports upload and download of OVF packages, and upload of media images. Transfer

operations are characterized as uploads when the operation transfers content from the local host to a remote

one, and as downloads when the local host requests the transfer of content from a remote host. Uploads are

typically initiated by a POST request, and downloads by a GET request. Uploads and downloads are

facilitated by the vCloud transfer service, which provides temporary storage for files.

The vCloud API also supports a clone operation that copies vApps, vApp templates, or media images. The

clone operation also allows you to specify that the source object be deleted after the operation completes,

which effectively moves or renames the source object.

After they have been uploaded or cloned, templates and media images can be added to catalogs as needed.


“Summary of Provisioning Requests” on page 41

“Upload OVF to Create a vApp Template” on page 42

“View the OVF Descriptor of a vApp Template” on page 47

“Download a vApp Template as OVF” on page 47

“Upload a Media Image” on page 50

“Copying and Moving” on page 50

“Changing a Name or Description” on page 53

“Delete a vAppTemplate, vApp, or Media Image” on page 54

“Cataloging vApp Templates and Media Images” on page 54

“Controlling Access” on page 56

Summary of Provisioning RequestsTable 4‐1 summarizes provisioning requests supported in this release. The table uses the following

conventions:

API‐URL is a URL of the form http://vcloud.example.com/api/v1.0.

id is an integer.

Provisioning 4

Table 4-1. Summary of Provisioning Requests


Upload OVF to Create a vApp Template

POST API‐URL/vdc/id/action/uploadVAppTemplate

UploadVAppTemplateParams VAppTemplate

Download a vApp Template as OVF

GET download‐URL None Depends on file type


42 VMware, Inc.

Upload OVF to Create a vApp TemplateA vCloud API client that has access to an OVF package can use a simple workflow to upload the package and

create a vApp template.

1 The client POSTs an initial request that specifies a name for the template, a transfer format for the data,

and an optional description.

2 The server returns an unresolved (status="0") vAppTemplate document that includes an upload URL

for the OVF package.

3 The client uses an HTTP PUT request to upload the OVF package descriptor (the .ovf file) to the upload

URL.

4 The server reads the descriptor and constructs a complete vAppTemplate document (one that includes an

upload URL for each file listed in the References section of the descriptor). While the server is constructing

this document, the client makes periodic requests for it and examines the response for additional upload

URLs. When the response contains any upload URLs beyond the one returned in Step 2, template is

complete

5 The client uses HTTP PUT requests to upload each of the files.

6 If the OVF package includes a manifest file, the entire upload is validated against the contents of the

manifest file.

Enable a vApp Template for Download

POST API‐URL/vAppTemplate/vAppTemplate‐id/action/enableDownload

None Task

Disable a vApp Template for Download

POST API‐URL/vAppTemplate/vAppTemplate‐id/action/disableDownload

None 204 No Content

Upload a Media Image POST API‐URL/vdc/id/media Media Media

Copy or Move a Media Image

POST API‐URL/vdc/id/action/cloneMedia CloneMediaParams Media

Copy or Move a vApp Template

POST API‐URL/vdc/id/action/cloneVAppTemplate

CloneVAppTemplateParams VAppTemplate

Copy or Move a vApp POST API‐URL/vdc/id/action/cloneVApp CloneVAppParams VApp

Change the Name or Description of a vAppTemplate

PUT API‐URL/vAppTemplate/vappTemplate‐id VAppTemplate Task

Change the Name or Description of a vApp

PUT API‐URL/vApp/vapp‐id VApp Task

Change the Name or Description of a Media Image

PUT API‐URL/media/id Media Task

Delete a vAppTemplate, vApp, or Media Image

DELETE object‐URL None Task

Add an Item to a Catalog POST API‐URL/catalog/id/catalogItems CatalogItem CatalogItem

Remove an Item from a Catalog

DELETE API‐URL/catalog/id/catalogItem/id

None 204 No content

Control Access to Catalogs POSTAPI‐URL/catalog/id/action/controlAccess

ControlAccessParams ControlAccessParams

Table 4-1. Summary of Provisioning Requests (Continued)


VMware, Inc. 43

Chapter 4 Provisioning

Both monolithic and ranged (chunked) PUTs are supported. After starting an upload, a client can make

periodic requests to determine its progress. After all the files are uploaded (and validated if a manifest is

present), the server processes the uploads. When processing is complete, the server sets the value of the

template’s status attribute to 8, indicating that the template is ready for use. (This status value indicates that

all of the virtual machines in the template are powered off. For more information, including a complete list of

possible status values and their meanings, see “status” on page 144.)

Restrictions on Uploaded Content

This release of the vCloud API imposes the following restrictions on uploaded OVF content:

You can upload either OVF 1.0 or OVF 1.1 content. OVF 1.1 packages are converted to OVF 1.0 for

download, and any OVF 1.1 content is lost.

You cannot upload a compressed OVF package.

If you upload an OVF package in which any VirtualSystem element has an ovf:id attribute value that is longer than 13 characters, the name of the Vm that represents the VirtualSystem in the vAppTemplate created by the upload is rewritten as the first 13 characters of the ovf:id attribute followed by three

digits. For example, NewVirtualMachine1 and NewVirtualMachine2 become NewVirtualMa001 and

NewVirtualMa002.

Initiate the Upload

To initiate the upload, a client makes an HTTP POST request specifying a target vDC and an

uploadVAppTemplate action. The request body, shown in Example 4‐1, is an UploadVAppTemplateParams element.

Example 4-1. uploadVappTemplate Request

POST http://vcloud.example.com/api/v1.0/vdc/5/action/uploadVAppTemplateContent-Type: application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml

<UploadVAppTemplateParams name="Ubuntu Template" xmlns="http://www.vmware.com/vcloud/v1" ><Description>Ubuntu vApp Template</Description>

</UploadVAppTemplateParams>

This request creates a new VAppTemplate object in the target vDC and returns the objectʹs XML representation

in a response, as shown in Example 4‐2.

Example 4-2. Unresolved vAppTemplate Body with Upload URL for OVF Descriptor

201 CreatedContent-Type: application/vnd.vmware.vcloud.vAppTemplate+xml

<VAppTemplate name="Ubuntu Template" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268" status="0" ovfDescriptorUploaded="false" type="application/vnd.vmware.vcloud.vAppTemplate+xml" ... >


...<Description>Ubuntu vApp Template</Description><Files>

<File name="descriptor.ovf" bytesTransferred="0"><Link rel="upload:default"

href="http://vcloud.example.com/transfer/.../descriptor.ovf"/></File>

</Files></VAppTemplate>


44 VMware, Inc.

The response body includes the following attributes:

An href attribute whose value is a link to the newly created vApp template object.

An ovfDescriptorUploaded attribute with a value of false, indicating that the OVF descriptor file has not yet been uploaded

A status attribute with a value of 0, indicating that the file references in the descriptor have not yet been

uploaded. (A VAppTemplate with a status of 0 is said to be unresolved.)

It also includes a File element with an upload URL (rel="upload:default") for the OVF descriptor. The name attribute of this File element has been created by the server and specifies a container that the server has

created to receive the contents of the descriptor. It has no relation to the file name of the descriptor in the

client’s file system.

The client uploads the OVF descriptor by making a PUT request to the upload URL, and supplying the

descriptor’s contents as an Envelope element in the request body. The server responds with a 200 OK status,

as shown in Example 4‐3.

Example 4-3. Upload OVF Descriptor

Request:

PUT http://vcloud.example.com/transfer/.../descriptor.ovfContent-Type text/xml...<Envelope ... >

...</Envelope>

Response:

200 OK

After the descriptor is uploaded, the server validates it and, if it is valid, creates upload URLs for each of the

files it references. To track the progress of this operation, the client can make periodic GET requests to the

vAppTemplate URL. When the operation is complete, the response to this kind of request includes additional

File elements beyond the one already created for the descriptor, as shown in Example 4‐4.

Example 4-4. GET vAppTemplate with Upload URLs

Request:


Response:

200 OKContent-Type: application/vnd.vmware.vcloud.vAppTemplate+xml...<VAppTemplate ovfDescriptorUploaded="true" status="0" name="Ubuntu Template"

href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268" type="application/vnd.vmware.vcloud.vAppTemplate+xml" ...>


...<Description>Ubuntu vApp Template</Description><Files>

<File size="3940" bytesTransferred="3940" name="descriptor.ovf"><Link rel="upload:default"

href="http://vcloud.example.com/transfer/.../descriptor.ovf"/></File>

VMware, Inc. 45


<File size="1950489088" bytesTransferred="0" name="disk0.vmdk"><Link rel="upload:default" href="http://vcloud.example.com/transfer/.../disk0.vmdk"/>

</File></Files>

</VAppTemplate>

In this example, the ovfDescriptorUploaded attribute has a value of true and the status attribute has a value of 0. If the descriptor fails validation, the status is set to ‐1, and the template contains a Task element

whose Error element indicates the reason for the failure.

Each of the File elements includes an upload link (<Link rel="upload:default" ... />) and several attributes:

size. The file size, taken from the size attribute of the File element in the OVF descriptor.

bytesTransferred. For all file references other than the descriptor, this attribute is initially set to a value of

0 indicating that the upload has not yet begun. In the File reference to the descriptor, the value of the bytesTransferred attribute is equal to the value of the size attribute, indicating that all the bytes in the descriptor have been transferred.

name. The file name, taken from the href attribute of the File element in the OVF descriptor.

Including a Manifest

Some OVF packages include a manifest document, which specifies a checksum for each file in the package. If

you are uploading a package that includes a manifest file, add a manifestRequired="true" attribute to the request body, as shown in Example 4‐5.

Example 4-5. uploadVappTemplate Request for an OVF Package That Includes a Manifest

POST http://vcloud.example.com/api/v1.0/vdc/5/action/uploadVAppTemplateContent-Type: application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml

<UploadVAppTemplateParams name="Ubuntu Template" manifestRequired="true" xmlns="http://www.vmware.com/vcloud/v1" >

<Description>Ubuntu vApp Template</Description></UploadVAppTemplateParams>

When you specify that a manifest is required, the set of File elements returned after you upload the OVF

descriptor includes one for the manifest itself. After all the files are uploaded, each file is checked by the server

to verify that its checksum matches the one stated in the manifest. If any checksums do not match, the

template’s status attribute is set to ‐1 and the template contains a Task element whose Error element

indicates the reason for the failure.

Uploading the Files

Information from the server’s response in Example 4‐3 enables the client to construct a series of PUT requests,

one for each File in the list, that upload the files referenced by the template. Each request specifies an upload

URL and a content length in bytes.

Example 4‐6 shows an upload request for one of the files required by an OVF package. The upload request is

simply a few header lines, followed by the serialized file content.


46 VMware, Inc.

Example 4-6. Uploading File Data

Request:

PUT http://vcloud.example.com/transfer/.../disk0.vmdkContent-length: 1950489088

...serialized contents of file disk0.vmdk...

EOF

Response:

200 OK

To monitor the progress of an upload, a client can use an HTTP GET request specifying the VAppTemplate URL that was returned in the upload map. The response is the same upload map. After all the files have been

uploaded, the response includes a Task that the vAppTemplate creates to monitor the events leading up to its

resolution, and an updated value for the bytesTransferred attribute of each File element, as shown in

Example 4‐7. (The complete VAppTemplate body is returned. This example omits most of it for clarity.)

Example 4-7. Monitoring the Progress of an Upload

Request:


Response:

200 OK<VAppTemplate name="Ubuntu Template"

href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268" status="0" ... >

...<Files>

...<File size="1950489088" bytesTransferred="500000000" name="disk0.vmdk">

<Link rel="upload:default" href="http://vcloud.example.com/transfer/.../disk0.vmdk"/></File>

</Files>...

</VAppTemplate>

If the response to an upload progress request indicates that the upload terminated before it was complete (for

example, if repeated progress requests show the same bytesTransferred value), a client can use the size and bytesTransferred values from the response to construct a ranged PUT of the remaining contents, as

shown in Example 4‐8.

Example 4-8. Ranged PUT to Complete a Partial Upload

Request:

PUT http://vcloud.example.com/transfer/.../disk0.vmdkkContent-Range: bytes 500000000-1950489087/1950489088Content-length: 1450489088

...serialized contents of specified range...

EOF

NOTE Ranged PUT requests are typically required for very large uploads, especially when network

bandwidth or latency could cause the operation to time out.

VMware, Inc. 47


Response:

200 OK

View the OVF Descriptor of a vApp TemplateThe representation of a resolved vApp template includes a link to its OVF descriptor.

<Link rel="ovf" type="text/xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268/ovf"/>

A GET request specifying the URL in the href value of this Link returns the descriptor, as shown in

Example 4‐9. Only resolved VAppTemplate elements include this link. To get the OVF descriptor that defines

a vApp or virtual machine, you must start with the template from which it was created.

When you view the OVF descriptor of a vApp template, it includes deployment‐specific information.

Example 4-9. View the OVF Descriptor of a vApp Template

Request:

GET http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268/ovf

Response:

200 OKContent-Type text/xml...<Envelope ...>

<DiskSection><Info>Virtual disk information</Info><Disk ovf:capacity="100" ovf:capacityAllocationUnits="byte * 2^20" ovf:diskId="vmdisk1"

ovf:fileRef="file1" ovf:format="http://www.vmware.com/interfaces/specifications/vmdk.html#streamOptimized"/>

</DiskSection><VirtualSystem ... ovf:id="Ubuntu Template">

...</VirtualSystem>

</Envelope>

Download a vApp Template as OVFA vAppTemplate can be downloaded as an OVF package. After locating the template by browsing a catalog

or vDC, a client can request that the template be enabled for download. This operation constructs a download

URL for the template’s OVF descriptor file and adds it to the template. A client can download the descriptor

from this URL, examine it to discover the download URLs of the files it references, then make a series of GET

requests that download the files themselves.

When you download a vApp template as OVF, all deployment‐specific information is removed from the OVF.

NOTE The OVF descriptor does not include any File references. These are removed by the server after the

template is resolved and recreated when the template is enabled for download.


48 VMware, Inc.

Enable a vApp Template for Download

A vApp template must be explicitly enabled for download by an administrator or privileged user.

Example 4‐10 shows such a request. The response is a Task element. The time required for the task to complete

is determined by the number and size of the files comprising the template.

Example 4-10. Enable a vApp Template for Download

Request:

POST http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268/action/enableDownload

Response:

202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Enabling download of Virtual Application Template Ubuntu Template (268)" ...

>...

</Task>

When the enableDownload task completes, the template’s files are available from the vCloud transfer service,

and the vAppTemplate includes a Link element that contains a URL from which the template’s OVF descriptor

can be downloaded, as shown in Example 4‐11.

Example 4-11. vApp Template with DownloadURL for OVF Descriptor

Request:

GET http://vcloud.example.com/api/vAppTemplate/vappTemplate-268

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.vAppTemplate+xml...<VAppTemplate ovfDescriptorUploaded="true" status="8" name="Ubuntu Template"

type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268" ...>

...<Link type="text/xml" rel="download:default"

href="http://vcloud.example.com/transfer/.../descriptor.ovf"/>...

</VAppTemplate>

The client uses this download:default URL in a GET request that downloads the OVF descriptor (as shown

in Example 4‐12), then examines the contents of the descriptor to discover the href values for the remaining

files in the template’s References container.

Example 4-12. Downloading the OVF Descriptor

Request:

GET http://vcloud.example.com/transfer/..../descriptor.ovf

Response:

200 OK...<Envelope ...>

<References><File ovf:href="disk0.vmdk" ovf:id="file1" ovf:size="1950489088"/>

</References><DiskSection>

<Info>Virtual disk information</Info>

VMware, Inc. 49


<Disk ovf:capacity="100" ovf:capacityAllocationUnits="byte * 2^20" ovf:diskId="vmdisk1" ovf:fileRef="file1" ovf:format="http://www.vmware.com/interfaces/specifications/vmdk.html#streamOptimized"/>

</DiskSection><VirtualSystem ... ovf:id="Ubuntu Template">

...</VirtualSystem>

</Envelope>

In this example, the descriptor references only one file:

<File ovf:href="disk0.vmdk" ovf:id="file1" ovf:size="1950489088"/>

The href attribute of the File element is the path to the file relative to the location of the descriptor itself. To

retrieve this file from the server, the client must make a GET request to a URL that it constructs with a simple

two‐step algorithm:

1 Start with the URL that was contained in the download:default attribute of the Link to the descriptor that was contained by template. (See Example 4‐11.)

2 Replace the final component of that URL with the value of the href attribute of the File in the downloaded OVF descriptor.

The result of this process, using the responses in Example 4‐11 and Example 4‐12, is the request URL shown

in Example 4‐13.

Example 4-13. Downloading a Referenced File

Request:

GET http://vcloud.example.com/transfer/..../disk0.vmdk

Response:

200 OK...

...serialized contents of file disk0.vmdk...

EOF

When the download completes, the vApp template is available on the client as an OVF package.

Disable a vApp Template for Download

An administrator or authorized user can use the disableDownload action to disable a vApp template for

download, as shown in Example 4‐14. The response is an HTTP 204 (No Content) status.

Example 4-14. Disable a vApp Template for Download

Request:

POST http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268/action/disableDownload

Response:

204 No Content

NOTE Make sure that the downloaded files maintain the same relationship to each other in the local file

system as they had on the transfer server file system. In this case, the descriptor and disk0.vmdk were both

in the same directory (the default arrangement).


50 VMware, Inc.

After the disableDownload request completes, the template’s files are removed from the transfer server, and

the Link element that contains the download:default URL no longer appears in the vAppTemplate body.

Upload a Media ImageThe vCloud API supports uploading virtual media such as CD‐ROM and floppy disk images. The workflow

for these procedures is similar to that described for vApp template uploads; the client POSTs a request to the

server that includes information about a virtual media item it intends to upload, and the server responds with

an upload URL, which the client can use to do a monolithic or ranged PUT of the file contents.

Example 4‐15 shows a request to upload a CD‐ROM image in ISO format. The request body is a Media element, which specifies the name, size, and type of the file.

Example 4-15. Request to Upload an ISO Image

POST http://vcloud.example.com/api/v1.0/vdc/5/mediaContent-Type: application/vnd.vmware.vcloud.media+xml

<Media name="database.iso" size="242131" imageType="iso" xmlns="http://www.vmware.com/vcloud/v1"><Description>ISO database image</Description>

</Media>

The server returns a Media representation that includes a single File element, as shown in Example 4‐16. The

client responds with a PUT request, sending serialized file data to the File element’s upload:default URL. Example 4‐6 shows a similar request.

Example 4-16. Server Response to Request to Upload an ISO Image

Content-Type: application/vnd.vmware.vcloud.media+xml201 Created

<Media name="database.iso" size="242131" status="0" imageType="iso" href="http://vcloud.example.com/api/v1.0/media/254" type="application/vnd.vmware.vcloud.media+xml" ...>


<Description>ISO database image</Description><Files>

<File name="database.iso" size="242131" bytesTransferred="0" <Link rel="upload:default" href="http://vcloud.example.com/.../database.iso"/>

</File></Files>

</Media>

During the upload, the value of the bytesTransferred attribute of the File element indicates upload

progress. When the upload is complete, the value of the status attribute is set to 1, and the Files element is

no longer included in the Media representation.

Copying and MovingThe vCloud API provides object‐specific copy operations for media images, vApp templates, and vApps.

These operations support creating a copy of the object in the same vDC or in another vDC within the same

organization. Each copy operation supports an option to delete the source object after the copy is complete,

which effectively moves the source object to another vDC, or renames it within the same vDC. The vCloud API

does not include an explicit move operation.

NOTE Downloading media images is not supported in this release of Cloud Director.

VMware, Inc. 51


When you move an object by copying it and deleting its source, an intermediate object is created in the target

vDC, as part of the following sequence of events.

1 The source object is coped to an intermediate object whose name is a combination of the object name and

a UUID.

2 The source object is deleted.

3 The intermediate object is renamed with the name specified for the target object in the copy request.

Copy or Move a Media Image

The cloneMedia request makes a copy of the media image referenced in the Source element of the request

body. The request specifies a new name and, optionally, a new description for the copy. The request can

optionally include an IsSourceDelete element whose value specifies whether the source media image is

deleted after the copy is complete. If IsSourceDelete is missing from the request body or present with a

value of false, the source object remains in place after the copy is complete. Setting IsSourceDelete to true effectively moves the media image.

Example 4‐17 copies the virtual media image referenced by http://vcloud.example.com/api/v1.0/media/254 to

the vDC referenced by http://vcloud.example.com/api/v1.0/vdc/5 and provides a new name and description

for the copy. The source image remains in place after the copy is complete.

Example 4-17. Copy a Virtual Media Image

Request:

POST http://vcloud.example.com/api/v1.0/vdc/5/action/cloneMediaContent-Type: application/vnd.vmware.vcloud.cloneMediaParams+xml<CloneMediaParams name="databse-backup.iso" xmlns="http://www.vmware.com/vcloud/v1">

<Description>This is a backup copy of the ISO database image</Description><Source href="http://vcloud.example.com/api/v1.0/media/254"/>

</CloneMediaParams>

Response:

201 Created...<Media name="database-backup.iso" size="242131" status="0" imageType="iso"

href="http://vcloud.example.com/api/v1.0/media/277" type="application/vnd.vmware.vcloud.media+xml" ...>

<Link rel="up" href="http://vcloud.example.com/api/v1.0/vdc/5"/><Description>This is a backup copy of the ISO database image</Description><Tasks>

<Task ... operation="Busy Media File cloned(277)" ... >...

</Task></Tasks>

</Media>

Copy or Move a vApp Template

The cloneVAppTemplate request makes a copy of the vApp template referenced in the Source element of the

request body. The request specifies a new name and, optionally, a new description for the copy. The request

can optionally include an IsSourceDelete element whose value specifies whether the source vApp template

is deleted after the copy is complete. If IsSourceDelete is missing from the request body or present with a

value of false, the source object remains in place after the copy is complete. Setting IsSourceDelete to true effectively moves the vApp template.

Example 4‐18 moves the vApp template referenced by

http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate‐111 to the vDC referenced by

http://vcloud.example.com/api/v1.0/vdc/5. Because the IsSourceDelete element in the request body

contains a value of true, the source vApp template is removed after the copy is complete.


52 VMware, Inc.

Example 4-18. Move a vAppTemplate

Request:

POST http://vcloud.example.com/api/v1.0/vdc/5/action/cloneVAppTemplateContent-Type: application/vnd.vmware.vcloud.cloneVAppTemplateParams+xml<CloneVAppTemplateParams name="Ubuntu Copy" xmlns="http://www.vmware.com/vcloud/v1">

<Source href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/><IsSourceDelete>true</IsSourceDelete>

</CloneVAppTemplateParams>

Response:

201 CreatedContent-Type: application/vnd.vmware.vcloud.vAppTemplate+xml...<VAppTemplate ovfDescriptorUploaded="true" status="0" name="Ubuntu Copy"

href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-302" type="application/vnd.vmware.vcloud.vAppTemplate+xml" ...>


...<Tasks>

<Task ... operation="Busy Virtual Application Template Ubuntu Copy (382)" ...>...

</Task></Tasks>

</VAppTemplate>

Copy or Move a vApp

The cloneVApp request makes a copy of the vApp referenced in the Source element of the request body. The

request specifies a new name and, optionally, a new description for the copy. The request can optionally

include an IsSourceDelete element whose value specifies whether the source vApp is deleted after the copy

is complete. If IsSourceDelete is missing from the request body or present with a value of false, the source object remains in place after the copy is complete. Setting IsSourceDelete to true effectively moves the

vApp.

You cannot copy or move a vApp that is deployed.

Example 4‐19 copies the vApp referenced by http://vcloud.example.com/api/v1.0/vApp/vApp‐201 to the vDC

referenced by http://vcloud.example.com/api/v1.0/vdc/5 and provides a new name and description for the

copy. Because the IsSourceDelete element in the request body contains a value of false, the source vApp is unaffected by the copy operation. (The default value of IsSourceDelete is false. The example includes it

for illustrative purposes only.)

The response is a Task element owned by the copy.

Example 4-19. Copy a vApp

Request:

POST http://vcloud.example.com/api/v1.0/vdc/5/action/cloneVAppContent-Type: application/vnd.vmware.vcloud.cloneVAppParams+xml

<CloneVAppParams name="New Linux Server" xmlns="http://www.vmware.com/vcloud/v1"><Description>Cloned from Ubuntu FTP Server</Description><Source href=”http://vcloud.example.com/api/v1.0/vApp/vApp-201”/><IsSourceDelete>false</IsSourceDelete>

</CloneVAppParams>

VMware, Inc. 53


Response:


<VApp name="New Linux Server" status="0" href="http://vcloud.example.com/api/v1.0/vApp/vapp-999" ...>

<Description>Cloned from Ubuntu FTP Server</Description>...<Tasks>

<Task ... operation="Busy Virtual Application New Linux Server Copy (201)" ...>...

</Task></Tasks>

</VApp>

Changing a Name or DescriptionEvery vAppTemplate, vApp, and Media element includes an edit link that a client can use if to change the value of the object’s name attribute or Description element. In each case, the request must include all the

required elements of the object’s representation, even the ones that you are not changing.

Change the Name or Description of a vAppTemplate

Example 4‐20 changes the description of the vApp template shown in Example 3‐6 on page 39.

Example 4-20. Change the Name and Description of a vAppTemplate

Request:

PUT http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml...

<VAppTemplate xmlns="http://www.vmware.com/vcloud/v1 name="Ubuntu 9.10" type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111">

<Description>Ubuntu 9.10 Server Edition, with vsftpd</Description></VAppTemplate>

Response:

202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ...>

...</Task>

Change the Name or Description of a vApp

You can change the name or description of a vApp using a procedure similar to the one shown in

Example 4‐20.


54 VMware, Inc.

Change the Name or Description of a Media Image

Example 4‐21 changes the description of a media image that was created by the copy operation in

Example 4‐17.

Example 4-21. Change the Description of a Media Image

Request:

PUT http://vcloud.example.com/api/v1.0/media/277Content-Type: application/vnd.vmware.vcloud.media+xml...<Media name="database.iso" size="242131" imageType="iso" xmlns="http://www.vmware.com/vcloud/v1">

<Description>New description</Description></Media>

Response:


...</Task>

Delete a vAppTemplate, vApp, or Media ImageYou can use an HTTP DELETE request to delete a vAppTemplate, vApp, or media image. All of these

operations conform to the prototype (DELETE href, where href is the URL of the object you want to delete)

shown in Example 2‐10 on page 30. You cannot delete an object if it is in use. Any object that is being copied

or moved is in use. Other criteria that determine whether an object is in use depend on the object type.

A vApp template is in use if it is being instantiated. After instantiation is complete, the template is no

longer in use.

A vApp is in use if it is deployed.

A media image is in use if it is inserted in a Vm.

Cataloging vApp Templates and Media ImagesAlthough references to vApp templates and media images can be retrieved directly from the vDC to which

they were uploaded, it is a common practice to place references to such assets in one of an organization’s

catalogs. Doing so makes the asset easier to discover, because a catalog can include assets from all vDCs in an

organization. It also provides more flexible administrative control over these assets, because access to catalogs

and the items in them can be restricted to specific users and groups. Assets such as vApp templates are not

enabled for most uses until you include them in a catalog. For example, a vApp template that is not included

in a catalog can be modified but cannot be instantiated. A media image that is not included in a catalog cannot

be used by anyone but its owner.

Add an Item to a Catalog

A catalog can contain references to vApp templates and media images that have been uploaded to any vDC

in an organization. A vApp template or media image can be listed in at most one catalog.

VMware, Inc. 55


To add an item to a catalog

1 Browse the vDCs in an organization to find ResourceEntity elements that reference the item you want

to add to the catalog.

2 Create a CatalogItem element that contains a reference to the item.

Example 3‐4 on page 37 lists a number of ResourceEntity elements in a vDC. To create a CatalogItem that references this one:

<ResourceEntity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/>

follow these guidelines:

The name attribute of the CatalogItem can be the same as the one in the ResourceEntity, or you can make up a new value for name.

The Description element of the CatalogItem can be the same as the Description element for the

object referenced by the ResourceEntity, or you can make up a new Description.

The href attribute of the Entity element in the CatalogItem must have the same value as the href attribute of the ResourceEntity that the CatalogItem references.

Property elements are optional in any CatalogItem. For more information about how these elements

can be used, see Property on page 161.

3 POST the CatalogItem body to the rel="add" URL included in the Catalog body.

Example 4‐22 adds a CatalogItem to the catalog listed in Example 3‐2 on page 35.

Example 4-22. Add an Item to a Catalog

Request:

POST http://vcloud.example.com/api/v1.0/catalog/32/catalogItemsContent-Type: application/vnd.vmware.vcloud.catalogItem+xml<CatalogItem name="Ubuntu Template with vsftpd" xmlns="http://www.vmware.com/vcloud/v1">

<Description>Approved template for public FTP sites</Description><Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/><Property key="Owner">Tech Ops</Property>

</CatalogItem>

Response:

201 CreatedContent-Type: application/vnd.vmware.vcloud.catalogItem+xml...<CatalogItem name="Ubuntu Template with vsftpd"

type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221" ...>

<Link rel="edit" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/>

<Link rel="up" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32"/>

<Link rel="remove" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/><Description>Approved template for public FTP sites</Description><Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/><Property key="Owner">Tech Ops</Property>

</CatalogItem>


56 VMware, Inc.

Remove an Item from a Catalog

A organization administrator or a user with adequate permissions can remove a CatalogItem by making a

DELETE request to the its rel="remove" link. Example 4‐23 removes the CatalogItem created in Example 4‐22.

Example 4-23. Remove a CatalogItem

Request:

DELETE http://vcloud.example.com/api/v1.0/catalogItem/221

Response:

204 No Content

Catalog Links in a VApp Template or Media Image

Every vAppTemplate and Media element that has been added to a catalog contains a rel="catalogItem" link whose href value is the URL of the CatalogItem that references the template or media image (see the

response in Example 3‐6 on page 39). A client can GET that URL and examine the response to find the

rel="up" link in the CatalogItem (see the response in Example 4‐22). This link is a reference to the catalog

that contains the CatalogItem.

Controlling AccessAn organization administrator can use controlAccess links to control access to catalogs and vApps.

Control Access to Catalogs

When you list the contents of an organization, each catalog includes access control links, as shown in

Example 4‐24, which is an excerpt from Example 3‐1 on page 34.

Example 4-24. Access Control Links for a Catalog

<Org ... ><Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml"

href="http://vcloud.example.com/api/v1.0/catalog/32" name="MainCatalog"/><Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml"


href="http://vcloud.example.com/api/v1.0/catalog/32/action/controlAccess/"/><Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml"

href="http://vcloud.example.com/api/v1.0/catalog/37" name="Shared Catalog"/><Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml"


href="http://vcloud.example.com/api/v1.0/catalog/37/action/controlAccess/"/>...

</Org>

For each of the catalogs listed in this excerpt, three links are provided:

A Link with rel="down" that provides the URL for the catalog itself

Another Link with rel="down" that a client can use to retrieve the catalog’s access control settings

A Link with rel="controlAccess" that a client can use to modify the catalog’s access control setting

An organization administrator or privileged user can use these links to view or modify access controls on a

catalog. Example 4‐25 shows the request to view the access control settings for a catalog.

VMware, Inc. 57


Example 4-25. Viewing Access Control Settings for a Catalog

Request:

GET http://vcloud.example.com/api/v1.0/catalog/32/controlAccess/

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.controlAccess+xml...<ControlAccessParams ...>

<IsSharedToEveryone>false</IsSharedToEveryone></ControlAccessParams>

Because the value of IsSharedToEveryone is false, the administrator must grant access to individual users

or groups, specified by reference. In Example 4‐26, the administrator POSTs a modified version of the

ControlAccessParams element received in Example 4‐25 to the catalog’s access control URL. The

modifications populate the AccessSettings container with two AccessSetting elements, each of which

assigns an access level to a specific user.

Example 4-26. Granting Catalog Access to Users

Request:

POST http://vcloud.example.com/api/v1.0/catalog/32/action/controlAccessContent-Type: application/vnd.vmware.vcloud.controlAccess+xml

<ControlAccessParams xmlns="http://www.vmware.com/vcloud/v1"><IsSharedToEveryone>false</IsSharedToEveryone><AccessSettings>

<AccessSetting><Subject type="application/vnd.vmware.admin.user+xml"

href="http://vcloud.example.com/api/v1.0/admin/user/1"/><AccessLevel>FullControl</AccessLevel>

</AccessSetting><AccessSetting>

<Subject type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/6"/>

<AccessLevel>ReadOnly</AccessLevel></AccessSetting>

</AccessSettings></ControlAccessParams>

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.controlaccess+xml...<ControlAccessParams ...>

<IsSharedToEveryone>false</IsSharedToEveryone><AccessSettings>

<AccessSetting><Subject type="application/vnd.vmware.admin.user+xml"

href="http://vcloud.example.com/api/v1.0/admin/user/1"/><AccessLevel>FullControl</AccessLevel>

</AccessSetting><AccessSetting>

<Subject type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/6"/>

<AccessLevel>ReadOnly</AccessLevel></AccessSetting>

</AccessSettings></ControlAccessParams>


58 VMware, Inc.

To specify global access controls that apply to all members of an organization, an organization administrator

can set IsSharedToEveryone to true and specify an access level in the EveryoneAccessLevel element, as

shown in Example 4‐27.

Example 4-27. Granting Catalog Access to Everyone

Request:

POST http://vcloud.example.com/api/v1.0/catalog/32/controlAccessContent-Type: application/vnd.vmware.vcloud.controlAccess+xml...<ControlAccessParams xmlns="http://www.vmware.com/vcloud/v1">

<IsSharedToEveryone>true</IsSharedToEveryone><EveryoneAccessLevel>ReadOnly</EveryoneAccessLevel>

</ControlAccessParams>

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.controlaccess+xml...<ControlAccessParams ...>

<IsSharedToEveryone>true</IsSharedToEveryone><EveryoneAccessLevel>ReadOnly</EveryoneAccessLevel>

</ControlAccessParams>

Access control for vApps is implemented in a similar way. See Example 5‐36 on page 89.

VMware, Inc. 59

5

The vCloud API supports programmatic access to a range of self‐service datacenter operations that allow users

to create, configure, operate, and connect to vApps.


“Summary of Datacenter Operations Requests” on page 59

“vApp Lifecycle” on page 60

“Instantiate a vApp Template” on page 61

“Compose a vApp” on page 65

“Recompose a vApp to Add or Remove Virtual Machines” on page 67

“Capture a vApp to Create a vApp Template” on page 68

“Reconfiguring vApps and Virtual Machines” on page 69

“Deploying and Controlling vApps and Virtual Machines” on page 80

“Control Access to vApps” on page 89

“Retrieve a Task” on page 89

Summary of Datacenter Operations RequestsTable 5‐1 summarizes datacenter operations requests supported in this release. The table uses the following

conventions:


id is an integer

vApp‐or‐Vm‐URL is a URL of the form API‐URL/vApp/vapp‐id (for a vApp object) or

API‐URL/vApp/vm‐id (for a Vm object)

Datacenter Operations 5

Table 5-1. Summary of Datacenter Operations Requests


Instantiate a vApp Template POST API‐URL/vdc/id/action/instantiateVAppTemplate

InstantiateVAppTemplateParams VApp

Retrieve vApp Template CustomizationSection

GET API‐URL/vAppTemplate/vappTemplate‐id/customizationSection

None CustomizationSection

Modify vApp Template CustomizationSection

PUT API‐URL/vAppTemplate/vappTemplate‐id/customizationSection

CustomizationSection Task

Compose a vApp POST API‐URL/vdc/id/action/composeVApp

ComposeVAppParams VApp


60 VMware, Inc.

vApp LifecycleA vApp contains one or more Vm elements, which represent individual virtual machines. It also contains

information that defines operational details for the vApp and the virtual machines it contains. The vApp

lifecycle includes several distinct states:

An OVF package, the form in which vApps are typically made available for download and distribution

A vApp template, created when a client uploads an OVF package to a vDC

Recompose a vApp to Add or Remove Virtual Machines

POST API‐URL/vApp/vapp‐id/action/recomposeVApp

RecomposeVAppParams Task

Capture a vApp to Create a vApp Template

POST API‐URL/vdc/id/action/captureVApp

CaptureVAppParams VAppTemplate

Deploy a vApp or Virtual Machine

POST vApp‐or‐Vm‐URL/action/deploy

DeployVAppParams Task

Undeploy a vApp or Virtual Machine

POST vApp‐or‐Vm‐URL/action/undeploy

UndeployVAppParams Task

Power On a vApp or Virtual Machine

POST vApp‐or‐Vm‐URL/power/action/powerOn

None Task

Power Off a vApp or Virtual Machine

POST vApp‐or‐Vm‐URL/power/action/powerOff

None Task

Reset a vApp or Virtual Machine

POST vApp‐or‐Vm‐URL/power/action/reset

None Task

Suspend a vApp or Virtual Machine

POST vApp‐or‐Vm‐URL/power/action/suspend

None Task

Discard the Suspended State of a vApp or Virtual Machine

POST vApp‐or‐Vm‐URL/action/discardSuspendedState

None Task

Shut Down a vApp or Virtual Machine

POST vApp‐or‐Vm‐URL/power/action/shutdown

None 204 No Content

Reboot a vApp or Virtual Machine

POST vApp‐or‐Vm‐URL/power/action/reboot

None 204 No Content

Insert Media Into a Virtual Machine

POST API‐URL/vApp/vm‐id/media/action/insertMedia

MediaInsertOrEjectParams Task

Eject Media from a Virtual Machine

POST API‐URL/vApp/vm‐id/media/action/ejectMedia

MediaInsertOrEjectParams Task

List Media Devices of a Virtual Machine

GET API‐URL/vApp/vm‐id/virtualHardwareSection/media

None RasdItemsList

Get a Request for User Input GET API‐URL/vApp/vm‐id/question

None VmPendingQuestion

Provide Requested User Input

POST API‐URL/vApp/vm‐id/question/action/answer

VmQuestionAnswer 204 No Content

Get a Screen Thumbnail for a Virtual Machine

GET API‐URL/vApp/vm‐id/screen

None screen thumbnail (Content‐type: image/png)

Get a Screen Ticket for a Virtual Machine

POST API‐URL/vApp/vm‐id/screen/action/acquireTicket

None ScreenTicket

Control Access to vApps POST API‐URL/vApp/vapp‐id/action/controlAccess

ControlAccessParams ControlAccessParams

Retrieve a Task GET API‐URL/task/id None Task

Table 5-1. Summary of Datacenter Operations Requests (Continued)


VMware, Inc. 61

Chapter 5 Datacenter Operations

An undeployed vApp, created when a vApp template is instantiated or a deployed vApp is undeployed.

A deployed vApp, ready to be powered on and operated. You can specify that instantiation include

deployment, power‐on, or both.

Figure 5‐1 illustrates these state transitions.

Figure 5-1. vApp State Transitions

OVF upload and the creation of vApp templates is covered in “Upload OVF to Create a vApp Template” on

page 42.

Instantiate a vApp TemplateA vApp template specifies a set of files, such as virtual disks, that the vApp requires, and a set of abstract

resources, such as CPU, memory, and network connections, that must be allocated to the vApp by the vDC in

which it is deployed. Instantiation creates a vApp from the files specified in the template, and allocates

vDC‐specific bindings for networks and other resources. (These bindings are advisory; they do not guarantee

that the resources will be available when the vApp is deployed.) Instantiation is a prerequisite to deployment.

In the most common use case, a client instantiates a vApp template and immediately deploys it.

descriptor.ovf

OVF package

<VApp Template...status=”8” href=”http://.../vapp Template-3”> ... ...</VApp Template>

instantiate

<VApp...status=”8” deployed=“false” href=”http://.../vapp-9”> ... <Link rel=”deploy”...> ...</VApp>

deploy

disk0.vmdk

upload

vApptemplate

vApp

<VApp...status=”8” deployed=“true” href=”http://.../vapp-9”> ... <Link rel=”power:powerOn”...> ...</VApp>

vApp


62 VMware, Inc.

About Instantiation Parameters

Instantiation parameters allow you to specify certain properties of a vApp, including:

Details of its vApp network (required).

Lease settings for the vApp (optional, if you want to override your organization’s defaults)

Startup and shutdown parameters for the vApp (applicable only if the vApp has multiple children)

Instantiation parameters also include a way to indicate that any terms and conditions (such as license

agreements) contained in the vApp have been accepted.

Instantiation parameters cannot be used to modify a Vm that appears in the vApp’s Chldren container. To change the properties of a Vm, use the reconfiguration links in its Item elements. (See “Reconfiguring vApps

and Virtual Machines” on page 69.)

About vApp Networks

A vApp network is a logical network that defines how the vApp connects to an organization network in the

target vDC. It is specified as part of an instantiateVAppTemplate or composeVApp request, created when

the vApp is deployed, and deleted when the vApp is undeployed. Virtual machines (Vm elements) in the

vApp’s Children collection all connect to this network, as specified in their NetworkConnection elements.

The details of a vApp network are specified in the NetworkConfig element of the

InstantiateVAppTemplateParams request body, and include the following:

A name for the vApp network, specified in the networkName attribute of the NetworkConfig element. If

the template that you are instantiating includes an ovf:NetworkSection element, the value of the

networkName attribute of the NetworkConfig element must match the value of the ovf:name attribute of the ovf:Network element in the template. If the template defines multiple networks, then you must do

the same in the InstantiateVAppTemplateParams request.

A Configuration element that specifies the organization network to which the vApp network connects

and a FenceMode value that controls how those two networks are connected.

Instantiating a vAppTemplate Using Default Parameters

An instantiation request can supply a minimal InstantiateVAppTemplateParams element to specify that

instantiation should use the target vDC’s default bindings (see “Instantiating the Template in the vDC” on

page 24). This type of request can be appropriate for a vApp that has simple requirements for storage,

network, and compute resources. A vApp instantiated in this way can be reconfigured if necessary to correct

problems caused by a default instantiation. For more information, see “Reconfiguring vApps and Virtual

Machines” on page 69.

Instantiating a vApp Template Using Additional Parameters

If a client wants to specify vApp instantiation parameters in detail, rather than relying on vDC defaults, it can

include the details in the body of the instantiateVAppTemplate request.

The instantiation request takes the form of a POST to a vDC’s instantiateVAppTemplate URL. The request body is an InstantiateVAppTemplateParams element.

To obtain the information required in an InstantiateVAppTemplateParams element, the client must take

several steps:

Examine the template’s OVF to discover any EULA sections that it includes. The

InstantiateVAppTemplateParams element can include an AllEULAsAccepted element whose value

indicates whether all EULA terms included in the template were accepted. If a vApp template includes

any EULA sections, AllEULAsAccepted must be set to a value of true. Otherwise, instantiation fails.

Examine the template’s ovf:StartupSection element to verify that the prescribed startup order for

children does not need to be modified.

VMware, Inc. 63


Examine the template’s ovf:NetworkSection element to see whether any networks are defined there. If

the vApp template includes an ovf:Network element, the name you specify for the vApp network must

match the name specified in that element’s ovf:name attribute.

See “About Instantiation Parameters” on page 62.

Verify that your organization’s default lease settings are appropriate for this vApp. If they are not, you can

specify custom lease settings as part of instantiation.

Example 5‐1 shows an instantiation request similar to the one shown in Example 2‐6 on page 25, but includes

an AllEULAsAccepted element that denotes acceptance of terms and conditions embedded in the child Vm elements, and a LeaseSettingsSection element that specifies custom deployment and storage lease terms

for this vApp. It also specifies that the vApp should be deployed and powered on after it is instantiated. (If

you omit the deploy and powerOn attributes, the default value of false is assumed.)

Example 5-1. Instantiating a vApp Template wIth Custom Lease Settings

Request:

POST http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate Content-Type: application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml...<InstantiateVAppTemplateParams name="Linux FTP server" deploy=”true” powerOn=”true”

xmlns="http://www.vmware.com/vcloud/v1" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1">

<Description>Example FTP Server</Description><InstantiationParams>

<NetworkConfigSection><ovf:Info>Configuration parameters for logical networks</ovf:Info><NetworkConfig networkName="vAppNetwork">



</NetworkConfigSection><LeaseSettingsSection type="application/vnd.vmware.vcloud.leaseSettingsSection+xml">

<ovf:Info>Lease Settings</ovf:Info><StorageLeaseInSeconds>172800</StorageLeaseInSeconds><StorageLeaseExpiration>2010-04-11T08:08:16.438-07:00</StorageLeaseExpiration>

</LeaseSettingsSection></InstantiationParams><Source href=”http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111”/><AllEULAsAccepted>true</AllEULAsAccepted>

</InstantiateVAppTemplateParams>

Response:


<VApp name="Linux FTP server" deployed=”false” status="0" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...>

<Description>Example FTP Server</Description>...<Tasks>

<Task ... operation="Creating Virtual Application Linux FTP server(7)" ... >...

</Task></Tasks>

</VApp>


64 VMware, Inc.

The response is a sparsely populated vApp body that contains a Task element The status of the vApp is initially

0. When instantiation is complete and the vApp is powered on, the Task no longer appears in the vApp body, and the vApp status changes to 4, indicating that all of its children are powered on. You can check the status

of the task by issuing a GET request to the task URL or you can check the status of the vApp by issuing a GET

request to the vApp URL. These URLs are returned in the value of the object’s href attribute.

Retrieve or Modify the CustomizationSection of a vApp Template

A vApp template can include a CustomizationSection element that specifies whether or not the virtual

machines in the vApp should be customized when the vApp is instantiated. Example 5‐2 retrieves this section

from a vApp template.

Example 5-2. Retrieve vApp Template CustomizationSection

Request:

GET http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/customizationSection

Response:

200 OKContent-type: application/vnd.vmware.vcloud.customizationSection+xml...<CustomizationSection xmlns="http://www.vmware.com/vcloud/v1"

xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" ovf:required="false" vcloud:href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/customizationSection/" vcloud:type="application/vnd.vmware.vcloud.customizationSection+xml" ...>

<ovf:Info>VApp template customization section</ovf:Info><CustomizeOnInstantiate>true</CustomizeOnInstantiate><Link rel="edit" type="application/vnd.vmware.vcloud.customizationSection+xml"

href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/customizationSection/"/>

</CustomizationSection>

To change the value of CustomizeOnInstantiate, PUT a CustomizationSection body that has the changed value to the section’s rel="edit" URL, as shown in Example 5‐3.

Example 5-3. Modify vApp Template CustomizationSection

Request:

PUT http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/customizationSectionContent-type: application/vnd.vmware.vcloud.customizationSection+xml...<CustomizationSection xmlns="http://www.vmware.com/vcloud/v1"

xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" ovf:required="false" vcloud:href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/customizationSection/" vcloud:type="application/vnd.vmware.vcloud.customizationSection+xml">

<ovf:Info>VApp template customization section</ovf:Info><CustomizeOnInstantiate>false</CustomizeOnInstantiate>

</CustomizationSection>

Response:


...</Task>

VMware, Inc. 65


Compose a vAppThe vCloud API supports composing a vApp from any combination of vApp templates, vApps, or virtual

machines. When you compose a vApp, all children of each composition source become peers in the Children collection of the composed vApp.

To compose a vApp, a client makes a composeVApp request whose body, a ComposeVAppParams element,

includes the following information:

An InstantiationParams element that applies to the composed vApp itself and any vApp templates

referenced in Item elements. For more information, see “About Instantiation Parameters” on page 62.

An Item element for each virtual machine, vApp, or vAppTemplate to include in the composition. Each

Item can contain the following elements:

A required Source element whose href attribute value is a reference to a vApp template, vApp, or

Vm to include in the composition. If the Source element references a Vm, the Item must also include

an InstantiationParams element specific to that Vm.

An optional NetworkAssignment element that specifies how the network connections of child Vm elements are mapped to vApp networks in the parent.

If any of the composition items is subject to a EULA, the ComposeVAppParams element must include an

AllEULAsAccepted element that has a value of true, indicating that you accept the EULA. Otherwise,

composition fails.

The composed vApp must be deployed and powered on before it can be used.

Example 5‐4 shows a composeVApp request that specifies two vAppTemplate sources and one Vm source. The Vm source requires InstantiationParams that modify its NetworkConnectionSection to specify the vApp network created for this vApp. The vAppTemplate sources inherit this setting from the base InstantiationParams element (the one that appears before the first Item is specified).

Example 5-4. Compose a vApp

Request:

POST http://vcloud.example.com/api/v1.0/vdc/5/action/composeVAppContent-Type: application/vnd.vmware.vcloud.composeVAppParams+xml...<ComposeVAppParams name="Example Corp’s CRM Appliance" xmlns="http://www.vmware.com/vcloud/v1"

xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"><InstantiationParams>

<NetworkConfigSection><ovf:Info>Configuration parameters for logical networks</ovf:Info><NetworkConfig networkName="CRMApplianceNetwork">



</NetworkConfigSection></InstantiationParams><Item>

<Source href="http://vcloud.example.com/api/v1.0/vApp/vm-4"/><InstantiationParams>

<NetworkConnectionSection type="application/vnd.vmware.vcloud.networkConnectionSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/" ovf:required="false">

<ovf:Info/><PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex><NetworkConnection network="CRMApplianceNetwork">

<NetworkConnectionIndex>0</NetworkConnectionIndex><IsConnected>true</IsConnected><IpAddressAllocationMode>DHCP</IpAddressAllocationMode>

</NetworkConnection>


66 VMware, Inc.

</NetworkConnectionSection></InstantiationParams>

</Item><Item>

<Source href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-114"/></Item><Item>

<Source href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-190"/></Item><AllEULAsAccepted>true</AllEULAsAccepted>

</ComposeVAppParams>

Response:

201 CreatedContent-Type: application/vnd.vmware.vcloud.vApp+xml...<VApp name="Example Corp’s CRM Appliance" type="application/vnd.vmware.vcloud.vApp+xml"

status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-33" ...><Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml"

href="http://vcloud.example.com/api/v1.0/vdc/5"/><Description>Composed CRM Appliance</Description>...<Tasks>

<Task ...>...

</Task></Tasks>

</VApp>

The response is similar to the one shown in Example 5‐1, a sparsely populated vApp body that contains a Task element. The status of the vApp is initially 0. When composition is complete, the status changes to 1.

Finding Virtual Machine URLs to Use in a Composition Item

Virtual machines (Vm objects) are not listed in catalogs or vDCs. To find the URL of a Vm URL to include in a composition item Source, GET a vApp or vApp template that includes it, and examine the Children container of the VApp element. Each Vm in this container has an href attribute whose value you can use to

reference the Vm for this (or any other) purpose.

The Vm URL used in Example 5‐4 appears in the Children element of Example 5‐5.

Example 5-5. Vm URL in a vApp Body

Request:


Response:

200 OKContent-type: application/vnd.vmware.vcloud.vApp+xml...<VApp name="Linux FTP server" status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7"

...>...<Children>

<Vm status="8" href="http://vcloud.example.com/api/v1.0/vApp/vm-4" ...>...

</Children></VApp>

NOTE To be included in a composition request, a Vm must be powered off (status="8").

VMware, Inc. 67


Recompose a vApp to Add or Remove Virtual MachinesThe vCloud API supports recomposition of a vApp to add or remove virtual machines (Vm elements). To

recompose a vApp, a client makes a recomposeVApp request, supplying a RecomposeVAppParams element as

the request body. The RecomposeVAppParams element allows an arbitrary number of DeleteItem elements,

but is otherwise identical to ComposeVAppParams. This means that in addition to adding or removing virtual

machines, a recomposeVApp request can also change the name and description of the vApp, and can supply

new InstantiationParams to change various sections of the composed vApp or any of the added virtual

machines.

Example 5-6. vApp Before Recomposition

Request:


Response:

200 OKContent-type: application/vnd.vmware.vcloud.vApp+xml...<VApp name="Example Corp’s CRM Appliance" type="application/vnd.vmware.vcloud.vApp+xml"

status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-33" ...><Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml"

href="http://vcloud.example.com/api/v1.0/vdc/5"/><Description>Composed CRM Appliance</Description>...<Children>

<Vm status="8" name="CRM-DB" href="http://vcloud.example.com/api/v1.0/vApp/vm-7" ...>...</Vm><Vm status="8" name="CRM-CRM" href="http://vcloud.example.com/api/v1.0/vApp/vm-44" ...>...</Vm><Vm status="8" name="CRM-HTTP" href="http://vcloud.example.com/api/v1.0/vApp/vm-45" ...>...</Vm>

</Children>...

</VApp>

Example 5‐7 shows a recomposeVApp request that modifies the vApp shown in Example 5‐6 by removing one

of the virtual machines it contains and creating a new StartupSection that specifies a startup order for the two virtual machines that remain in the vApp.

Example 5-7. Recompose a vApp

Request:

POST http://vcloud.example.com/api/v1.0/vApp/vapp-33/action/recomposeVAppContent-Type: application/vnd.vmware.vcloud.recomposeVAppParams+xml...<RecomposeVAppParams name="Example Corp’s CRM Appliance" xmlns="http://www.vmware.com/vcloud/v1"

xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"><InstantiationParams>

<NetworkConfigSection><ovf:Info>Configuration parameters for logical networks</ovf:Info><NetworkConfig networkName="CRMApplianceNetwork">



</NetworkConfigSection>


68 VMware, Inc.

<ovf:StartupSection xmlns:vcloud="http://www.vmware.com/vcloud/v1" vcloud:href="http://vcloud.example.com/api/v1.0/vApp/vapp-33/startupSection/" vcloud:type="application/vnd.vmware.vcloud.startupSection+xml">

<ovf:Info>VApp startup section</ovf:Info><ovf:Item ovf:order="0" ovf:id="CRM-DB"/><ovf:Item ovf:order="1" ovf:id="CRM-CRM"/>

</ovf:StartupSection></InstantiationParams><AllEULAsAccepted>true</AllEULAsAccepted><DeleteItem href="http://vcloud.example.com/api/v1.0/vApp/vm-45" />

</RecomposeVAppParams>

Response:

202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Updating Virtual Application Example Corp’s CRM Appliance (33)" ...>

...</Task>

Capture a vApp to Create a vApp TemplateThe captureVApp request creates a vApp template from an instantiated vApp. The request body, shown in

Example 5‐8, is a captureVAppParams element that specifies the href of the vApp to capture, along with a

name and optional description for the template that the capture creates.

Example 5-8. Capture a vApp

Request:

POST http://vcloud.example.com/api/v1.0/vdc/5/action/captureVAppContent-Type: application/vnd.vmware.vcloud.captureVAppParams+xml...<CaptureVAppParams name="Linux Server Template" xmlns="http://www.vmware.com/vcloud/v1">

<Description>Template captured from Ubuntu vApp</Description><Source href=”http://vcloud.example.com/api/v1.0/vApp/vApp-201”/>

</CaptureVAppParams>

Response:

201 CreatedContent-Type: application/vnd.vmware.vcloud.vAppTemplate+xml...<VAppTemplate name="Linux Server Template"" type="application/vnd.vmware.vcloud.vApp+xml"

status="8" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-20" ...>


<Description>Template captured from Ubuntu vApp</Description><Tasks>

<Task ... operation="Capturing Virtual Application Template CaturedTemplate (20)" ... >...

</Task></Tasks>...

</VAppTemplate>

The response is a vAppTemplate document that contains a Task. The status of the vAppTemplate is initially 0. When the capture operation is complete, the status changes to 8.

NOTE Before it can be captured, a vApp must be undeployed (deployed="false").

VMware, Inc. 69


Reconfiguring vApps and Virtual MachinesConfiguration details for vApps and the virtual machines they contain are specified in ovf:SectionType elements such as LeaseSettingsSection, NetworkConfigSection, and OperatingSystemSection. These sections can be specified in the InstantiationParams for the vApp or Vm, and can also be edited in place using reconfiguration links (Link elements where rel="edit") that the server adds to these sections during instantiation. For more information about the sections that can be included in InstantiationParams, see “InstantiationParams” on page 172.

The reconfiguration process for vApps and virtual machines is similar, but the set of sections that can be edited

during reconfiguration depends on the object being reconfigured.

Reconfigure a vApp

Table 5‐2 summarizes vApp reconfiguration requests supported in this release. The table uses the following

conventions:


id is an integer

You can reconfigure a vApp by making changes to any of the following sections:

LeaseSettingsSection

StartupSection

NetworkConfigSection

Modified sections must contain all required elements, even if you are not changing their values. Some

elements in some sections are read‐only. See the schema references for details.

Table 5-2. Summary of vApp Reconfiguration Requests


Retrieve vApp Lease Settings GET API‐URL/vApp/vapp‐id/leaseSettingsSection/

None LeaseSettingsSection

Modify vApp Lease Settings PUT API‐URL/vApp/vapp‐id/leaseSettingsSection/

LeaseSettingsSection Task

Retrieve vApp Startup Section GET API‐URL/vApp/vapp‐id/startupSection/

None StartupSection

Modify vApp Startup Section PUT API‐URL/vApp/vapp‐id/startupSection/

StartupSection Task

Retrieve vApp Network Section GET API‐URL/vApp/vapp‐id/networkSection/

None ovf:NetworkSection

Retrieve vApp Network Configuration GET API‐URL/vApp/vapp‐id/networkConfigSection/

None NetworkConfigSection

Modify vApp Network Configuration PUT API‐URL/vApp/vapp‐id/networkConfigSection/

NetworkConfigSection Task

NOTE Each Vm in the vApp’s Children collection includes additional links for configuring its guest operating system, virtual hardware, and other properties. For clarity, the Children are not shown in Example 5‐9. To see

them, refer to Example 5‐12 on page 75.


70 VMware, Inc.

Example 5-9. Configuration Links for a vApp

Request:


Response:

200 OKContent-type: application/vnd.vmware.vcloud.vApp+xml...

<VApp name="Linux FTP server" status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...>

<Description>Example FTP Server</Description>...<LeaseSettingsSection

href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/leaseSettingsSection/" ovf:required="false">

<ovf:Info>VApp lease settings</ovf:Info><Link rel="edit" type="application/vnd.vmware.vcloud.leaseSettingsSection+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/leaseSettingsSection/"/>

<DeploymentLeaseInSeconds>3600</DeploymentLeaseInSeconds><StorageLeaseInSeconds>3600</StorageLeaseInSeconds><DeploymentLeaseExpiration>2010-01-21T13:50:59.764-08:00</DeploymentLeaseExpiration>

</LeaseSettingsSection><ovf:StartupSection href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/startupSection/">

<ovf:Info>VApp startup section</ovf:Info><Link rel="edit" type="application/vnd.vmware.vcloud.startupSection+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/startupSection/"/></ovf:StartupSection><ovf:NetworkSection ... >

... </ovf:NetworkSection><NetworkConfigSection

href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/" ovf:required="false">

<Link rel="edit" type="application/vnd.vmware.vcloud.networkConfigSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/"/>

<ovf:Info>Configuration parameters for vAppNetwork</ovf:Info><NetworkConfig ... >

...<Configuration>

...</Configuration><IsDeployed>false</IsDeployed>

</NetworkConfig></NetworkConfigSection><Children>

...</Children>

</VApp>

VMware, Inc. 71


To modify a section

1 Retrieve the vApp or vApp template and examine the response to find the section that you want to

modify.

2 Retrieve the section by making a GET request to the section’s edit link (a Link element in the section

where rel="edit").

3 Modify the section as needed.

4 PUT the modified section to the section’s edit link. Note that section edit URLs, unlike most other URLs

presented by the vCloud API, end with a / character.

Retrieve or Modify the NetworkConfigSection of a vApp Template

Example 5‐10 retrieves a vApp’s network configuration (NetworkConfigSection). Example 5‐11 modifies the

section and applies the changes. Changes to the StartupSection or LeaseSettingsSection can use the same procedure.

Example 5-10. Retrieve vApp Network Configuration

Request:

GET http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/

Response:

200 OKContent-type: application/vnd.vmware.vcloud.networkConfigSection+xml...<NetworkConfigSection href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/"

ovf:required="false"><ovf:Info>Configuration parameters for logical networks</ovf:Info><Link rel="edit" type="application/vnd.vmware.vcloud.networkConfigSection+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/"/><NetworkConfig networkName="vAppNetwork">


<IsInherited>true</IsInherited><Gateway>10.147.56.253</Gateway><Netmask>255.255.255.0</Netmask><Dns1>10.147.115.1</Dns1><Dns2>10.147.115.2</Dns2><DnsSuffix>example.com</DnsSuffix><IpRanges>

<IpRange><StartAddress>10.147.56.1</StartAddress><EndAddress>10.147.56.255</EndAddress>

</IpRange></IpRanges>

</IpScope><ParentNetwork type="application/vnd.vmware.vcloud.network+xml" name="Internet"

href="http://vcloud.example.com/api/v1.0/network/54"/><FenceMode>bridged</FenceMode>

</Configuration><IsDeployed>false</IsDeployed>

</NetworkConfig></NetworkConfigSection>

The modified NetworkConfigSection in the request body in Example 5‐11 changes the FenceMode value to natRouted and adds a Features element that defines several network features useful to an FTP server that

must be reachable from the public Internet, but only at the FTP port and the SSH port.

NOTE Sections that do not have a Link where rel="edit" cannot be modified.


72 VMware, Inc.

A set of FirewallRules that allow TCP traffic to ports 21 and 22. Because these rules require you to specify a single IP address on the inside of the firewall, the IpScope element is modified to limit the range

of IP addresses available on the vApp network to a single address. Any Vm that connects to the vApp network defined in this NetworkConfigSection is given this address.

A NatService element that maps a routable external IP address to the internal IP address allocated to the

Vm by the vApp network. The VAppScopedVmId value in this element is taken from the

VAppScopedLocalId element of the Vm and the VmNicId value is taken from its PrimaryNetworkConnectionIndex. See Example 5‐12 on page 75.

Whenever you modify a vApp network, as we do in this example, you must be sure that the modifications are

consistent with the network connection requirements of the virtual machines that connect to the network. The

vApp in this example contains a single Vm. As shown in Example 5‐12 on page 75, that virtual machine’s

NetworkConnection element specifies an IP address that will not be available after the vApp network has

been reconfigured as shown in Example 5‐11. Example 5‐14 on page 77 corrects this problem. While

Example 5‐11 uses the IpScope element to restrict the IP addresses available on a vApp network, it is usually

more practical to keep the range of addresses available on a vApp network somewhat wider, and apply any

firewall‐related IP address restrictions by modifying the NetworkConnection of the Vm to which the

FirewallRules apply, as we do in Example 5‐14. A wider range of IP addresses would allow this vApp to be

modified to include additional virtual machines, and the IP address restriction applied in Example 5‐14 would

allow the FirewallRules in Example 5‐14 to remain valid.

This request, like all request bodies derived from a response, omits the Link elements and href attributes that were part of the response. It also omits the IsDeployed element of the NetworkConfig. These elements and

attributes are created by the server and are read‐only. They are ignored if you include them in a request.

Example 5-11. Modify vApp Network Configuration

Request:

PUT http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/Content-type: application/vnd.vmware.vcloud.networkConfigSection+xml...<NetworkConfigSection>

<ovf:Info>Configuration parameters for logical networks</ovf:Info><NetworkConfig networkName="vAppNetwork">


<IsInherited>false</IsInherited><Gateway>10.147.56.253</Gateway><Netmask>255.255.255.0</Netmask><Dns1>10.147.115.1</Dns1><Dns2>10.147.115.2</Dns2><DnsSuffix>example.com</DnsSuffix><IpRanges>


</IpRange></IpRanges>

</IpScope><ParentNetwork type="application/vnd.vmware.vcloud.network+xml" name="Internet"

href="http://vcloud.example.com/api/v1.0/network/54"/><FenceMode>natRouted</FenceMode><Features>

<FirewallService><IsEnabled>true</IsEnabled><FirewallRule>

<IsEnabled>true</IsEnabled><Description>FTP Rule</Description><Policy>allow</Policy><Protocols>

<Tcp>true</Tcp></Protocols><Port>21</Port>

VMware, Inc. 73


<DestinationIp>10.147.115.1</DestinationIp></FirewallRule><FirewallRule>

<IsEnabled>true</IsEnabled><Description>SSH Rule</Description><Policy>allow</Policy><Protocols>

<Tcp>true</Tcp></Protocols><Port>22</Port><DestinationIp>10.147.115.1</DestinationIp>

</FirewallRule></FirewallService><NatService>

<IsEnabled>true</IsEnabled><NatType>ipTranslation</NatType><Policy>allowTraffic</Policy><NatRule>

<OneToOneVmRule><MappingMode>manual</MappingMode><ExternalIp>64.100.10.1</ExternalIp><VAppScopedVmId>20ea086f-1a6a-4fb2-8e2e-23372facf7de</VAppScopedVmId><VmNicId>0</VmNicId>

</OneToOneVmRule></NatRule>

</NatService></Features>


</NetworkConfigSection>

Response:

202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Updating Virtual Application Linux FTP server (7)" ...>

...</Task>

The response is a Task element.

View or Modify vApp Lease Settings

Lease settings apply to both vApps and vApp templates, although vApp templates do not include deployment

lease information (DeploymentLeaseInSeconds and DeploymentLeaseExpiration). Default vApp lease settings are inherited from the organization that owns the vDC in which the vApp is deployed. You can

override these defaults in the InstantiateVAppTemplateParams request body (see “Instantiating a vApp Template Using Additional Parameters” on page 62). You can view the lease settings by retrieving the vApp or vAppTemplate representation. To modify them, use the edit link in the LeaseSettingsSection, as described in “Reconfigure a vApp” on page 69.

Reconfigure a Virtual Machine

Table 5‐2 summarizes virtual machine reconfiguration requests supported in this release. The table uses the

following conventions:


id is an integer


74 VMware, Inc.

You can reconfigure a virtual machine (Vm element) by making changes to any of the following sections:

VirtualHardwareSection

OperatingSystemSection

NetworkConnectionSection

GuestCustomizationSection

Modified sections must contain all required elements, even if you are not changing their values. Some

elements in some sections are read‐only. See the schema references for details.

Table 5-3. Summary of Virtual Machine Reconfiguration Requests


Retrieve the Network Connection of a Virtual Machine

GET API‐URL/vApp/vm‐id/networkConnectionSection/

None NetworkConnectionSection

Modify the Network Connection of a Virtual Machine

PUT API‐URL/vApp/vm‐id/networkConnectionSection/

NetworkConnectionSection Task

Retrieve the Guest Customization Section of a Virtual Machine

GET API‐URL/vApp/vm‐id/guestCustomizationSection/

None GuestCustomizationSection

Modify the Guest Customization Section of a Virtual Machine

PUT API‐URL/vApp/vm‐id/guestCustomizationSection/

GuestCustomizationSection Task

Retrieve the Operating System Section of a Virtual Machine

GET API‐URL/vApp/vm‐id/operatingSystemSection/

None OperatingSystemSection

Modify the Operating System Section of a Virtual Machine

PUT API‐URL/vApp/vm‐id/operatingSystemSection/

OperatingSystemSection Task

Retrieve the Virtual Hardware Section of a Virtual Machine

GET API‐URL/vApp/vm‐id/virtualHardwareSection/

None VirtualHardwareSection

Modify the Virtual Hardware Section of a Virtual Machine

PUT API‐URL/vApp/vm‐id/virtualHardwareSection/

VirtualHardwareSection Task

Retrieve the CPU Configuration of a Virtual Machine

GET API‐URL/vApp/vm‐id/virtualHardwareSection/cpu

None ovf:Item

Modify the CPU Configuration of a Virtual Machine

PUT API‐URL/vApp/vm‐id/virtualHardwareSection/cpu

ovf:Item Task

Retrieve the Memory Item from the Virtual Hardware Section of a Virtual Machine

GET API‐URL/vApp/vm‐id/virtualHardwareSection/memory

None ovf:Item

Modify the Memory Item of the Virtual Hardware Section of a Virtual Machine

PUT API‐URL/vApp/vm‐id/virtualHardwareSection/memory

ovf:Item Task

Retrieve Virtual Disk Items from the Virtual Hardware Section of a Virtual Machine

GET API‐URL/vApp/vm‐id/virtualHardwareSection/disks

None RasdItemsList

Modify Virtual Disk Items of the Virtual Hardware Section of a Virtual Machine

PUT API‐URL/vApp/vm‐id/virtualHardwareSection/disks

RasdItemsList Task

Retrieve Network Card Items from the Virtual Hardware Section of a Virtual Machine

GET API‐URL/vApp/vm‐id/virtualHardwareSection/networkCards

None RasdItemsList

Modify Network Card Items of the Virtual Hardware Section of a Virtual Machine

PUT API‐URL/vApp/vm‐id/virtualHardwareSection/networkCards

RasdItemsList Task

Retrieve Removable Media Drive Items from the Virtual Hardware Section of a Virtual Machine

GET API‐URL/vApp/vm‐id/virtualHardwareSection/media

None RasdItemsList

VMware, Inc. 75


Example 5‐12 shows a representative collection of these links. (This example does not show the configuration

links for the parent vApp. To see them, refer to Example 5‐9 on page 70.)

Example 5-12. Configuration Links for a Vm

Request:


Response:


...><Description>Example FTP Server</Description>...<Children>

<Vm status="8" name="ubuntu10-x86" href="http://vcloud.example.com/api/v1.0/vApp/vm-4" ...>

<Link rel="power:reboot" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/action/reboot"/>

...<Link rel="media:ejectMedia"

type="application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/media/action/ejectMedia"/>

<Description/><ovf:VirtualHardwareSection ... ">

<ovf:System>...</ovf:System><ovf:Item vcloud:href="http://vcloud.example.com/api/v1.0/vApp/vm-4/

virtualHardwareSection/cpu" ... >...

<rasd:Description>Number of Virtual CPUs</rasd:Description><rasd:ResourceType>3</rasd:ResourceType>...<Link rel="edit" type="application/vnd.vmware.vcloud.rasdItem+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vm-4/virtualHardwareSection/cpu"/>

</ovf:Item><ovf:Item vcloud:href="http://vcloud.example.com/api/v1.0/vApp/vm-4/

virtualHardwareSection/memory" ...>...<rasd:Description>Memory Size</rasd:Description><rasd:ResourceType>4</rasd:ResourceType>...<Link rel="edit" type="application/vnd.vmware.vcloud.rasdItem+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vm-4/virtualHardwareSection/memory"/>

</ovf:Item><ovf:Item>

...<rasd:Description>SCSI Controller</rasd:Description><rasd:ResourceType>6</rasd:ResourceType>...

</ovf:Item><ovf:Item>

...<rasd:Description>Hard disk</rasd:Description><rasd:ElementName>Hard disk 1</rasd:ElementName><rasd:ResourceType>17</rasd:ResourceType>

...</ovf:Item>


76 VMware, Inc.

<Link rel="edit" type="application/vnd.vmware.vcloud.virtualHardwareSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/virtualHardwareSection/"/>

<Link type="application/vnd.vmware.vcloud.rasdItemsList+xml" rel="edit href="http://vcloud.example.com/api/v1.0/vApp/vm-4/virtualHardwareSection/disks"/>

...<Link rel="edit" type="application/vnd.vmware.vcloud.rasdItemsList+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vm-4/virtualHardwareSection/networkCards"/>

...</ovf:VirtualHardwareSection><ovf:OperatingSystemSection ... href="http://vcloud.example.com/api/v1.0/vApp/vm-4/

operatingSystemSection/">...<Link rel="edit" type="application/vnd.vmware.vcloud.operatingSystemSection+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vm-4/operatingSystemSection/"/>

</ovf:OperatingSystemSection><NetworkConnectionSection ... href="http://vcloud.example.com/api/v1.0/vApp/vm-4/

networkConnectionSection/" ...><ovf:Info>Specifies the available VM network connections</ovf:Info><PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex><NetworkConnection network="vAppNetwork">

<NetworkConnectionIndex>0</NetworkConnectionIndex><IpAddress>10.147.122.134</IpAddress><IsConnected>false</IsConnected><MACAddress>00:50:56:01:01:49</MACAddress><IpAddressAllocationMode>POOL</IpAddressAllocationMode>

</NetworkConnection><Link rel="edit"

type="application/vnd.vmware.vcloud.networkConnectionSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/"/>

</NetworkConnectionSection><GuestCustomizationSection

type="application/vnd.vmware.vcloud.guestCustomizationSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/guestCustomizationSection/" ovf:required="false">

<ovf:Info>Specifies Guest OS Customization Settings</ovf:Info><Enabled>false</Enabled><ChangeSid>false</ChangeSid><VirtualMachineId>4</VirtualMachineId><JoinDomainEnabled>false</JoinDomainEnabled><UseOrgSettings>false</UseOrgSettings><AdminPasswordEnabled>false</AdminPasswordEnabled><AdminPasswordAuto>true</AdminPasswordAuto><ResetPasswordRequired>false</ResetPasswordRequired><CustomizationScript/><ComputerName>ubuntu10-x86</ComputerName><Link rel="edit"

type="application/vnd.vmware.vcloud.guestCustomizationSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/guestCustomizationSection/"/>

</GuestCustomizationSection><VAppScopedLocalId>20ea086f-1a6a-4fb2-8e2e-23372facf7de</VAppScopedLocalId></Vm>

</Children></VApp>

VMware, Inc. 77


Reconfiguration links in the body of a Vm can appear in two places:

Individual Link elements in the ovf:Item elements defining cpu and memory. These links appear in the ovf:Item itself, and have type="application/vnd.vmware.vcloud.rasdItem+xml".

Links to groups of related ovf:Item elements (disks, network cards, and media devices). These links

appear at the end of the ovf:VirtualHardwareSection, and have type="application/vnd.vmware.vcloud.rasdItemsList+xml".

Retrieve or Modify the Network Connection of a Virtual Machine

Example 5‐13 retrieves the NetworkConnectionSection configuration of the Vm shown in Example 5‐12. Example 5‐14 modifies the section and uses the URL in the edit link from that section to apply the changes to the Vm.

Example 5-13. Retrieve the Network Connection of a Virtual Machine

Request:

GET http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.networkconnectionsection+xml...

<NetworkConnectionSection ... href="http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/" ...>

<ovf:Info>Specifies the available VM network connections</ovf:Info><PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex><NetworkConnection network="vAppNetwork">


</NetworkConnection><Link rel="edit" type="application/vnd.vmware.vcloud.networkConnectionSection+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vm-4networkConnectionSection/"/>

</NetworkConnectionSection>

The modified NetworkConnectionSection in the request body changes the value in the IpAddress element.

Example 5-14. Modify the Network Connection of a Virtual Machine

Request:

PUT "http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/Content-type: application/vnd.vmware.vcloud.networkConnectionSection+xml...<NetworkConnectionSection ...

href="http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/" ...><ovf:Info>Specifies the available VM network connections</ovf:Info><PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex><NetworkConnection network="vAppNetwork">


</NetworkConnection></NetworkConnectionSection>


78 VMware, Inc.

Response:


...</Task>

Retrieve or Modify the CPU Configuration of a Virtual Machine

Example 5‐15 retrieves the CPU configuration of the Vm shown in Example 5‐12. Example 5‐16 modifies the

section and uses the URL in the edit link from that section to apply the changes to the Vm.

Example 5-15. Retrieve the CPU Configuration of a Virtual Machine

Request:

GET http://vcloud.example.com/api/v1.0/vApp/vm-4/virtualHardwareSection/cpu

Response:

200 OKContent-type: application/vnd.vmware.vcloud.rasdItem+xml...<Item xmlns="http://www.vmware.com/vcloud/v1"

xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData" ... >

<rasd:AllocationUnits>hertz * 10^6</rasd:AllocationUnits><rasd:Description>Number of Virtual CPUs</rasd:Description><rasd:ElementName>1 virtual CPU(s)</rasd:ElementName><rasd:InstanceID>1</rasd:InstanceID><rasd:ResourceType>3</rasd:ResourceType><rasd:VirtualQuantity>1</rasd:VirtualQuantity>

</Item>

The modified Item in the request body adds a second CPU to the Vm by changing the rasd:VirtualQuantity value of the Item to 2.

Example 5-16. Modify the CPU Configuration of a Virtual Machine

Request:

PUT http://vcloud.example.com/api/v1.0/vApp/vm-4/virtualHardwareSection/cpuContent-type: application/vnd.vmware.vcloud.rasdItem+xml...<Item xmlns="http://www.vmware.com/vcloud/v1"

xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData">

<rasd:AllocationUnits>hertz * 10^6</rasd:AllocationUnits><rasd:Description>Number of Virtual CPUs</rasd:Description><rasd:ElementName>1 virtual CPU(s)</rasd:ElementName><rasd:InstanceID>1</rasd:InstanceID><rasd:ResourceType>3</rasd:ResourceType><rasd:VirtualQuantity>2</rasd:VirtualQuantity>

</Item>

Response:


...</Task>

VMware, Inc. 79


Retrieve or Modify the Guest Customization Section of a Virtual Machine

Example 5‐17 retrieves the GuestCustomizationSection of a Windows Vm. Example 5‐18 modifies the

section and uses the URL in the edit link from that section to apply the changes to the Vm.

Example 5-17. Retrieve the Guest Customization Section of a Virtual Machine

Request:

GET http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection

Response:

200 OKContent-type: application/vnd.vmware.vcloud.guestcustomizationsection+xml...<GuestCustomizationSection type="application/vnd.vmware.vcloud.guestCustomizationSection+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection/" ovf:required="false">

<ovf:Info>Specifies Guest OS Customization Settings</ovf:Info><Enabled>false</Enabled><ChangeSid>false</ChangeSid><VirtualMachineId>4</VirtualMachineId><JoinDomainEnabled>false</JoinDomainEnabled><UseOrgSettings>false</UseOrgSettings><AdminPasswordEnabled>false</AdminPasswordEnabled><AdminPasswordAuto>true</AdminPasswordAuto><ResetPasswordRequired>false</ResetPasswordRequired><CustomizationScript/><ComputerName>ubuntu10-x86</ComputerName><Link rel="edit" type="application/vnd.vmware.vcloud.guestCustomizationSection+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection/"/>

</GuestCustomizationSection>

The modified GuestCustomizationSection in the request body changes the value of the JoinDomainEnabled element to true. This change requires you to specify a domain to join, along with the

name and password of a domain administrator, so the request body includes DomainName, DomainUserName, and DomainUserPassword elements.

Example 5-18. Modify the Guest Customization Section of a Virtual Machine

Request:

PUT http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSectionContent-type: application/vnd.vmware.vcloud.guestcustomizationsection+xml...<GuestCustomizationSection type="application/vnd.vmware.vcloud.guestCustomizationSection+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection/" ovf:required="false">

<ovf:Info>Specifies Guest OS Customization Settings</ovf:Info><Enabled>false</Enabled><ChangeSid>false</ChangeSid><VirtualMachineId>4</VirtualMachineId><JoinDomainEnabled>true</JoinDomainEnabled><UseOrgSettings>false</UseOrgSettings><DomainName>EXAMPLE</DomainName><DomainUserName>admin</DomainUserName><DomainUserPassword>Pa55w0rd</DomainUserPassword><AdminPasswordEnabled>false</AdminPasswordEnabled><AdminPasswordAuto>true</AdminPasswordAuto><ResetPasswordRequired>false</ResetPasswordRequired><CustomizationScript/><ComputerName>ubuntu10-x86</ComputerName>


80 VMware, Inc.

<Link rel="edit" type="application/vnd.vmware.vcloud.guestCustomizationSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection/"/>

</GuestCustomizationSection>

Response:

202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Updating Virtual Application Win2K3 (12)" ...>

...</Task>

View or Modify Groups of Related Sections in a Vm

As shown in Example 5‐12 on page 75, Link elements for disks, media devices, and network cards are grouped

at the end of the VirtualHardwareSection. These links have content type application/vnd.vmware.vcloud.rasdItemsList+xml, and reference a RasdItemsList element in the

VirtualHardwareSection of a Vm. The vCloud API uses the RasdItemsList element to aggregate related

elements in a VirtualHardwareSection. This simplifies retrieval and modification of Item elements that are

typically viewed or modified as a group. To retrieve one of these elements, use the link where rel="down". To modify it, use the link where rel="edit".

Deploying and Controlling vApps and Virtual MachinesA vApp or Vm body returned in response to a GET, PUT, or POST request includes a number of action links,

which have the form vApp‐or‐Vm‐URL/action/action‐name. A client can use action links to request various

actions on the vApp. Only those action links that are valid for the vApp or virtual machine in its current state

are returned. For example, if a vApp is instantiated but not deployed, only the links for deploy and remove are returned. For a vApp that is powered on, links for all actions except powerOn are returned (see Example 2‐8

on page 27).

Some of the requests documented in this section apply only to vApps, others apply only to virtual machines

(Vm objects), and others apply to both.

A request made to a vApp URL invokes the requested operation on each of the virtual machines in the

Children element of the vApp, in the order specified in its ovf:StartupSection element. This element,

if present, specifies a start order and related properties for each member of a VirtualSystemCollection (each Vm in the Children collection). If the element is not present, all members are started up at the same

time. The same logic applies to shutdown, reboot, and similar operations. For more information, see the

OVF specification, available at

http://www.dmtf.org/standards/published_documents/DSP0243_1.0.0.pdf.

A request made to a Vm URL affects only that virtual machine.

Deploy a vApp or Virtual Machine

To deploy a vApp, the client makes a request to its action/deploy URL. Deploying a vApp automatically

deploys all of the virtual machines it contains.

To deploy a virtual machine, the client makes a request to its action/deploy URL. Deploying a Vm implicitly

deploys the parent vApp if that vApp is not already deployed.

The request body in each case is a DeployVAppParams element.

NOTE You cannot include a GuestCustomizationSection in the InstantiationParams passed to a Vm during instantiation, composition, or recomposition. To change this section, you must retrieve it from a Vm and update it.

NOTE Media devices are read‐only, so they have no rel="edit" link. For more information, see “List Media

Devices of a Virtual Machine” on page 85.

VMware, Inc. 81


Example 5-19. Deploy and Power On a vApp or Virtual Machine

Request:

POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/deployContent-type: application/vnd.vmware.vcloud.deployVAppParams+xml...<DeployVAppParams powerOn="true" xmlns="http://www.vmware.com/vcloud/v1"/>

Response:

202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Starting Virtual Application Linux FTP server (7) ...>

...</Task>

Undeploy a vApp or Virtual Machine

Undeploying a vApp powers off or suspends any running virtual machines it contains, then frees the

resources reserved for the vApp and sets the vApp’s deployed attribute to a value of false to indicate that it is not deployed.

Undeploying a virtual machine powers off or suspends the virtual machine, then frees the resources reserved

for it and sets the its deployed attribute to a value of false to indicate that it is not deployed. This operation has no effect on the containing vApp.

The saveState attribute specifies whether the undeployed virtual machines are suspended and their suspend

state saved, or simply powered off.

The request body in each case is an UndeployVAppParams element.

Example 5-20. Undeploy a vApp or Virtual Machine

Request to undeploy a vApp:

POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/undeployContent-type: application/vnd.vmware.vcloud.undeployVAppParams+xml...<UndeployVAppParams saveState="true" xmlns="http://www.vmware.com/vcloud/v1"/>

Request to undeploy a Vm:

POST http://vcloud.example.com/api/v1.0/vApp/vm-5/action/undeployContent-type: application/vnd.vmware.vcloud.undeployVAppParams+xml...<UndeployVAppParams saveState="true" xmlns="http://www.vmware.com/vcloud/v1"/>

Response:


...</Task>

Power On a vApp or Virtual Machine

A powerOn request to a vApp URL powers on all of the virtual machines in the vApp, as specified in the vApp’s

ovf:StartupSection element.

A powerOn request to a virtual machine URL powers on the specified virtual machine and forces deployment

of the parent vApp.


82 VMware, Inc.

A powerOn request to a vApp or virtual machine that is undeployed forces deployment.

Example 5-21. Power On a vApp or Virtual Machine

Request to power on a vApp:

POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/powerOn

Request to power on a virtual machine:

POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/powerOn

Response:

202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Starting Virtual Application Linux FTP server (7) ...>

...</Task>

Power Off a vApp or Virtual Machine

A powerOff request to a vApp URL powers off all of the virtual machines in the vApp, as specified in its


A powerOff request to a virtual machine URL powers off the specified virtual machine.

Example 5-22. Power Off a vApp or Virtual Machine

Request to power off a vApp:

POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/powerOff

Request to power off a virtual machine:

POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/powerOff

Response:

202 Accepted...Content-Type: application/vnd.vmware.vcloud.task+xml<Task ...>

...</Task>

Reset a vApp or Virtual Machine

A reset request to a vApp URL resets all of the virtual machines in the vApp, as specified in its


A reset request to a virtual machine URL resets the specified virtual machine.

Example 5-23. Reset a vApp or Virtual Machine

Request to reset a vApp:

POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/reset

Request to reset a Vm:

POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/reset

VMware, Inc. 83


Response:


...</Task>

Suspend a vApp or Virtual Machine

A suspend request to a vApp URL suspends all of the virtual machines in the vApp, as specified in its


A suspend request to a virtual machine URL suspends the specified virtual machine.

Example 5-24. Suspend a vApp or Virtual Machine

Request to suspend a vApp:

POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/suspend

Request to suspend a Vm:

POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/suspend

Response:


...</Task>

Discard the Suspended State of a vApp or Virtual Machine

A discardSuspendedState request to a vApp URL discards the suspended state of all of the virtual machines

in the vApp, as specified in its ovf:StartupSection element.

A discardSuspendedState request to a virtual machine URL discards the suspended state of the specified

virtual machine.

You cannot resume a suspended vApp after its suspended state has been discarded.

Example 5-25. Discard the Suspended State of a vApp or Virtual Machine

Request to discard the suspended state of a vApp:

POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/discardSuspendedState

Request to discard the suspended state of a Vm:

POST http://vcloud.example.com/api/v1.0/vApp/vm-5/action/discardSuspendedState

Response:


...</Task>


84 VMware, Inc.

Shut Down a vApp or Virtual Machine

A shutdown request to a vApp URL shuts down all of the virtual machines in the vApp, as specified in its


A shutdown request to a virtual machine URL shuts down the specified virtual machine.

Example 5-26. Shut Down a vApp or Virtual Machine

Request to shut down a vApp:

POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/shutdown

Request to shut down a Vm:

POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/shutdown

Response:

204 No Content

Reboot a vApp or Virtual Machine

A reboot request to a vApp URL reboots all of the virtual machines in the vApp, as specified in its


A reboot request to a virtual machine URL reboots the specified virtual machine.

Example 5-27. Reboot a vApp or Virtual Machine

Request to reboot a vApp:

POST http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/reboot

Request to reboot a Vm:

POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/reboot

Response:

204 No Content

NOTE Because this request sends a signal to the guest OS, the vCloud API cannot track the progress or verify

the result of the requested operation.

NOTE Because this request sends a signal to the guest OS, the vCloud API cannot track the progress or verify

the result of the requested operation.

VMware, Inc. 85


List Media Devices of a Virtual Machine

You can make a GET request to the media URL of a Vm to return a list of all media devices attached to it.

Example 5-28. List Media Devices Attached to a Vm

Request:

GET http://vcloud.example.com/api/v1.0/vapp/vm-5/virtualHardwareSection/media

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.rasditemslist+xml...<RasdItemsList xmlns="http://www.vmware.com/vcloud/v1" ...href="http://vcloud.example.com/api/v1.0/vApp/vm-5/virtualHardwareSection/media" ... > <Item> <rasd:Address>0</rasd:Address> <rasd:Description>IDE Controller</rasd:Description> <rasd:ElementName>IDE Controller 0</rasd:ElementName> <rasd:InstanceID>1</rasd:InstanceID> <rasd:ResourceType>5</rasd:ResourceType> </Item> <Item> <rasd:AddressOnParent>0</rasd:AddressOnParent> <rasd:Description>CD/DVD Drive</rasd:Description> <rasd:ElementName>CD/DVD Drive 1</rasd:ElementName> <rasd:HostResource xmlns:vcloud="http://www.vmware.com/vcloud/v1"

vcloud:connected="false"></rasd:HostResource> <rasd:InstanceID>3000</rasd:InstanceID> <rasd:Parent>1</rasd:Parent> <rasd:ResourceType>15</rasd:ResourceType> </Item> <Item> <rasd:AddressOnParent>0</rasd:AddressOnParent> <rasd:Description>Floppy Drive</rasd:Description> <rasd:ElementName>Floppy Drive 1</rasd:ElementName> <rasd:HostResource xmlns:vcloud="http://www.vmware.com/vcloud/v1"

vcloud:connected="false"></rasd:HostResource> <rasd:InstanceID>8000</rasd:InstanceID> <rasd:ResourceType>14</rasd:ResourceType> </Item></RasdItemsList>

Insert Media Into a Virtual Machine

An insertMedia request makes a virtual media image readable by a Vm. The request must specify the

insertMedia URL of a Vm. The Media element in the request body must specify the href of the media image

to insert. When processing an insertMedia request, the server examines the type of the media specified in the

request and then attempts to insert it in a device of the appropriate type, starting with the device that has the

lowest bus number and lowest address on that bus.

Example 5-29. Insert Media Into a Virtual Machine

Request:

POST http://vcloud.example.com/api/v1.0/vapp/vm-5/media/action/insertMediaContent-Type: application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml<MediaInsertOrEjectParams xmlns="http://www.vmware.com/vcloud/v1">

<Media href="http://vcloud.example.com/api/v1.0/media/3"/></MediaInsertOrEjectParams>


86 VMware, Inc.

Response:


...</Task>

Eject Media from a Virtual Machine

An ejectMedia request reverses a specific insertMedia request. The request must specify the ejectMedia URL of a Vm that was previously the target of an insertMedia request. The Media element in the request body

must specify the href of the media image that was inserted by that request.

Example 5-30. Eject Media from a Virtual Machine

Request:

POST http://vcloud.example.com/api/v1.0/vapp/vm-5/media/action/ejectMediaContent-Type: application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml<MediaInsertOrEjectParams xmlns="http://www.vmware.com/vcloud/v1">

<Media href="http://vcloud.example.com/api/v1.0/media/3"/></MediaInsertOrEjectParams>

Response:


...</Task>

Get a Screen Thumbnail for a Virtual Machine

A screen request returns a thumbnail view of a virtual machine’s console encoded in png format.

Example 5-31. Get a Screen Thumbnail for a Virtual Machine

Request:

GET http://vcloud.example.com/api/v1.0/vApp/vm-4/screen

Response:

200 OKContent-type image/png...

...serialized contents of thumbnail in png format...

EOF

VMware, Inc. 87


Get a Screen Ticket for a Virtual Machine

An acquireTicket request returns a ticket that a client can use to gain access to the console of a virtual machine.

Example 5-32. Get a Screen Ticket for a Virtual Machine

Request:

POST http://vcloud.example.com/api/v1.0/vApp/vm-4/screen/action/acquireTicket

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.screenTicket+xml...<ScreenTicket xmlns="http://www.vmware.com/vcloud/v1"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1 ...>

mks://10.147.43.171/vm-61?ticket=Pznh4HMb7k%2FlniSLwyAD1fmlPIXOuSACKgEReF7ylTIn4qRkxhFv9QT7I3SLTAQu%2F7W5RxVpDxjVKuuHQ4VIwu59F%2FG1WL1OmYMWistJC9tkRjQ1RRQiB1Oem5E7qX9O

</ScreenTicket>

Provide User Input Requested by a Virtual Machine

A request for a virtual machine to change state (power on, suspend, reconfigure, and so on) might cause the

virtual machine to ask for additional user input before it can complete. A vApp that contains a Vm awaiting a

user response has status="5", and includes a link with rel="down" and type="application/vnd.vmware.vcloud.vmPendingQuestion+xml" that a client can GET to discover what input is needed. In this series of examples, a virtual machine that was recently reconfigured in vCenter

to add a new parallel port device and then powered on is requesting user input about where to send output

from the device. The powerOn request cannot complete until this input is supplied.

Example 5‐33 shows the link to the question, in the body of the vApp.

Example 5-33. vApp Requesting Input

Request:


Response:


...>...<Link rel="down" type="application/vnd.vmware.vcloud.vmPendingQuestion+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vm-5/question"/>...<Description>Example FTP Server</Description>...<Children>...</Children>

</vApp>


88 VMware, Inc.

Get a Request for User Input

In Example 5‐34, the client uses the vmPendingQuestion link returned in Example 5‐33 to get a

VmPendingQuestion document that includes the question and the set of choices allowed in the response.

Example 5-34. Get a Vm Pending Question

Request:

GET http://vcloud.example.com/api/v1.0/vApp/vm-5/question

Response:

200 OKContent-type: application/vnd.vmware.vcloud.vmPendingQuestion+xml ...

<VmPendingQuestion xmlns="http://www.vmware.com/vcloud/v1" ... ><Link type="application/vnd.vmware.vcloud.vmPendingAnswer+xml"

href="http://vcloud.example.com/api/v1.0/vApp/vm-5/question/action/answer"/><Question>msg.parallel.file.open:Parallel port output file

"/vmfs/volumes/d6162a46-58e50cab/linuxftp/vm-mgi.log" already exists. Do you want to replace it with any newly created content, or append new content to the end of the file?

</Question><QuestionId>50</QuestionId><Choices>

<Id>0</Id><Text>Append</Text>

</Choices><Choices>

<Id>1</Id><Text>Replace</Text>

</Choices><Choices>

<Id>2</Id><Text>Cancel</Text>

</Choices></VmPendingQuestion>

Provide Requested User Input

Example 5‐35 shows the a response, delivered by a POST to the question/answer link of the Vm.

Example 5-35. Answer a Vm Pending Question

Request:

POST http://vcloud.example.com/api/v1.0/vApp/vm-5/question/action/answerContent-type: application/vnd.vmware.vcloud.vmPendingAnswer+xml ...<VmQuestionAnswer xmlns="http://www.vmware.com/vcloud/v1">

<ChoiceId>2</ChoiceId><QuestionId>50</QuestionId>

</VmQuestionAnswer>

Response:

204 No Content

VMware, Inc. 89


Control Access to vAppsAccess control links for vApps are included in the vApp body. Example 5‐36, an excerpt from Example 2‐8 on

page 27, shows these links.

Example 5-36. Access Control Links for a vApp

<vApp ... >...<Link rel="down" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/controlAccess/"/><Link rel="controlAccess"

href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/controlAccess/"/>...

</vApp>

An organization administrator can use these links in the same kinds of requests shown in “Control Access to

Catalogs” on page 56.

Retrieve a TaskWhenever the result of a request cannot be returned immediately, the server creates a Task object and includes it in the response, as a member of the Tasks container in the response body. Each Task has an href value, which is a URL that the client can use to retrieve the Task element alone, without the rest of the response in

which it was contained. All information about the task is included in the Task element when it is returned in

the response’s Tasks container, so a client does not need to make an additional request to the Task URL unless it wants to follow the progress of a task that was incomplete.

Example 5‐37 retrieves that task that was returned in the response in Example 2‐6 on page 25.

Example 5-37. Retrieve a Task

Request:

GET http://vcloud.example.com/api/v1.0/task/1awvdrn82atz7yzsdey

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.task+xml...<Task status="running" startTime="2010-06-25T08:00:55.402-07:00" operation="Creating Virtual

Application Linux FTP server(7)" expiryTime="2010-09-23T08:00:55.402-07:00" type="application/vnd.vmware.vcloud.task+xml" href="http://vcloud.example.com/api/v1.0/task/1awvdrn82atz7yzsdey">


</Task>

Tasks expire after a configurable interval. The default interval is 24 hours.


90 VMware, Inc.

VMware, Inc. 91

6

The VMware vCloud API supports a variety of objects and operations that an organization administrator or

other privileged user can use to automate tasks associated with provisioning organizations and users, and

with allocation of resources to organization vDCs.


“Summary of Administrative Requests” on page 91

“Administrator Credentials and Privileges” on page 93

“Administrative Objects and URLs” on page 93

“Get an Administrative View of a Cloud” on page 93

“Organization Administration” on page 94

“Network Administration” on page 99

“vDC Administration” on page 102

“Catalog Administration” on page 107

“User Administration” on page 110

“Group Administration” on page 113

“Role Administration” on page 114

Summary of Administrative RequestsTable 6‐1 summarizes administrative requests supported in this release. The table uses the following

conventions:


id is an integer

Administrative Operations 6

Table 6-1. Summary of Administrative Requests


Get an Administrative View of a Cloud

GET API‐URL/admin None VCloud

Create an Organization POST API‐URL/admin/orgs AdminOrg AdminOrg

Get an Administrative View of an Organization

GET API‐URL/admin/org/id None AdminOrg

Modify an Organization PUT API‐URL/admin/org/id AdminOrg AdminOrg

List All Tasks Owned by an Organization

GET API‐URL/tasksList/id None TasksList


92 VMware, Inc.

Add a Network to an Organization POST API‐URL/admin/org/id/networks OrgNetwork OrgNetwork

Get an Administrative View of an Organization Network

GET API‐URL/admin/network/id None OrgNetwork

Modify an Organization Network PUT API‐URL/admin/network/id OrgNetwork Task

Remove an Organization Network DELETE API‐URL/admin/network/id None Task

Enable or Disable an Organization POST API‐URL/admin/org/id/action/enablePOST API‐URL/admin/org/id/action/disable

None 204 No Content

Remove an Organization DELETE API‐URL/admin/org/id None None

Examine the Contents of a Provider vDC

GET API‐URL/admin/providervdc/id None ProviderVdc

Allocate a vDC to an Organization POST API‐URL/admin/org/id/vdcs AdminVdc AdminVdc

List the Organization vDCs Supported by a Provider vDC

GET API‐URL/admin/providervdc/id/vdcReferences

None VdcReferences

Get an Administrative View of a vDC GET API‐URL/admin/vdc/id None AdminVdc

Modify a vDC PUT API‐URL/admin/vdc/id AdminVdc AdminVdc

Enable or Disable a vDC POST API‐URL/admin/vdc/id/action/enablePOST API‐URL/admin/vdc/id/action/disable

None 204 No Content

Remove a vDC DELETE API‐URL/admin/vdc/id None Task

Create a Catalog POST API‐URL/admin/org/id/catalogs Catalog Catalog

Get an Administrative View of a Catalog

GET API‐URL/admin/catalog/id None Catalog

Publish a Catalog POST API‐URL/admin/catalog/id/action/publish

PublishCatalogParams 204 No Content

Modify Catalog Metadata PUT API‐URL/admin/catalog/id Catalog Catalog

Remove a Catalog DELETE API‐URL/admin/catalog/id None 204 No Content

Create or Import a User POST API‐URL/admin/org/id/users User User

Get an Administrative View of a User GET API‐URL/admin/user/id None User

Modify User Metadata PUT API‐URL/admin/user/id User User

Remove a User DELETE API‐URL/admin/user/id None 204 No Content

Import a Group POST API‐URL/admin/org/id/groups Group Group

View Group Metadata GET API‐URL/admin/group‐id None Group

Modify Group Metadata PUT API‐URL/admin/group/id Group Group

Remove a Group DELETE API‐URL/admin/group/id None 204 No Content

Create a Role POST API‐URL/admin/roles Role Role

View Role Metadata GET API‐URL/admin/role/id None Role

Modify a Role PUT API‐URL/admin/role/id Role Role

Remove a Role DELETE API‐URL/admin/role/id None 204 No Content

View a Right GET API‐URL/admin/right/id None Right

Table 6-1. Summary of Administrative Requests (Continued)


VMware, Inc. 93

Chapter 6 Administrative Operations

Administrator Credentials and PrivilegesThe vCloud API defines two levels of administrative privilege:

Organization administrators, who have administrative privileges in a specific organization.

System administrators, who have superuser privileges throughout the system. System administrators can

create, read, update, and delete all objects in a vCloud, and have organization administrator rights in all

organizations in a vCloud, and can operate directly on vSphere resources to create and modify provider

vDCs.

Some administrative operations (and all vSphere platform operations) are restricted to the system

administrator. Before attempting any of these operations, log in to the System organization with the user name

and password of the system administrator account that was created when vCloud Service Director was

installed. For example, if the system administrator’s name and password had been defined as administrator and Pa55w0rd, the system administrator login credentials would be the MIME Base64 encoding of the string

administrator@System:Pa55w0rd.

The System organization is created automatically when vCloud Service Director is installed, and always has a

URL of the form API‐URL/org/1. It is not listed in an OrgList, but can be retrieved with an explicit GET

request, as shown in Example 6‐1.

Example 6-1. The System Organization

Request:


Response:

200 OKContent-Type: application/vnd.vmware.vcloud.org+xml

...<Org xmlns="http://www.vmware.com/vcloud/v1" name="System" ...>...

</Org>

Administrative Objects and URLsThe vCloud API defines several objects that are used only in administrative operations. These objects are listed

in Chapter 11, “Administrative API Reference,” on page 179. Some, like User, Group, and Role are unique to administrative operations. Others extend common vCloud API objects to add elements and attributes that

enable administrative control. An AdminOrg, for example, supports the administrative view of an Org, and an AdminVdc does the same thing for a Vdc.

Get an Administrative View of a CloudAn administrator can access a cloud‐wide namespace of administrative objects at API‐URL/admin, where

API‐URL is a URL of the form http://vcloud.example.com/api/v1.0. The primary administrative objects in a

vCloud include organizations, provider vDCs, rights, roles, and external networks. Each object type is

represented in a VCloud element by zero or more references, as illustrated in Example 6‐2. A system

administrator can obtain more information about any of these objects by making a GET request to the object

reference (the value of its href attribute).

The vCloud response document includes links that enable a system administrator to add roles and

organizations. Subordinate objects such as users, catalogs, and vDCs, are contained by individual

organizations and are not listed at this level. Other objects, such as rights, can be listed but cannot be modified

using the vCloud API.


94 VMware, Inc.

Example 6-2. List the Top-Level Administrative Objects in a vCloud

Request:

GET http://vcloud.example.com/api/v1.0/admin

Response:

200 OK Content-Type: application/vnd.vmware.admin.vcloud+xml...<VCloud name="vCloud" href="http://vcloud.example.com/api/v1.0/admin" ...>

<Link rel="add" type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/roles"/>

<Link rel="add" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0/admin/orgs"/>

<Description>Example Corporation’s vCloud</Description><OrganizationReferences>

<OrganizationReference type="application/vnd.vmware.admin.organization+xml" name="Engineering" href="http://vcloud.example.com/api/v1.0/admin/org/44"/>

<OrganizationReference ... />...

</OrganizationReferences><ProviderVdcReferences>

<ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="Main Provider" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/>

<ProviderVdcReference ... />...

</ProviderVdcReferences><RightReferences>

<RightReference type="application/vnd.vmware.admin.right+xml name="vApp_Deploy" href="http://vcloud.example.com/api/v1.0/admin/right/3"/>

<RightReference type="application/vnd.vmware.admin.right+xml name="Catalog: Sharing" href="http://vcloud.example.com/api/v1.0/admin/right/7"/>

<RightReference ... />...

</RightReferences><RoleReferences>

<RoleReference type="application/vnd.vmware.admin.role+xml" name="Organization Administrator" href="http://vcloud.example.com/api/v1.0/admin/role/102"/>

<RoleReference type="application/vnd.vmware.admin.role+xml" name="Catalog Creator" href="http://vcloud.example.com/api/v1.0/admin/role/103"/>

<RoleReference ... />...

</RoleReferences><Networks>

<Network type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1" href="http://vcloud.example.com/api/v1.0/admin/network/7"/>

<Network type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC2" href="http://vcloud.example.com/api/v1.0/admin/network/33"/>

<Network ... />...

</Networks></VCloud>

Organization AdministrationAn AdminOrg is an extended representation of an Org object, and is accessed at API‐URL/admin/org/id, rather than API‐URL/org/id. Although system administrators work with AdminOrg elements to create and

modify organizations, most modifications to an AdminOrg also modify some user‐visible property of the

corresponding Org.

VMware, Inc. 95


Create an Organization

To create an organization, a system administrator POSTs an AdminOrg body to the vCloud’s orgs URL, as shown in Example 6‐3.

The response echoes the request, with several important additions:

It includes both the administrative and user URLs for the new organization. The administrative URL is

the value of the href element of the AdminOrg body, and the user URL is the value of the Link where

rel="alternate".

It includes links that an administrator can use to modify or remove the new organization. For example,

an administrator could use this Link to add a catalog.

<Link rel="add" type="application/vnd.vmware.admin.catalog+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/catalogs"/>

Example 6-3. Create an Organization

Request:

POST http://vcloud.example.com/api/v1.0/admin/orgsContent-Type: application/vnd.vmware.admin.organization+xml...<AdminOrg xmlns="http://www.vmware.com/vcloud/v1" name="ExampleFinance"

type="application/vnd.vmware.admin.organization+xml"><Description>Example Corporation’s Finance Organization</Description><FullName>Finance</FullName><Settings>

<CanPublishCatalogs>true</CanPublishCatalogs><DeployedVMQuota>0</DeployedVMQuota><StoredVmQuota>0</StoredVmQuota><OrgLeaseSettings>

<DeleteOnStorageLeaseExpiration>false</DeleteOnStorageLeaseExpiration><DeploymentLeaseSeconds>604800</DeploymentLeaseSeconds><StorageLeaseSeconds>2592000</StorageLeaseSeconds>

</OrgLeaseSettings><OrgLdapMode>SYSTEM</OrgLdapMode><OrgEmailSettings>

<IsDefaultSmtpServer>true</IsDefaultSmtpServer><IsDefaultOrgEmail>true</IsDefaultOrgEmail><FromEmailAddress>[email protected]</FromEmailAddress><DefaultSubjectPrefix>Attention</DefaultSubjectPrefix><IsAlertEmailToAllAdmins>true</IsAlertEmailToAllAdmins><SmtpServerSettings>

<IsUseAuthentication>true</IsUseAuthentication><Host>smtp.example.com</Host><Username>[email protected]</Username>

</SmtpServerSettings></OrgEmailSettings>

</Settings></AdminOrg>

Response:

201 CreatedContent-Type: application/vnd.vmware.admin.organization+xml...<AdminOrg xmlns="http://www.vmware.com/vcloud/v1"

href="http://vcloud.example.com/api/v1.0/admin/org/26" name="ExampleFinance" type="application/vnd.vmware.admin.organization+xml">

<Link rel="down" type="application/vnd.vmware.vcloud.tasksList+xml" href="http://vcloud.example.com/api/v1.0/tasksList/26"/>


<Link rel="add" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/users"/>

<Link rel="add" type="application/vnd.vmware.admin.group+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/groups"/>


96 VMware, Inc.

<Link rel="add" type="application/vnd.vmware.admin.vdc+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/vdcs"/>

<Link rel="add" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/networks"/>

<Link rel="edit" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26"/>

<Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/org/26"/><Link rel="disable" href="http://vcloud.example.com/api/v1.0/admin/org/26/action/disable"/><Link rel="alternate" type="application/vnd.vmware.vcloud.org+xml"

href="http://vcloud.example.com/api/v1.0/org/26"/><Description>Example Corporation’s Finance Organization</Description><FullName>Finance</FullName><Settings>

<IsEnabled>false</IsEnabled><CanPublishCatalogs>true</CanPublishCatalogs><DeployedVMQuota>0</DeployedVMQuota><StoredVmQuota>0</StoredVmQuota><OrgLeaseSettings>

<DeleteOnStorageLeaseExpiration>false</DeleteOnStorageLeaseExpiration><DeploymentLeaseSeconds>604800</DeploymentLeaseSeconds><StorageLeaseSeconds>2592000</StorageLeaseSeconds>

</OrgLeaseSettings><OrgLdapMode>SYSTEM</OrgLdapMode><OrgEmailSettings>

<IsDefaultSmtpServer>true</IsDefaultSmtpServer><IsDefaultOrgEmail>true</IsDefaultOrgEmail><FromEmailAddress>[email protected]</FromEmailAddress><DefaultSubjectPrefix>Attention</DefaultSubjectPrefix><IsAlertEmailToAllAdmins>true</IsAlertEmailToAllAdmins><SmtpServerSettings>

<IsUseAuthentication>true</IsUseAuthentication><Host>smtp.example.com</Host><Username>[email protected]</Username>

</SmtpServerSettings></OrgEmailSettings>


Get an Administrative View of an Organization

To see an administrative view of an organization, an administrator can make a GET request to the

organization’s admin URL (the href element of the AdminOrg body), as shown in Example 6‐4. With the

exception of the HTTP response code (200 OK instead of 201 Created), the response to this request is identical

to the one returned in Example 6‐3, so we omit most of it from the example.

Example 6-4. Get an Administrative View of an Organization

Request:

GET http://vcloud.example.com/api/v1.0/admin/org/26

Response:

200 OKContent-Type:application/vnd.vmware.admin.organization+xml...<AdminOrg xmlns="http://www.vmware.com/vcloud/v1"

href="http://vcloud.example.com/api/v1.0/admin/org/26" name="ExampleFinance" type="application/vnd.vmware.admin.organization+xml">

<Link rel="down" type="application/vnd.vmware.vcloud.tasksList+xml" href="http://vcloud.example.com/api/v1.0/tasksList/26"/>

<Description>Example Corporation’s Finance Organization</Description>

VMware, Inc. 97


<FullName>Finance</FullName>...<Settings>

...</Settings>

</AdminOrg>

List All Tasks Owned by an Organization

An administrative view of an organization includes a Link with a rel="down" attribute that the administrator

can use to retrieve a list of all tasks owned by a user or object in an organization. The request in Example 6‐5

uses the tasksList URL returned in Example 6‐4 to return a TasksList element that contains several Task elements.

Example 6-5. List All Tasks Owned by an Organization

Request:

GET http://vcloud.example.com/api/v1.0/tasksList/26

Response:

200 OKContent-Type: application/vnd.vmware.vcloud.tasksList+xml...<TasksList name="Tasks Lists" type="application/vnd.vmware.vcloud.tasksList+xml"

href="http://vcloud.example.com/api/v1.0/tasksList/18" ...><Task... status="success" ... operation="Deleted Virtual Application Template (21)" ... >

...</Task><Task... status="error" ... operation="Powered On Virtual Machine WIn2K8 (15)" ... ><Error stackTrace="com.vmware.ssdc.library.exceptions.VimInvalidStateException

The operation could not be performed because the object is in an invalid state. Current state of the the VM is VMOn.at com.vmware.vcloud.val.internal.impl.VC20VirtualServer.throwVimInvalidStateException(VC20VirtualServer.java:292)at ...">

...</Task><Task... status="running" ... operation="Deleting Virtual Application (44)" ... >

...</Task>...

</TasksList>

Modify an Organization

As shown in Example 6‐3, an AdminOrg body includes rel="add" links for networks, vDCs, users, groups,

and catalogs. An organization administrator can use these links to add objects of those types to the

organization. To modify other attributes or elements of an AdminOrg, an organization administrator can make

a PUT request to its rel="edit" link and supply a modified version of the AdminOrg body. The request in Example 6‐6 modifies the default lease settings of the organization created in Example 6‐3.

NOTE If you modify an organization’s catalog publishing policy or LDAP options or modify a role, the

changes do not take effect for logged‐in users until the cache for the current session expires or the user logs

out and logs in again.


98 VMware, Inc.

Example 6-6. Modify an Organization

Request:

PUT http://vcloud.example.com/api/v1.0/admin/org/26Content-Type: application/vnd.vmware.admin.organization+xml...<AdminOrg xmlns="http://www.vmware.com/vcloud/v1" name="ExampleFinance">

<Description>Example Corporation’s Finance Organization</Description><FullName>Finance</FullName><Settings>

<OrgLeaseSettings><DeleteOnStorageLeaseExpiration>true</DeleteOnStorageLeaseExpiration><DeploymentLeaseSeconds>1209600</DeploymentLeaseSeconds><StorageLeaseSeconds>7776000</StorageLeaseSeconds>

</OrgLeaseSettings><OrgLdapMode>SYSTEM</OrgLdapMode>


Response:

200 OKContent-Type: application/vnd.vmware.admin.organization+xml...<AdminOrg name="ExampleFinance" type="application/vnd.vmware.admin.organization+xml" ...>


<Link rel="add" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/users"/>

...<Settings>

...<OrgLeaseSettings>

<DeleteOnStorageLeaseExpiration>true</DeleteOnStorageLeaseExpiration><DeploymentLeaseSeconds>1209600</DeploymentLeaseSeconds><StorageLeaseSeconds>7776000</StorageLeaseSeconds>

</OrgLeaseSettings></Settings>...

</AdminOrg>

Enable or Disable an Organization

An administrator can use the enable or disable action links in an AdminOrg body to enable or disable an organization, as shown in Example 6‐7. The enablement state of the AdminOrg is shown in its IsEnabled element.

Example 6-7. Disable an Organization

Request:

POST http://vcloud.example.com/api/v1.0/admin/org/26/action/disable

Response:

204 No Content

VMware, Inc. 99


Remove an Organization

An organization administrator can use the remove link in an AdminOrg body to remove the organization from

the vCloud. Example 6‐8 does this, making a DELETE request to the remove link returned in Example 6‐4.

Example 6-8. Remove an Organization

Request:

DELETE http://vcloud.example.com/api/v1.0/admin/org/26

Response:

204 No Content

Network AdministrationA newly created organization has no networks in it. An organization administrator must create an

organization network from resources provided by one of the external networks listed in the Networks element

of the VCloud response (see Example 6‐2 on page 94).

View the Properties of an External Network

To create an organization network, and organization administrator must choose a parent network from one of

the networks grouped in the Networks element of the cloud. To get more information about any of these

networks, an administrator can make a GET request to the network’s URL (the href element of the Network element). Example 6‐9 makes such a request to the href of a Network element returned in Example 6‐2 on

page 94. The response is an ExternalNetwork element that shows the Configuration and other properties of the network, including a ProviderInfo element that specifies details of the underlying vSphere network.

The ExternalNetwork element is read‐only.

Example 6-9. View the Properties of an External Network

Request:

GET http://vcloud.example.com/api/v1.0/admin/network/7

Response:

200 OKContent-Type:pplication/vnd.vmware.admin.network+xm...<ExternalNetwork xmlns="http://www.vmware.com/vcloud/v1"

href="http://vcloud.example.com/api/v1.0/admin/network/7" name="ExternalNetwork-VC1" ...>

<Description>VLAN 7</Description> <Configuration>

...</Configuration><ProviderInfo>

NETWORK:dvportgroup-1587 on com.vmware.vcloud.entity.vimserver:1043863313</ProviderInfo>

</ExternalNetwork>

NOTE Before you can remove an organization, you must disable it and delete or change ownership of all

objects that the organization users own.


100 VMware, Inc.

Add a Network to an Organization

An administrator can use the rel="add" link for networks in an AdminOrg body to add a network to the

organization. Example 6‐10 does this by making a POST request to the networks link returned in Example 6‐4.

The content of the FenceMode element in the request body specifies that organization network is bridged to

its ParentNetwork, whose href value was retrieved from one of the Network elements in the response in

Example 6‐2.

Example 6-10. Add a Network to an Organization

Request:

POST http://vcloud.example.com/api/v1.0/admin/org/26/networksContent-Type: application/vnd.vmware.admin.network+xml...<OrgNetwork name="Internet" xmlns="http://www.vmware.com/vcloud/v1">

<Description>Bridged to the public Internet</Description><Configuration>

<ParentNetwork type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1" href="http://vcloud.example.com/api/v1.0/admin/network/7"/>

<FenceMode>bridged</FenceMode></Configuration>

</OrgNetwork>

Response:

201 CreatedContent-Type: application/vnd.vmware.admin.network+xm...<OrgNetwork xmlns="http://www.vmware.com/vcloud/v1" name="Internet"

type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/54" ...>

<Link rel="alternate" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/54"/>

<Link rel="edit" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/54"/>

<Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/network/54"/><Link rel="up" type="application/vnd.vmware.admin.organization+xml"

href="http://vcloud.example.com/api/v1.0//org/26"/><Description>Bridged to the public Internet</Description><Tasks>

<Task ... operation="Creating Network Internet (2)" ... >...

</Task></Tasks><Configuration>

<IpScope><IsInherited>true</IsInherited><Gateway>10.147.122.190</Gateway><Netmask>255.255.255.192</Netmask><Dns1>10.115.120.71</Dns1><DnsSuffix>example.com</DnsSuffix><IpRanges>


</IpRange></IpRanges><AllocatedIpAddresses/>

</IpScope>

NOTE A NetworkPool element must be included in the request when creating network whose FenceMode is natRouted or isolated.

VMware, Inc. 101


<ParentNetwork type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1" href="http://vcloud.example.com/api/v1.0/admin/network/7"/>

<FenceMode>bridged</FenceMode></Configuration>

</OrgNetwork>

The response echoes the request, and contains some additional elements:

A Task that tracks creation of the network.

Additional members of the Configuration element that are inherited from the organization’s defaults,

because they were not specified in the request.

The same request with a different value for FenceMode contents would create a network with a different type

of connection to the parent. For more information, see “FenceMode” on page 155.

Get an Administrative View of an Organization Network

To see an administrative view of an organization network, an administrator can make a GET request to the

network’s admin URL (the href element of the OrgNetwork body), as shown in Example 6‐11. The response,

most of which is not shown here, would be identical to the one shown in Example 6‐10, but without the Tasks element.

Example 6-11. Get an Administrative View of an Organization Network

Request:

GET http://vcloud.example.com/api/v1.0/admin/network/54

Response:

200 OKContent-Type: application/vnd.vmware.admin.network+xm...<OrgNetwork xmlns="http://www.vmware.com/vcloud/v1" name="Internet"

type="application/vnd.vmware.admin.network+xml" ref="http://vcloud.example.com/api/v1.0/admin/network/54" ...>

...<Description>Bridged to the public Internet</Description>...

</OrgNetwork>

Modify an Organization Network

An administrator can use the rel="edit" link in an OrgNetwork body to modify the network’s name,

description, or configuration. Example 6‐12 does this by making a PUT request to the rel="edit" link returned in Example 6‐10. The request modifies the network’s FenceMode element and adds elements to the

Configuration to define the NAT service being added to the network.

Example 6-12. Modify a Network

Request:

PUT http://vcloud.example.com/api/v1.0/admin/network/54Content-Type: application/vnd.vmware.admin.network+xml...<OrgNetwork name="Internet" xmlns="http://www.vmware.com/vcloud/v1">

<Description>NAT-ed to the public Internet</Description><Configuration><ParentNetwork type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1"

href="http://vcloud.example.com/api/v1.0/admin/network/7"/><FenceMode>natRouted</FenceMode>

<Features><DhcpService>


102 VMware, Inc.

<IsEnabled>false</IsEnabled><DefaultLeaseTime>3600</DefaultLeaseTime><MaxLeaseTime>7200</MaxLeaseTime><IpRange>

<StartAddress>10.6.35.3</StartAddress><EndAddress>10.6.255.254</EndAddress>

</IpRange></DhcpService><FirewallService>

<IsEnabled>true</IsEnabled></FirewallService><NatService>

<IsEnabled>false</IsEnabled><NatType>portForwarding</NatType><Policy>allowTraffic</Policy>

</NatService></Features>

</Configuration></OrgNetwork>

Response:

202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Updating Network Internet (2)" ...>

...</Task>

Remove an Organization Network

An organization administrator can use the remove link in an OrgNetwork body to remove the network from

the organization. Example 6‐13 does this, making a DELETE request to the remove link returned in Example 6‐11.

Example 6-13. Remove a Network from an Organization

Request:

DELETE http://vcloud.example.com/api/v1.0/admin/network/54

Response:

202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Removing Network Internet (2)" ...>

...</Task>

vDC AdministrationA newly created organization has no vDCs in it. vDC administration involves the following objects:

A ProviderVdc, which a system administrator creates from vSphere platform resources (see “Create a

Provider vDC” on page 127).

An AdminVdc, which a system administrator creates to allocate a subset of ProviderVdc resources to a vDC in a specific organization. Organization members see an AdminVdc as a vDC.

VMware, Inc. 103


Examine the Contents of a Provider vDC

ProviderVdc objects are listed among the top‐level objects in a vCloud. in Example 6‐2 on page 94 illustrates

such a listing, which includes a ProviderVdcReferences element that contains references to the provider

vDCs registered to this vCloud.

<ProviderVdcReferences><ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml"

name="Main Provider" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/>

<ProviderVdcReference ... />...

</ProviderVdcReferences>

An administrator can use the value of the href attribute in any ProviderVdcReference as the target of a GET request. The response is a ProviderVdc body, as shown in Example 6‐14.

Example 6-14. Examine the Contents of a Provider vDC

Request:

GET http://vcloud.example.com/api/v1.0/admin/providervdc/2

Response:

200 OKContent-Type: application/vnd.vmware.admin.providervdc+xml...<ProviderVdc xmlns="http://www.vmware.com/vcloud/v1" status="1" name="PVDC_VC2"

type="application/vnd.vmware.admin.providervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2" ... >

<Link rel="up" href="http://vcloud.example.com/api/v1.0/admin/"/><Link rel="down" type="application/vnd.vmware.admin.vdcReferences+xml"

href="http://vcloud.example.com/api/v1.0/admin/providervdc/2/vdcReferences"/><Description>PVDC_VC2</Description><ComputeCapacity>

<Cpu><Units>MHz</Units><Allocation>21929</Allocation><Total>24675</Total><Used>10053</Used><Overhead>384</Overhead>

</Cpu><Memory>

<Units>MB</Units><Allocation>16207</Allocation><Total>24475</Total><Used>15771</Used><Overhead>977</Overhead>

</Memory></ComputeCapacity><StorageCapacity>

<Units>MB</Units><Allocation>1311368</Allocation><Total>2097152</Total><Used>489361</Used><Overhead>2436</Overhead>

</StorageCapacity><AvailableNetworks>

<Network type="application/vnd.vmware.admin.network+xml" name="External Network VC2" href="http://vcloud.example.com/api/v1.0/admin/network/54"/>

</AvailableNetworks><IsEnabled>true</IsEnabled><NetworkPoolReferences>

<NetworkPoolReference type="application/vnd.vmware.admin.networkPool+xml" name="VC2-Direct" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/22"/>


104 VMware, Inc.

<NetworkPoolReference type="application/vnd.vmware.admin.networkPool+xml" name="VC2_VLAN_Backed" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/2"/>

</NetworkPoolReferences></ProviderVdc>

List the Organization vDCs Supported by a Provider vDC

An administrator can use the href value from any ProviderVdcReference element in a VCloud as the target of a request that returns a list of organization vDCs that the provider vDC supports.

Example 6‐15 shows a request of this type, made using the href of the provider vDC shown in Example 6‐2

on page 94. The response, a VdcReferences element, indicates that the provider vDC at

http://vcloud.example.com/api/v1.0/admin/providervdc/2 is supporting the organization vDC, http://vcloud.example.com/api/v1.0/admin/vdc/44, created in Example 6‐16.

Example 6-15. List the Organization vDCs Supported by a Provider vDC

Request:

GET http://vcloud.example.com/api/v1.0/admin/providervdc/2/vdcReferences

Response:

<VdcReferences xmlns="http://www.vmware.com/vcloud/v1" ... ><Link rel="up" type="application/vnd.vmware.admin.providervdc+xml"

href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/><VdcReference type="application/vnd.vmware.admin.vdc+xml" name="org3vdc1"

href="http://vcloud.example.com/api/v1.0/admin/vdc/44"/></VdcReferences>

Allocate a vDC to an Organization

An organization administrator can allocate resources from a provider vDC to a vDC in an organization by

POSTing an AdminVdc body to an organization’s add URL for vDCs. Example 6‐4 includes such a URL:

<Link rel="add" type="application/vnd.vmware.admin.vdc+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/vdcs"/>

Example 6‐16 uses that URL to add a new vDC to the organization. The new vDC allocates resources from the

provider vDC specified in the ProviderVdcReference element in the request body. The contents of that

element were obtained from this element, shown in the response in Example 6‐2.

<ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="MainProvider" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/>

<ProviderVdcReference ... />

Example 6-16. Allocate a vDC to an Organization

Request:

POST http://vcloud.example.com/api/v1.0/admin/org/26/vdcsContent-Type: application/vnd.vmware.admin.vdc+xml...<AdminVdc name="org26vdc1" xmlns="http://www.vmware.com/vcloud/v1">

<Description>Example vDC</Description><AllocationModel>AllocationPool</AllocationModel><StorageCapacity>

<Units>MB</Units><Allocated>3072</Allocated><Limit>4096</Limit>


<Cpu>

VMware, Inc. 105


<Units>MHz</Units><Allocated>2048</Allocated><Limit>2048</Limit>

</Cpu><Memory>


</Memory></ComputeCapacity><NicQuota>0</NicQuota><NetworkQuota>0</NetworkQuota><ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml"


</AdminVdc>

Response:

201 CreatedContent-Type: application/vnd.vmware.admin.vdc+xm...<AdminVdc name="org26vdc1" type="application/vnd.vmware.admin.vdc+xml"

href="http://vcloud.example.com/api/v1.0/admin/vdc/44" ...><Link rel="up" type="application/vnd.vmware.admin.organization+xml"

href="http://vcloud.example.com/api/v1.0/admin/org/26"/><Link rel="edit" type="application/vnd.vmware.admin.vdc+xml"

href="http://vcloud.example.com/api/v1.0/admin/vdc/44"/><Link rel="disable" href="http://vcloud.example.com/api/v1.0/admin/vdc/44/action/disable"/><Link rel="alternate" href="http://vcloud.example.com/api/v1.0/vdc/44"/><Description>Example vDC</Description><Tasks>

<Task status="running" ... operation="Creating Virtual Datacenter (44)" ...>... </Task>

</Tasks><AllocationModel>AllocationPool</AllocationModel><StorageCapacity>



<Cpu><Units>MHz</Units><Allocated>2048</Allocated><Limit>2048</Limit>

</Cpu><Memory>


</Memory></ComputeCapacity><ResourceEntities/><AvailableNetworks>

<Network type="application/vnd.vmware.admin.network+xml" name="Internet" href="http://vcloud.example.com/api/v1.0/admin/network/54"/>

</AvailableNetworks><NicQuota>0</NicQuota><NetworkQuota>0</NetworkQuota><ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml"


</AdminVdc>


106 VMware, Inc.

The response echoes the request, and includes a Task element that tracks creation of the vDC. The network

created in Example 6‐10 appears in the AvailableNetworks element. If you added more networks to the

organization that contains this vDC, they would also appear in that element.

Get an Administrative View of a vDC

References to an organization’s vDCs are contained in the Vdcs element of the Org or AdminOrg body. To get an administrative view of a vDC, an administrator can make a GET request to its admin URL. The request returns an AdminVdc body, similar to the one shown in the response section of Example 6‐3.

Modify a vDC

To modify a vDC, make a PUT request to its edit link, and supply a modified version of the Vdc body. In Example 6‐17, the client modifies the vDC created in Example 6‐3 to change the values in the Cpu element, then

includes the modified body in a PUT request to the edit link that was returned when the vDC was created.

The response, only part of which is shown in the example, is an AdminVdc body containing the modified

values.

Example 6-17. Modify a vDC

Request:

PUT http://vcloud.example.com/api/v1.0/admin/vdc/44Content-Type: application/vnd.vmware.admin.vdc+xm<AdminVdc name="org3vdc1" xmlns="http://www.vmware.com/vcloud/v1">

<Description>Example vDC</Description><AllocationModel>AllocationPool</AllocationModel><StorageCapacity>



<Cpu><Units>MHz</Units><Allocated>4096</Allocated><Limit>4096</Limit>

</Cpu><Memory>


</Memory></ComputeCapacity><NicQuota>0</NicQuota><NetworkQuota>0</NetworkQuota><ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml"


</AdminVdc>

Response:

200 OKContent-Type: application/vnd.vmware.admin.vdc+xm...<AdminVdc name="org26vdc1" type="application/vnd.vmware.admin.vdc+xml"

href="http://vcloud.example.com/api/v1.0/admin/vdc/44" ...>...<Tasks>

<Task status="running" ... operation="Updating Virtual Datacenter (44)"...>... </Task>

</Tasks>

VMware, Inc. 107


<ComputeCapacity><Cpu>

<Units>MHz</Units><Allocated>4096</Allocated><Limit>4096</Limit>

</Cpu>...

</ComputeCapacity>...

</AdminVdc>

Enable or Disable a vDC

An administrator can use the enable or disable action links in an AdminVdc body to enable or disable a vDC. The request and response are similar to those shown in Example 6‐7 on page 98. The enablement state of the

vDC is shown in its IsEnabled element.

Remove a vDC

Before you can remove a vDC, you must disable it. After the vDC has been disabled, its representation includes

a rel="remove" link. An administrator can make a DELETE request to that link to remove a vDC from an

organization.

Example 6-18. Remove a vDC

Request:

DELETE http://vcloud.example.com/api/v1.0/admin/vdc/6

Response:

202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Deleted Virtual Datacenter (6)" ...>

...</Task>

Catalog AdministrationA newly created organization has no catalogs in it. An organization administrator must create them and

specify their scope before items can be catalogued. You do not have to be an administrator to add or remove

CatalogItem elements. See “Cataloging vApp Templates and Media Images” on page 54.

Create a Catalog

Every organization has an add URL for catalogs. An administrator can create a catalog by POSTing a Catalog body to this URL. Example 6‐19 does this, using the URL in this Link shown in Example 6‐3.


The response echoes the request, and includes these additions created by the server.

A URL (the value of the href attribute of the response body) that references the new catalog.

Links that a client can use to request operations like add an item to the catalog, edit catalog properties, or

remove the catalog.

A link to the alternate (user) view of this catalog

An empty CatalogItems element


108 VMware, Inc.

A Task that tracks the creation of the catalog

An IsPublished element whose content is the string false.

Example 6-19. Create a Catalog

Request:

POST http://vcloud.example.com/api/v1.0/admin/org/26/catalogsContent-Type: application/vnd.vmware.admin.catalog+xml<Catalog name="Custom Catalog" xmlns="http://www.vmware.com/vcloud/v1">

<Description>Custom Catalog</Description></Catalog>

Response:

201 CreatedContent-Type: application/vnd.vmware.admin.catalog+xml...<Catalog href="http://vcloud.example.com/api/v1.0/catalog/32" name="Custom Catalog" ...>

<Description>Custom Catalog</Description><Tasks>

<Task ...>...

<Task><Tasks><Link rel="up" type="application/vnd.vmware.admin.organization+xml"

href="http://vcloud.example.com/api/v1.0/admin/org/26"/><Link rel="alternate" href="http://vcloud.example.com/api/v1.0/catalog/32"/><Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml"

href="http://vcloud.example.com/api/v1.0/catalog/32/catalogItems"/><Link rel="edit" type="application/vnd.vmware.vcloud.catalog+xml"

href="http://vcloud.example.com/api/v1.0/catalog/32"/><Link rel="remove" href="http://vcloud.example.com/api/v1.0/catalog/32"/><Link rel="publish" href="http://vcloud.example.com/api/v1.0/catalog/32/action/publish"/><CatalogItems/><IsPublished>false</IsPublished>

</Catalog>

Get an Administrative View of a Catalog

An administrative view of a catalog is nearly identical to a user view but contains additional action links that

support administrative operations such as edit and remove. To see an administrative view of a catalog, an

administrator can make a GET request to its admin URL, as shown in Example 6‐20. For a user view of the

same catalog, see Example 3‐2 on page 35.

Example 6-20. Get an Administrative View of a Catalog

Request:

GET http://vcloud.example.com/api/v1.0/admin/catalog/32

Response:

200 OKContent-Type: application/vnd.vmware.admin.catalog+xml...<Catalog .... >

...<Link rel="edit" href="http://vcloud.example.com/api/v1.0/admin/catalog/32"/><Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/catalog/32"/>

VMware, Inc. 109


<Description>Custom Catalog</Description><CatalogItems>

...</CatalogItems>...

</Catalog>

Publish a Catalog

Publishing a catalog makes the catalog visible to all organizations in a vCloud. An administrator of an

organization that can publish catalogs (one whose CanPublishCatalogs element has a value of true) can publish a catalog by making a POST request to the catalog’s publish URL and supplying a PublishCatalogParams body that sets the value of the catalog’s IsPublished element to true. Example 6‐21

publishes the catalog created in Example 6‐19.

Example 6-21. Publish a Catalog

Request:

POST http://vcloud.example.com/api/v1.0/admin/catalog/32/action/publishContent-Type: application/vnd.vmware.admin.publishCatalogParams+xml...<PublishCatalogParams xmlns="http://www.vmware.com/vcloud/v1">

<IsPublished>true</IsPublished></PublishCatalogParams>

Response:

204 No Content

Modify Catalog Metadata

An administrator can modify catalog metadata such as its name and description by creating a modified

Catalog body and PUTting it to the catalog’s edit link. The request in Example 6‐22 changes the name and

description of the catalog created in Example 6‐19. The response contains the modified Catalog body, including the CatalogItems element, which was unchanged by, and not included in, the request.

Example 6-22. Modify Catalog Metadata

Request:

PUT http://vcloud.example.com/api/v1.0/admin/catalog/32Content-Type: application/vnd.vmware.admin.catalog+xml<Catalog name="TechOps Catalog 01" xmlns="http://www.vmware.com/vcloud/v1">

<Description>TechOps Approved Templates Catalog</Description></Catalog>

Response:

200 OKContent-Type: application/vnd.vmware.admin.catalog+xml<Catalog href="http://vcloud.example.com/api/v1.0/catalog/32" name="TechOps Catalog 01" ...>

<Description>TechOps Approved Templates Catalog</Description><Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml"

href="http://vcloud.example.com/api/v1.0/catalog/32/catalogItems"/>


110 VMware, Inc.

<CatalogItems><CatalogItem name="Ubuntu Template with vsftpd"

type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221">

<Description>Approved template for public FTP sites</Description><Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/><Property key="Owner">Tech Ops</Property>

</CatalogItem></CatalogItems>

</Catalog>

Remove a Catalog

An administrator can remove a catalog by making a DELETE request to the catalog’s rel="remove" URL. Example 6‐23 removes the catalog created in Example 6‐19.

Example 6-23. Remove a Catalog

Request:

DELETE http://vcloud.example.com/api/v1.0/admin/catalog/32

Response:

204 No Content

User AdministrationUsers can be created in an organization or imported into the organization from an LDAP directory service.

Create or Import a User

Every user exists within the context of an organization. An administrator can add a user to an organization by

POSTing a User body to the organization’s add URL for users, as shown in Example 6‐24, which adds the user

to the organization created in Example 6‐3. The response is a User element, most of which is not shown in the

example. The element includes a link that an administrator can use to edit the user, and additional elements,

such as IsDefaultCached and StoredVmQuota, inherited from organization defaults.

Example 6-24. Create a User

Request:

POST http://vcloud.example.com/api/v1.0/admin/org/26/usersContent-Type: application/vnd.vmware.admin.user+xml<User name="ExampleUser" xmlns="http://www.vmware.com/vcloud/v1">

<FullName>Example User Full Name</FullName><EmailAddress>[email protected]</EmailAddress><IsEnabled>true</IsEnabled><Role type="application/vnd.vmware.admin.role+xml"

href="http://vcloud.example.com/api/v1.0/admin/role/105"/><Password>Pa55w0rd</Password>

</User>

NOTE Modifying catalog metadata does not affect CatalogItem elements. You cannot create a catalog that

has CatalogItem elements in it. They must be added in a separate operation. For information about adding

and removing these elements, see “Cataloging vApp Templates and Media Images” on page 54.

VMware, Inc. 111


Response:

201 CreatedContent-Type: application/vnd.vmware.admin.user+xml...<User name="ExampleUser" type="application/vnd.vmware.admin.user+xml"

href="http://vcloud.example.com/api/v1.0/admin/user/85" ...><Link rel="edit" type="application/vnd.vmware.admin.user+xml"

href="http://vcloud.example.com/api/v1.0/admin/user/85"/><FullName>Example User Full Name</FullName><EmailAddress>[email protected]</EmailAddress><IsEnabled>true</IsEnabled><IsAlertEnabled>false</IsAlertEnabled><IsDefaultCached>false</IsDefaultCached><StoredVmQuota>0</StoredVmQuota><DeployedVmQuota>0</DeployedVmQuota><Role type="application/vnd.vmware.admin.role+xml"

href="http://vcloud.example.com/api/v1.0/admin/role/105"/><GroupReferences/>

</User>

To import a user from an LDAP directory service, POST a User body whose name attribute specifies the user’s name in the LDAP directory, and includes an IsExternal element with a value of true. The server matches

the value of the name attribute in the request body with the value of the LDAP attribute that the organization

has specified for the user name (the value of the UserName element in UserAttributes), and imports that user

from LDAP. See “UserAttributes” on page 184.

Example 6‐25 illustrates this sort of request.

Example 6-25. Import a User from LDAP

Request:

POST http://vcloud.example.com/api/v1.0/admin/org/26/usersContent-Type: application/vnd.vmware.admin.user+xml...<User name="[email protected]" type="application/vnd.vmware.admin.user+xml"

xmlns="http://www.vmware.com/vcloud/v1"><IsExternal>true</IsExternal><Role type="application/vnd.vmware.admin.role+xml"

href="http://vcloud.example.com/api/v1.0/admin/role/105"/></User>

Response:

201 CreatedContent-Type: application/vnd.vmware.admin.user+xml...<User name="[email protected]" type="application/vnd.vmware.admin.user+xml"


href="http://vcloud.example.com/api/v1.0/admin/user/85"/><FullName>Example User</FullName><EmailAddress>[email protected]</EmailAddress><IsEnabled>false</IsEnabled><IM/><NameInSource>\F4\D3\42\8E\6A\BC\D3</NameInSource><IsAlertEnabled>false</IsAlertEnabled><IsDefaultCached>false</IsDefaultCached><StoredVmQuota>0</StoredVmQuota><DeployedVmQuota>0</DeployedVmQuota><Role type="application/vnd.vmware.admin.role+xml"


</User>


112 VMware, Inc.

FullName and EmailAddress are retrieved from LDAP. Values for IsEnabled, Description, and other elements can be specified in the request body or add later. See “Modify User Metadata” on page 112.

Get an Administrative View of a User

Each user in an organization is represented by a UserReference element. A GET request to the URL in the

href attribute of a UserReference returns a User element in the response, as shown in Example 6‐26.

Example 6-26. Get an Administrative View of a User

Request:

GET http://vcloud.example.com/api/v1.0/admin/user/85

Response:

200 OKContent-Type: application/vnd.vmware.admin.user+xml...<User name="[email protected]" type="application/vnd.vmware.admin.user+xml"


href="http://vcloud.example.com/api/v1.0/admin/user/85"/><FullName>Example User Full Name</FullName><EmailAddress>[email protected]</EmailAddress><Telephone/><IsEnabled>true</IsEnabled><IM/><NameInSource>[email protected]</NameInSource><IsAlertEnabled>false</IsAlertEnabled><IsDefaultCached>false</IsDefaultCached><StoredVmQuota>1000</StoredVmQuota><DeployedVmQuota>100</DeployedVmQuota><Role type="application/vnd.vmware.admin.role+xml" name="User"


</User>

Modify User Metadata

An administrator can use the edit link in a User element to modify user metadata. The request in

Example 6‐27 disables the User object by setting value of its IsEnabled element to false. As is the case with

all requests, the request body must include all required elements, whether or not you are changing them. The

response is the full User element, including the changed metadata, and includes the links and other metadata

typically supplied by the server.

Example 6-27. Modify User Metadata

Request:

PUT http://vcloud.example.com/api/v1.0/admin/user/85Content-Type: application/vnd.vmware.admin.user+xml...<User name="ExampleUser" xmlns="http://www.vmware.com/vcloud/v1">

<IsEnabled>false</IsEnabled><Role type="application/vnd.vmware.admin.role+xml"

href="http://vcloud.example.com/api/v1.0/admin/role/105"/></User>

VMware, Inc. 113


Response:

200 OKContent-Type: application/vnd.vmware.admin.user+xml...<User name="[email protected]" type="application/vnd.vmware.admin.user+xml"


href="http://vcloud.example.com/api/v1.0/admin/user/85"/><Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/user/85"/><FullName>Example User Full Name</FullName><EmailAddress>[email protected]</EmailAddress><Role type="application/vnd.vmware.admin.role+xml"

href="http://vcloud.example.com/api/v1.0/admin/role/105"/><IsEnabled>false</IsEnabled>

</User>

Remove a User

Before you can remove a user, you must disable the User object by changing the value of its IsEnabled element to false, as shown in Example 6‐27. After it has been disabled, the User element contains a link

where rel="remove". An administrator can use this link remove the user from the organization, as shown in

Example 6‐28.

Example 6-28. Remove a User

Request:

DELETE http://vcloud.example.com/api/v1.0/admin/user/85

Response:

204 No Content

Group AdministrationGroups must be imported from LDAP. You cannot use the vCloud API to add or remove group members, or

change the name of the group. Instead, you must make the changes in the source LDAP database and then

import the group again.

Import a Group

To import a group from an LDAP directory service, POST an empty Group body to the organization’s add URL for groups. The value of the name attribute in the request body must match the value of the group’s name attribute in LDAP.

Example 6-29. Import a Group from LDAP

Request:

POST http://vcloud.example.com/api/v1.0/admin/org/26/groupsContent-Type: application/vnd.vmware.admin.group+xml<Group name="Engineering" xmlns="http://www.vmware.com/vcloud/v1">

<Role type="application/vnd.vmware.admin.role+xml" name="vApp Wrangler" href="http://vcloud.example.com/api/v1.0/admin/role/102"/>

</Group>


114 VMware, Inc.

Response:

201 CreatedContent-Type: application/vnd.vmware.admin.user+xml...<Group name="Engineering" type="application/vnd.vmware.admin.group+xml"

href="http://vcloud.example.com/api/v1.0/admin/group/44" ...> <Link rel="edit" type="application/vnd.vmware.admin.group+xml"

href="http://vcloud.example.com/api/v1.0/admin/group/44"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/group/44"/> <Description>Research and development</Description> ...

<UsersList/> <Role type="application/vnd.vmware.admin.role+xml" name="vApp Wrangler"

href="http://vcloud.example.com/api/v1.0/admin/role/102"/></Group>

View Group Metadata

Each group in an organization can be referenced by the URL contained in one of its GroupReference elements. These elements are contained by the Groups element of an AdminOrg body. A group’s URL also appears in the response to the request that imports the group. An administrator can GET a group URL to view

the Group body.

Modify Group Metadata

An administrator can modify a Group body to change its Description or Role by PUTting a modified Group body to the edit URL for the group. See Example 6‐27 for an example of the workflow for this type of request.

Remove a Group

An administrator can use the remove link in a Group body to remove a group from a vCloud. Example 6‐30

removes the group imported in Example 6‐29.

Example 6-30. Remove a Group

Request:

DELETE http://vcloud.example.com/api/v1.0/admin/group/44

Response:

204 No Content

Role AdministrationA role associates the name of a user or group with a set of rights. Role names must be unique in a vCloud

instance.

Create a Role

A system administrator can create a role by aggregating a set of rights in a Role body, and then POSTing the body to the add URL for roles. Example 6‐31 creates a new role named vAppWrangler and adds it to the

vCloud shown in Example 6‐2. The response, like other responses to requests that create an object, includes

the POSTed content, a link to the new object, and links of type edit and remove that an administrator can use

to manage this role.

VMware, Inc. 115


Example 6-31. Create a Role

Request:

POST http://vcloud.example.com/api/v1.0/admin/rolesContent-Type: application/vnd.vmware.admin.role+xml<Role name="vAppWrangler" xmlns="http://www.vmware.com/vcloud/v1">

<Description>Create and manage vApps</Description><RightReferences>

<RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: View" href="http://vcloud.example.com/api/v1.0/admin/right/16"/>

<RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: Power Operations" href="http://vcloud.example.com/api/v1.0/admin/right/9"/>

<RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: Download" href="http://vcloud.example.com/api/v1.0/admin/right/11"/>


</RightReferences></Role>

Response:

201 CreatedContent-Type: application/vnd.vmware.admin.role+xml...<Role name="vAppWrangler" type="application/vnd.vmware.admin.role+xml"

href="http://vcloud.example.com/api/v1.0/admin/role/102" ...><Link rel="edit" type="application/vnd.vmware.admin.role+xml"

href="http://vcloud.example.com/api/v1.0/admin/role/102"/><Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/role/102"/><Description>Create and manage vApps</Description><RightReferences>






View Role Metadata

URLs for all roles in a vCloud appear as RoleReference elements in a vCloud body. An individual role’s URL is also displayed in the response to a request that creates the role A system administrator can GET a role URL

to view the Role body. Example 6‐32 does this for the role created in Example 6‐31.

Example 6-32. View Role Metadata

Request:

GET http://vcloud.example.com/api/v1.0/admin/role/102

Response:

200 OKContent-Type: application/vnd.vmware.admin.role+xml...<Role name="vApp Wrangler" type="application/vnd.vmware.admin.role+xml"

href="http://vcloud.example.com/api/v1.0/admin/role/102" ...>


116 VMware, Inc.

<Link rel="edit" type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/102"/>

<Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/role/102"/><Description>Create and manage vApps</Description><RightReferences>






Modify a Role

A system administrator can modify a role to add or remove rights or change the name of the role by PUTting

a modified Role body to the edit URL of the Role. See Example 6‐27 for an example of the workflow for this

type of request.

Remove a Role

A system administrator can use the remove link in a Role element to remove a role from a vCloud.

Example 6‐33 removes the role created in Example 6‐31.

Example 6-33. Remove a Role

Request:

DELETE http://vcloud.example.com/api/v1.0/admin/role/102

Response:

204 No Content

View a Right

A system administrator can view, but not modify, the contents of a Right element, as shown in Example 6‐34,

which provides a view of one of the RightReferences shown in Example 6‐2.

Example 6-34. View a Right

Request:

GET http://vcloud.example.com/api/v1.0/admin/right/7

Response:

200 OKContent-Type: application/vnd.vmware.admin.right+xml...<Right xmlns="http://www.vmware.com/vcloud/v1" name="Catalog: Sharing"

type="application/vnd.vmware.admin.right+xml" href="http://vcloud.example.com/api/v1.0/admin/right/7" ... >

<Description>Share a Catalog</Description><Category>catalog</Category>

</Right>

VMware, Inc. 117

7

The VMware vCloud API includes extensions that support a variety of operations on the vSphere Platform,

which provides resources to a VMware vCloud.


“Summary of vSphere Platform Operations Requests” on page 117

“List vSphere Platform Operations and Objects for a vCloud” on page 119

“List Provider vDCs in a vCloud” on page 120

“List Network Pools in a vCloud” on page 120

“List vCenter Servers Registered to a vCloud” on page 120

“List ESX/ESXi Hosts in a vCloud” on page 124

“Create a Provider vDC” on page 127

“Create an External Network” on page 133

“Create a Network Pool” on page 136

“Import a Virtual Machine from vCenter” on page 138

Summary of vSphere Platform Operations RequestsTable 7‐1 summarizes vSphere platform operations requests supported in this release. The table uses the

following conventions:

API‐URL is a URL of the form http://vcloud.example.com/api/v1.0.

id is an integer.

VMware vSphere Platform Operations 7

NOTE All vSphere platform operations are restricted to the system administrator. Before attempting any of

these operations, log in to the System organization with the user name and password of the system

administrator account that was created when Cloud Director was installed. For more information, see

“Administrator Credentials and Privileges” on page 93.

Table 7-1. Summary of vSphere Platform Operations Requests


List vSphere Platform Operations and Objects for a vCloud

GET API‐URL/admin/extension None VMWExtension

List Provider vDCs in a vCloud

GET API‐URL/admin/extension/providerVdcReferences

None VMWProviderVdcReferences

List External Networks in a vCloud

GET API‐URL/admin/extension/externalNetworkReferences

None VMWExternalNetworkReferences


118 VMware, Inc.

List Network Pools in a vCloud

GET API‐URL/admin/extension/networkPoolReferences

None VMWNetworkPoolReferences

List vCenter Servers Registered to a vCloud

GET API‐URL/admin/extension/vimServerReferences

None VMWVimServerReferences

Get Information About a vCenter Server

GET API‐URL/admin/extension/vimServer/id

None VimServer

List Available Resource Pools on a vCenter Server

GET API‐URL/admin/extension/vimServer/id/resourcePoolList

None ResourcePoolList

Modify vCenter Server Settings

PUT API‐URL/admin/extension/vimServer/id/

VimServer Task

Register a vCenter Server and vShield Manager

POST API‐URL/admin/extension/action/registervimserver

RegisterVimServerParams RegisterVimServerParams

Unregister a vCenter Server and vShield Manager

POST API‐URL/admin/extension/vimServer/id/action/unregister

None Task

Force Reconnection to a vCenter Server

POST API‐URL/admin/extension/vimServer/id/forcevimserverreconnect

None 204 No Content

List ESX/ESXi Hosts in a vCloud

GET API‐URL/admin/extension/hostReferences

None VMWHostReferences

Get Information About a Host

GET API‐URL/admin/extension/host/id

None Host

Prepare a Host POST API‐URL/admin/extension/host/id/action/prepare

PrepareHostParams Task

Unprepare a Host POST API‐URL/admin/extension/host/id/action/unprepare

None Task

Enable or Disable a Host

POST API‐URL/admin/extension/host/id/action/enable

POST API‐URL/admin/extension/host/id/action/disable

None 204 No Content

Repair a Host POST API‐URL/admin/extension/host/id/action/repair

None 204 No Content

Upgrade a Host Agent POST API‐URL/admin/extension/host/id/action/upgrade

None Task

Create a Provider vDC POST API‐URL/admin/extension/providervdcs

VMWProviderVdc VMWProviderVdc

Examine the vSphere Objects in a Provider vDC

GET API‐URL/admin/extension/providervdc/id

None VMWProviderVdc

Modify a Provider vDC PUT API‐URL/admin/extension/providervdcs

VMWProviderVdc VMWProviderVdc

Enable or Disable a Provider vDC

POST API‐URL/admin/extension/providervdc/id/action/enablePOST API‐URL/admin/extension/providervdc/id/action/disable

None 204 No Content

Remove a Provider vDC

DELETEAPI‐URL/admin/extension/providervdc/id

None Task

Create an External Network

POST API‐URL/admin/extension/externalnets

VMWExternalNetwork VMWExternalNetwork

Table 7-1. Summary of vSphere Platform Operations Requests (Continued)


VMware, Inc. 119

Chapter 7 VMware vSphere Platform Operations

List vSphere Platform Operations and Objects for a vCloudAll resources exposed to vCloud tenants through provider vDCs originate in vCenter instances registered to

the vCloud service. A system administrator can request a list of vSphere objects currently registered for use

with a vCloud. The response also include links to actions that allow the system administrator to add or register

new vSphere objects. Example 7‐1 shows an example of such a request.

Example 7-1. List All vSphere Platform Operations and Objects for a vCloud

Request:

GET http://vcloud.example.com/api/v1.0/admin/extension

Response:

200 OKContent-Type: application/vnd.vmware.admin.vmwextension+xml ...<vmext:VMWExtension xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" ... >

<vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwProviderVdcReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/providerVdcReferences"/>

<vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwExternalNetworkReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/externalNetworkReferences"/>

<vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwNetworkPoolReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPoolReferences"/>

<vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwVimServerReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServerReferences"/>

<vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwHostReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/hostReferences"/>

<vcloud:Link rel="add" type="application/vnd.vmware.admin.vmwprovidervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdcs"/>

<vcloud:Link rel="add" type="application/vnd.vmware.admin.vmwexternalnet+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnets"/>

Get Information About an External Network

GET API‐URL/admin/extension/externalnet/id

none VMWExternalNetwork

Modify an External Network

PUT API‐URL/admin/extension/externalnet/id

VMWExternalNetwork VMWExternalNetwork

Remove an External Network

DELETEAPI‐URL/admin/extension/externalnet/id

none Task

Create a Network Pool POST API‐URL/admin/extension/networkPools

VMWNetworkPool VMWNetworkPool

Get Information About a Network Pool

GET API‐URL/admin/extension/networkPool/id

None VMWExternalNetwork

Modify a Network Pool PUT API‐URL/admin/extension/networkPool/id

VMWNetworkPool VMWNetworkPool

Remove a Network Pool

PUT API‐URL/admin/extension/networkPool/id

None 204 No Content

Import a Virtual Machine as a vApp

POST API‐URL/admin/extension/vimServer/id/importVmAsVapp

ImportVmAsVAppParams VApp

Import a Virtual Machine as a vApp Template

POST API‐URL/admin/extension/vimServer/id/importVmAsVappTemplate

ImportVmAsVAppTemplateParams

VAppTemplate

Table 7-1. Summary of vSphere Platform Operations Requests (Continued)



120 VMware, Inc.

<vcloud:Link rel="add" type="application/vnd.vmware.admin.networkPool+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPools"/>

<vcloud:Link rel="register" type="application/vnd.vmware.admin.registerVimServerParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/action/registervimserver"/>

<vcloud:Link rel="down" type="application/vnd.vmware.admin.licensingReportList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/licensing/reports"/>

</vmext:VMWExtension>

List Provider vDCs in a vCloudA system administrator can use the providerVdcReferences link returned in a VMWExtension response to request a list of all provider vDCs in the vCloud. Example 7‐2 makes such a request, using the

providerVdcReferences link returned in Example 7‐1.

Example 7-2. List Provider vDCs in a vCloud

Request:

GET http://vcloud.example.com/api/v1.0/admin/extension/providerVdcReferences

Response:

200 OKContent-Type: application/vnd.vmware.admin.vmwprovidervdcreferences+xml ...<vmext:VMWProviderVdcReferences xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" ... >

<vcloud:Link rel="up" type="application/vnd.vmware.admin.vmwExtension+xml" href="http://vcloud.example.com/api/v1.0/admin/extension"/>

<vmext:ProviderVdcReference type="application/vnd.vmware.admin.vmwprovidervdc+xml" name="PVDC-VC3" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/1"/>

<vmext:ProviderVdcReference ... ><vmext:ProviderVdcReference ... >

</vmext:VVMWProviderVdcReferences>

List External Networks in a vCloudThis operation follows the model shown in Example 7‐2, but uses the externalNetworkReferences link from the VMWExtension response as the target of the request. The response is a VMWExternalNetworkReferences element.

List Network Pools in a vCloudThis operation follows the model shown in Example 7‐2, but uses the networkPoolReferences link from the VMWExtension response as the target of the request. The response is a NetworkPoolReferences element.

List vCenter Servers Registered to a vCloudThis operation follows the model shown in Example 7‐2, but uses the vimServerReferences link from the VMWExtension response as the target of the request. The response is a VMWVimServerReferences element.

Get Information About a vCenter Server

A system administrator can use the href attribute value of any VimServerReference in a VMWVimServerReferences element to get more information about a specific vCenter server, as shown in

Example 7‐3.

VMware, Inc. 121


Example 7-3. Get Information About a vCenter Server

Request:

GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100

Response:

200 OK Content-Type: application/vnd.vmware.admin.vmwvirtualcenter+xml...<vmext:VimServer xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="VC-02" ... ><vcloud:Link rel="down" type="application/vnd.vmware.admin.vmsObjectRefsList+xml"

href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/vmsList"/>

<vcloud:Link rel="down" type="application/vnd.vmware.admin.resourcePoolList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/resourcePoolList"/>

<vcloud:Link rel="add" type="application/vnd.vmware.admin.importVmAsVAppParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/importVmAsVApp"/>

<vcloud:Link rel="add" type="application/vnd.vmware.admin.importVmAsVAppTemplateParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/importVmAsVAppTemplate"/>

<vcloud:Link rel="unregister" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/action/unregister"/>

<vcloud:Description>vCenter created by the Configuration Wizard</vcloud:Description><vmext:Username>administrator</vmext:Username><vmext:Url>http://10.147.40.234:443</vmext:Url><vmext:IsEnabled>true</vmext:IsEnabled><vmext:ShieldManagerIP>10.147.44.59</vmext:ShieldManagerIP><vmext:ShieldManagerUserName>admin</vmext:ShieldManagerUserName>

</vmext:VimServer>

List Available Resource Pools on a vCenter Server

The VimServer element returned in response to a GET request to a vimServer URL contains a rel="down" link whose href value is a URL that returns a list of available resource pools hosted on that server. A pool is considered available if it is not in use in a vDC. A system administrator can make a GET request to that URL

to list the available pools. Example 7‐4 makes such a request using the resourcePoolList URL from Example 7‐3.

Example 7-4. List Available Resource Pools on a vCenter Server

Request:

GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/resourcePoolList

Response:

200 OKContent-Type: application/vnd.vmware.admin.resourcepoollist+xml...<vmext:ResourcePoolList xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" ...><vcloud:Link rel="up" type="application/vnd.vmware.admin.vmwvirtualcenter+xml"

href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/><vmext:ResourcePool name="Cluster-1">

<vmext:MoRef>resgroup-1159</vmext:MoRef><vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType><vmext:DataStoreRefs/>

</vmext:ResourcePool><vmext:ResourcePool name="Cluster-2">

<vmext:MoRef>resgroup-1064</vmext:MoRef>


122 VMware, Inc.

<vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType><vmext:DataStoreRefs>

<vmext:VimObjectRef><vmext:MoRef>datastore-10</vmext:MoRef><vmext:VimObjectType>DATASTORE</vmext:VimObjectType>

</vmext:VimObjectRef><vmext:VimObjectRef>

<vmext:MoRef>datastore-11</vmext:MoRef><vmext:VimObjectType>DATASTORE</vmext:VimObjectType>



</vmext:VimObjectRef></vmext:DataStoreRefs>

</vmext:ResourcePool></vmext:ResourcePoolList>

Modify vCenter Server Settings

A system administrator can change the values of name, Description, and IsEnabled for a vCenter server by making a PUT request to the server’s edit URL. A system administrator must also modify the values of

Username, Password, and URL when any of those are changed on the server host. You cannot change those

values for the vCenter server by modifying its VimServer element, but you must update the element if you

make these changes to the server.

Example 7‐5 disables the vCenter server shown in Example 7‐3 and also changes its Description.

Example 7-5. Modify vCenter Server Settings

Request:

PUT http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100Content-Type: application/vnd.vmware.admin.vmwvirtualcenter+xml...<vmext:VimServer xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="VC-02" type="application/vnd.vmware.admin.vmwvirtualcenter+xml">

<vcloud:Description>Temporarily disabled for maintenance</vcloud:Description><vmext:Username>administrator</vmext:Username><vmext:Url>http://10.147.40.234:443</vmext:Url><vmext:IsEnabled>false</vmext:IsEnabled>

</vmext:VimServer>

Response:

202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Updating VirtualCenter (100)" ...>

...</Task>

Register a vCenter Server and vShield Manager

A system administrator can register a vCenter server and a companion vShield manager server for use with a

vCloud by making a POST request to the vCloud’s action/registervimserver URL and supplying a RegisterVimServerParams request body, as shown in Example 7‐6.

VMware, Inc. 123


Example 7-6. Register a vCenter Server and vShield Manager

Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/action/registervimserverContent-Type: application/vnd.vmware.admin.registerVimServerParams+xml...<vmext:RegisterVimServerParams xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1"><vmext:VimServer name="VC-22">

<vmext:Username>Administrator</vmext:Username><vmext:Password>Pa55w0rd</vmext:Password><vmext:Url>https://10.100.121.123:443</vmext:Url><vmext:IsEnabled>false</vmext:IsEnabled>

</vmext:VimServer><vmext:ShieldManager name="VSM-VC-22">

<vmext:Username>Administrator</vmext:Username><vmext:Password>Pa55w0rd</vmext:Password><vmext:Url>https://10.100.121.66</vmext:Url>

</vmext:ShieldManager></vmext:RegisterVimServerParams>

Response:

200 OKContent-Type: application/vnd.vmware.admin.registerVimServerParams+xml...<vmext:RegisterVimServerParams xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" type="application/vnd.vmware.admin.vmwprovidervdc+xml">

<vmext:VimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC-22" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100">

<vmext:Username>Administrator</vmext:Username><vmext:Url>https://10.100.121.123:443</vmext:Url><vmext:IsEnabled>false</vmext:IsEnabled>

</vmext:VimServer><vmext:ShieldManager>

<vmext:AssociatedVimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VSM-VC-22" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/>

<vmext:Username>Administrator</vmext:Username><vmext:Url>https://10.100.121.66</vmext:Url>

</vmext:ShieldManager></vmext:RegisterVimServerParams>

Unregister a vCenter Server and vShield Manager

Unregistering a vCenter server makes it and its vShield Manager server unavailable for use in the Cloud

Director environment. A system administrator can unregister a vCenter server and vShield manager by

making a POST request to the vCenter server’s action/unregister URL. Example 7‐7 unregisters the

vCenter server referenced by http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100.

NOTE You must disable the vCenter server before you unregister it.


124 VMware, Inc.

Example 7-7. Unregister a vCenter Server and vShield Manager

Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/action/unregister

Response:

202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... >

...</Task>

Force Reconnection to a vCenter Server

If Cloud Director loses it connection to a vCenter Server, or if you change the connection settings, a system

administrator can make a POST request to the server’s action/forcevimserverreconnect link to try forcing a reconnection, as shown in Example 7‐8.

Example 7-8. Force Reconnection to a vCenter Server

Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/action/forcevimserverreconnect

Response:

204 No Content

List ESX/ESXi Hosts in a vCloudA system administrator can use the hostReferences link returned in a VMWExtension response to request a list of all ESX/ESXi hosts in the vCloud. Example 7‐9 makes such a request, using the hostReferences link returned in Example 7‐1.

Example 7-9. List ESX/ESXi Hosts in a vCloud

Request:

GET http://vcloud.example.com/api/v1.0/admin/extension/hostReferences

Response:

200 OKContent-Type: application/vnd.vmware.admin.vmwhostreferences+xml ...<vmext:VMWHostReferences xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" ... >

<vcloud:Link rel="up" type="application/vnd.vmware.admin.vmwExtension+xml" href="http://vcloud.example.com/api/v1.0/admin/extension"/>

<vmext:HostReference type="application/vnd.vmware.admin.host+xml" name="10.115.121.12" href="http://vcloud.example.com/api/v1.0/admin/extension/host/180"/>

<vmext:HostReference ... ><vmext:HostReference ... >

</vmext:VMWHostReferences>

Get Information About a Host

A system administrator can use the href attribute value of any HostReference in a VMWHostReferences element to get detailed information about a specific host, as shown in Example 7‐10.

VMware, Inc. 125


Example 7-10. Get Information About a Host

Request:

GET http://vcloud.example.com/api/v1.0/admin/extension/host/22

Response:

200 OKContent-Type: application/vnd.vmware.admin.host+xml...<vmext:Host xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="10.115.121.14" href="http://vcloud.example.com/api/v1.0/admin/extension/host/22" ... >

<vcloud:Link rel="disable"href="http://vcloud.example.com/api/v1.0/admin/extension/host/22/action/disable"/>

<vcloud:Description/><vmext:Ready>true</vmext:Ready><vmext:Available>true</vmext:Available><vmext:Enabled>true</vmext:Enabled><vmext:Busy>false</vmext:Busy><vmext:EnableHostForHostSpanning>true</vmext:EnableHostForHostSpanning><vmext:CpuType>Intel(R) Xeon(R) CPU E5310 @ 1.60GHz</vmext:CpuType><vmext:NumOfCpusPackages>2</vmext:NumOfCpusPackages><vmext:NumOfCpusLogical>8</vmext:NumOfCpusLogical><vmext:CpuTotal>1600</vmext:CpuTotal><vmext:MemUsed>0.0</vmext:MemUsed><vmext:MemTotal>8187.5546875</vmext:MemTotal><vmext:HostOsName>VMware ESXi</vmext:HostOsName><vmext:HostOsVersion>4.0.0</vmext:HostOsVersion><vmext:VimPropertyPageUrl>

vpxclient://7416E531-05B9-4C1F-854D-97EF7C546CB0::HostSystem:host-20/</vmext:VimPropertyPageUrl><vmext:VmMoRef>host-20</vmext:VmMoRef>

</vmext:Host>

Prepare a Host

When you add a host to a vSphere cluster that Cloud Director uses, you must prepare the host before a

provider vDC can use the host’s resources.

You cannot prepare a host that is in lockdown mode. After you prepare a host, you can enable lockdown mode.

A system administrator can prepare a host by making a POST request to the host’s action/prepare URL and supplying a PrepareHostParams request body that includes the username and password of a host

administrator, as shown in Example 7‐11.

Example 7-11. Prepare a Host

Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/prepareContent-Type: application/vnd.vmware.admin.prepareHostParams+xml...<vmext:PrepareHostParams xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" type="application/vnd.vmware.admin.vmwprovidervdc+xml">

<vmext:Username>Administrator</vmext:Username><vmext:Password>Pa55w0rd</vmext:Password>

</vmext:PrepareHostParams>


126 VMware, Inc.

Response:

202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Preparing Host (1)" ...>

...</Task>

Unprepare a Host

Unprepare a host to make it unavailable for use in the Cloud Director environment. A system administrator

can unprepare a host by making a POST request to the host’s action/unprepare URL. Example 7‐12

unprepares the host reference by http://vcloud.example.com/api/v1.0/admin/extension/host/1.

Example 7-12. Unprepare a Host

Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/unprepare

Response:


...</Task>

Enable or Disable a Host

You can disable a host to prevent vApps from starting up on the host. Virtual machines that are already

running on the host are not affected. To perform maintenance on a host, migrate all vApps off of the host or

stop all vApps and then disable the host.

A system administrator can enable or disable a host for use in a vCloud by making a POST request to the host’s

action/enable or action/disable URL. Example 7‐13 disables the host referenced by

http://vcloud.example.com/api/v1.0/admin/extension/host/1.

Example 7-13. Disable a Host

Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/disable

Response:

204 No Content

Repair a Host

If the Cloud Director agent on a host cannot be contacted, a system administrator can try to repair the host

POST request to the host’s action/repair URL. Example 7‐14 upgrades the host agent for the host referenced

by http://vcloud.example.com/api/v1.0/admin/extension/host/1.

VMware, Inc. 127


Example 7-14. Repair a Host

Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/repair

Response:


...</Task>

Upgrade a Host Agent

New releases of vCenter Cloud Director may include a new version of the host agent. A system administrator

can upgrade the host agent on a host to the version included in the current installation of Cloud Director by

making a POST request to the host’s action/upgrade URL. Example 7‐15 upgrades the host agent for the host

referenced by http://vcloud.example.com/api/v1.0/admin/extension/host/1.

Example 7-15. Upgrade a Host Agent

Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/upgrade

Response:

202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Upgrading Host (1)" ...>

...</Task>

Create a Provider vDCAn VMWProviderVdc is an extended representation of a ProviderVdc object. It includes elements that allow

a system administrator to specify resources such as datastores and resource pools provided by a vCenter

instance registered to the vCloud. Only a system administrator can view or modify a VMWProviderVdc. An organization administrator or other privileged user can examine all other properties of a provider vDC (see

“Examine the Contents of a Provider vDC” on page 103).

After a system administrator creates a VMWProviderVdc, it becomes visible as a member of the

ProviderVdcReferences element of a VCloud. See “Get an Administrative View of a Cloud” on page 93.

A system administrator can use the rel="add" link for providervdcs in a VMWExtension body to add a provider vDC to a vCloud. Example 7‐18 does this by making a POST request to the providervdcs link returned in Example 7‐1.

To retrieve the values you need for the DataStoreRefs and ResourcePoolRef elements in the request body,

start by listing the vCenter Servers registered to this vCloud (see “List vCenter Servers Registered to a vCloud”

on page 120), then GET one of the vCenter Server URLs listed in the response. The result is a VimServer

element, as shown in Example 7‐16.


128 VMware, Inc.

Example 7-16. VimServer Element

Request:

GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101

Response:

200 OKContent-Type: application/vnd.vmware.admin.vmwvirtualcenter+xml...<vmext:VimServer xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101" ...>

<vcloud:Link rel="down" type="application/vnd.vmware.admin.vmsObjectRefsList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/vmsList"/>

<vcloud:Link rel="down" type="application/vnd.vmware.admin.resourcePoolList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/resourcePoolList"/>

<vcloud:Link rel="add" type="application/vnd.vmware.admin.importVmAsVAppParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/importVmAsVApp"/>

<vcloud:Link rel="add" type="application/vnd.vmware.admin.importVmAsVAppTemplateParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/importVmAsVAppTemplate"/>

<vcloud:Link rel="edit" type="application/vnd.vmware.admin.vmwvirtualcenter+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/>

<vcloud:Link rel="unregister" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/action/unregister"/>

<vcloud:Link rel="reconnect" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/action/forcevimserverreconnect"/>

<vmext:Username>administrator</vmext:Username><vmext:Url>https://10.147.20.155:443</vmext:Url><vmext:IsEnabled>true</vmext:IsEnabled><vmext:ShieldManagerIP>10.147.41.67</vmext:ShieldManagerIP><vmext:ShieldManagerUserName>admin</vmext:ShieldManagerUserName>

</vmext:VimServer>

The resourcePoolList from a VimServer element (see Example 7‐17) includes the MoRef and VimObjectType values for all accessible datastores and resource pools associated with that vCenter server.

Example 7-17. Resource Pool List

Request:

GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/resourcePoolList

Response:

200 OKContent-Type: application/vnd.vmware.admin.resourcepoollist+xml...<vmext:ResourcePoolList xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" ... ><vcloud:Link rel="up" type="application/vnd.vmware.admin.vmwvirtualcenter+xml"

href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/><vmext:ResourcePool name="gasare-vc2-rp">

<vmext:MoRef>resgroup-3582</vmext:MoRef><vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType><vmext:DataStoreRefs>

<vmext:VimObjectRef><vmext:MoRef>datastore-418</vmext:MoRef><vmext:VimObjectType>DATASTORE</vmext:VimObjectType>


VMware, Inc. 129





</vmext:VimObjectRef></vmext:DataStoreRefs>

</vmext:ResourcePool></vmext:ResourcePoolList>

You can use this information to get values for the DataStoreRefs and ResourcePoolRef elements in the

VMWProviderVdc, then POST the VMWProviderVdc body to the rel="add"link for providervdcs in the VMWExtension element, as shown in Example 7‐18.

Example 7-18. Create a Provider vDC

Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/providervdcsContent-Type: application/vnd.vmware.admin.vmwprovidervdc+xml...<vmext:VMWProviderVdc xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="PvDC-VC2" type="application/vnd.vmware.admin.vmwprovidervdc+xml">

<vcloud:Description>New Provider vDC</vcloud:Description><vcloud:ComputeCapacity>

<vcloud:Cpu><vcloud:Units>MHz</vcloud:Units><vcloud:Allocation>2241</vcloud:Allocation><vcloud:Total>24675</vcloud:Total>

</vcloud:Cpu><vcloud:Memory><vcloud:Units>MB</vcloud:Units><vcloud:Allocation>1319056</vcloud:Allocation><vcloud:Total>2097152</vcloud:Total></vcloud:Memory>

</vcloud:ComputeCapacity><vcloud:StorageCapacity>

<vcloud:Units>MB</vcloud:Units><vcloud:Allocation>18944</vcloud:Allocation><vcloud:Total>2260224</vcloud:Total>

</vcloud:StorageCapacity><vmext:DataStoreRefs>

<vmext:VimObjectRef><vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml"

name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/>


</vmext:VimObjectRef></vmext:DataStoreRefs><vmext:ResourcePoolRef>

<vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/>

<vmext:MoRef>resgroup-220</vmext:MoRef><vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType>

</vmext:ResourcePoolRef><vmext:VimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2"

href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/></vmext:VMWProviderVdc>

Response:

201 CreatedContent-Type: application/vnd.vmware.admin.vmwprovidervdc+xml


130 VMware, Inc.

...<vmext:VMWProviderVdc xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" status="0"

name="PvDC-VC2" xmlns:vcloud="http://www.vmware.com/vcloud/v1" type="application/vnd.vmware.admin.vmwprovidervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2">

<vcloud:Link rel="enable" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2/action/enable"/>

<vcloud:Link rel="edit" type="application/vnd.vmware.admin.vmwprovidervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2"/>

<vcloud:Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2"/>

<vcloud:Link rel="alternate" type="application/vnd.vmware.admin.providervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/>

<vcloud:Link rel="down" type="application/vnd.vmware.admin.vdcReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2/vdcReferences"/>

<vcloud:Description>New Provider vDC</vcloud:Description><vcloud:Tasks>

<vcloud:Task ... operation="Creating Provider Virtual Datacenter PvDC-VC2(2)" ... >...

</vcloud:Task></vcloud:Tasks><vcloud:Description>PVDC_VC2</vcloud:Description><vcloud:ComputeCapacity>

<vcloud:Cpu><vcloud:Units>MHz</vcloud:Units><vcloud:Allocation>21929</vcloud:Allocation><vcloud:Total>24675</vcloud:Total><vcloud:Used>10053</vcloud:Used><vcloud:Overhead>384</vcloud:Overhead>

</vcloud:Cpu><vcloud:Memory>

<vcloud:Units>MB</vcloud:Units><vcloud:Allocation>16207</vcloud:Allocation><vcloud:Total>24475</vcloud:Total><vcloud:Used>15771</vcloud:Used><vcloud:Overhead>977</vcloud:Overhead>

</vcloud:Memory></vcloud:ComputeCapacity><vcloud:StorageCapacity>

<vcloud:Units>MB</vcloud:Units><vcloud:Allocation>1311368</vcloud:Allocation><vcloud:Total>2097152</vcloud:Total><vcloud:Used>489361</vcloud:Used><vcloud:Overhead>2436</vcloud:Overhead>

</vcloud:StorageCapacity><vcloud:AvailableNetworks>

<vcloud:Network type="application/vnd.vmware.admin.network+xml" name="External Network VC2" href="http://vcloud.example.com/api/v1.0/admin/network/7"/>

</vcloud:AvailableNetworks><vcloud:IsEnabled>false</vcloud:IsEnabled><vcloud:NetworkPoolReferences>

<vcloud:NetworkPoolReference type="application/vnd.vmware.admin.networkPool+xml" name="s-org-vdc-vc2-DirectNET" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/22"/>

<vcloud:NetworkPoolReference type="application/vnd.vmware.admin.networkPool+xml" name="Netpool_VC2_VLAN_Backed" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/2"/>

</vcloud:NetworkPoolReferences><vmext:DataStoreRefs>




VMware, Inc. 131






href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/><vmext:HostReferences>

<vmext:HostReference type="application/vnd.vmware.admin.host+xml" name="10.115.121.11" href="http:// vcloud.example.com/api/v1.0/admin/extension/host/1"/>

<vmext:HostReference type="application/vnd.vmware.admin.host+xml" name="10.115.121.9" href="http:// vcloud.example.com/api/v1.0/admin/extension/host/2"/>

</vmext:HostReferences></vmext:VMWProviderVdc>

The response echoes the request but now has a status attribute whose value is initially 0 and an href attribute whose value is the URL of the new provider vDC. It also includes some additional elements created

by the server:

Link elements for actions and related references

A Task element that tracks creation of the provider vDC. When the task completes, the value of the

provider vDC’s status attribute changes to 1.

A HostReferences element that contains references to the ESX/ESXi hosts registered to the vCenter

server backing this provider vDC.

Examine the vSphere Objects in a Provider vDC

A system administrator can retrieve a list of ProviderVdcReferences (see “List Provider vDCs in a vCloud” on page 120), then use the value of the href attribute in any ProviderVdcReference as the target of a GET request. The response is a VMWProviderVdc body similar to the one shown in the response in Example 7‐18.

Modify a Provider vDC

To modify a provider vDC, make a PUT request to its edit link, and supply a modified version of the

VMWProviderVdc element in the request body. In Example 7‐19, the client modifies the Cpu Allocation of the provider vDC created in Example 7‐18, then includes the modified element in a PUT request to the edit link in the VMWProviderVdc element.

You must include all required elements and attributes in the request, even those that you are not changing.

Example 7-19. Modify a Provider vDC

Request:

PUT http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2Content-Type: application/vnd.vmware.admin.vmwprovidervdc+xml...<vmext:VMWProviderVdc xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="PvDC-VC2" type="application/vnd.vmware.admin.vmwprovidervdc+xml">

<vcloud:ComputeCapacity><vcloud:Cpu>

<vcloud:Units>MHz</vcloud:Units><vcloud:Allocation>4096</vcloud:Allocation><vcloud:Total>24675</vcloud:Total>

</vcloud:Cpu><vcloud:Memory><vcloud:Units>MB</vcloud:Units><vcloud:Allocation>1319056</vcloud:Allocation><vcloud:Total>2097152</vcloud:Total>


132 VMware, Inc.

</vcloud:Memory></vcloud:ComputeCapacity><vcloud:StorageCapacity>

<vcloud:Units>MB</vcloud:Units><vcloud:Allocation>18944</vcloud:Allocation><vcloud:Total>2260224</vcloud:Total>

</vcloud:StorageCapacity><vmext:DataStoreRefs>








href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/></vmext:VMWProviderVdc>

Response:

200 OKContent-Type: application/vnd.vmware.admin.vmwprovidervdc+xml...<vmext:VMWProviderVdc xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="PvDC-VC2" type="application/vnd.vmware.admin.vmwprovidervdc+xml" ... >

...</vmext:VMWProviderVdc>

The response, most of which is not shown here, echoes the request.

Enable or Disable a Provider vDC

A system administrator can use the enable or disable action links in a VMWProviderVdc element to enable

or disable a provider vDC, as shown in Example 7‐20. The enablement state of the VMWProviderVdc is shown

in its IsEnabled element.

Example 7-20. Disable a Provider vDC

Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/providervdc/43/action/disable

Response:

204 No Content

Remove a Provider vDC

Before you can remove a provider vDC, you must disable it. After the provider vDC has been disabled, its

representation includes a rel="remove" link. A system administrator can make a DELETE request to that link

to remove a provider vDC from a vCloud. The response contains a Task that tracks the delete operation.

VMware, Inc. 133


Example 7-21. Remove a vDC

Request:

DELETE http://vcloud.example.com/api/v1.0/admin/extension/providervdc/43

Response:

202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Deleting Provider Virtual Datacenter (43)" ...>

...</Task>

Create an External NetworkA system administrator can use the rel="add" link for externalnets in a VMWExtension element to add an

external network to a vCloud. Example 7‐22 does this by making a POST request to the externalnets link returned in Example 7‐1. The content of the VimPortGroupRef element in the request body specifies that

vCenter portgroup that supports the new external network.

Example 7-22. Create an External Network

Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/externalnetsContent-Type: application/vnd.vmware.admin.vmwexternalnet+xml...<vmext:VMWExternalNetwork xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="ExternalNet-VC100"><vcloud:Description>Portgroup-25 on VC-100</vcloud:Description><vcloud:Configuration>

<vcloud:IpScope><vcloud:IsInherited>false</vcloud:IsInherited><vcloud:Gateway>10.147.58.253</vcloud:Gateway><vcloud:Netmask>255.255.255.0</vcloud:Netmask><vcloud:Dns1>10.147.115.1</vcloud:Dns1><vcloud:Dns2>10.147.115.2</vcloud:Dns2><vcloud:DnsSuffix>eng.vmware.com</vcloud:DnsSuffix><vcloud:IpRanges>

<vcloud:IpRange><vcloud:StartAddress>10.147.58.1</vcloud:StartAddress><vcloud:EndAddress>10.147.58.100</vcloud:EndAddress>

</vcloud:IpRange></vcloud:IpRanges>

</vcloud:IpScope><vcloud:FenceMode>isolated</vcloud:FenceMode></vcloud:Configuration><vmext:VimPortGroupRef>

<vmext:VimServerRef type="application/vnd.vmware.admin.vmwvserver+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/>

<vmext:MoRef>dvportgroup-25</vmext:MoRef><vmext:VimObjectType>NETWORK</vmext:VimObjectType>

</vmext:VimPortGroupRef></vmext:VMWExternalNetwork>

NOTE You must use the VMware vSphere API to obtain the values you need to populate the

VimPortGroupRef element.


134 VMware, Inc.

Response:

201 CreatedContent-Type: application/vnd.vmware.admin.vmwexternalnet+xml...<vmext:VMWExternalNetwork xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="ExternalNet-VC100" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/>

<vcloud:Link rel="alternate" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/27"/>

<vcloud:Link rel="edit" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/>

<vcloud:Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/>

<vcloud:Description>Portgroup-25 on VC-100</vcloud:Description><vcloud:Tasks>

<vcloud:Task status="running"... operation="Creating External Network ExternalNet-VC100(27)" href="http:// vcloud.example.com/api/v1.0/task/579"/>

</vcloud:Tasks>...

</vmext:VMWExternalNetwork>

The response echoes the request and includes Link elements for actions and related references, and a Task element that tracks creation of the external network.

Get Information About an External Network

A system administrator can use the href attribute value of any ExternalNetworkReference element to get

more information about a specific external network. Example 7‐23 retrieves information about the external

network created in Example 7‐22. The entire VMWExternalNetwork body is returned in the response, but only part of the response is shown in the example

Example 7-23. Get Information About an External Network

Request:

GET http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27

Response:

200 OKContent-Type: application/vnd.vmware.admin.vmwexternalnet+xml...<vmext:VMWExternalNetwork xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"


<vcloud:Link rel="alternate" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/27"/>

<vcloud:Link rel="edit" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/>

<vcloud:Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/>

<vcloud:Description>Portgroup-25 on VC-100</vcloud:Description><vcloud:Configuration>...</vcloud:Configuration><vmext:VimPortGroupRef>




VMware, Inc. 135


Modify an External Network

To modify an external network, make a PUT request to its edit link, and supply a modified version of the

VMWExternalNetwork element in the request body. In Example 7‐24, the client modifies the IpRange EndAddress of the external network created in Example 7‐22, then includes the modified body in a PUT

request to the edit link that was returned when the external network was created.

Example 7-24. Modify an External Network

Request:

PUT http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27Content-Type: application/vnd.vmware.admin.vmwexternalnet+xml...<vmext:VMWExternalNetwork xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"


<vcloud:Description>Description>Portgroup-25 on VC-100</vcloud:Description><vcloud:Configuration>

<vcloud:IpScope><vcloud:IsInherited>false</vcloud:IsInherited><vcloud:Gateway>10.147.58.253</vcloud:Gateway><vcloud:Netmask>255.255.255.0</vcloud:Netmask><vcloud:Dns1>10.147.115.1</vcloud:Dns1><vcloud:Dns2>10.147.115.2</vcloud:Dns2><vcloud:DnsSuffix>eng.vmware.com</vcloud:DnsSuffix><vcloud:IpRanges>

<vcloud:IpRange><vcloud:StartAddress>10.147.58.1</vcloud:StartAddress><vcloud:EndAddress>10.147.58.201</vcloud:EndAddress>

</vcloud:IpRange></vcloud:IpRanges>

</vcloud:IpScope><vcloud:FenceMode>isolated</vcloud:FenceMode></vcloud:Configuration><vmext:VimPortGroupRef>




Response:

200 OKContent-Type: application/vnd.vmware.admin.vmwexternalnet+xml...<vmext:VMWExternalNetwork xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="ExternalNet-VC100">...

</vmext:VMWExternalNetwork>

Remove an External Network

To remove an external network, a system administrator can make a DELETE request to its rel="remove" link. The response is a Task that tracks the delete operation.


136 VMware, Inc.

Example 7-25. Remove an External Network

Request:

DELETE http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27

Response:

202 AcceptedContent-Type: application/vnd.vmware.vcloud.task+xml...<Task ... operation="Deleting External Network (27)" ...>

...</Task>

Create a Network PoolA system administrator can use the rel="add" link for networkPools in a VMWExtension body to add a network pool to a vCloud. Example 7‐26 creates a network pool of the VlanPoolType by making a POST

request to the networkPools link returned in Example 7‐1. Requests to create network pools of other types

(FencePoolType and PortGroupPoolType) follow a similar pattern.

Example 7-26. Create a Network Pool

Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/networkPoolsContent-Type: application/vnd.vmware.admin.networkPool+xml...<vmext:VMWNetworkPool xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance” xsi:type="vmext:VlanPoolType" name="NewVlanPool">

<vcloud:Description>Extra pool for new Orgs</vcloud:Description> <vmext:VlanRange> <vmext:Start>100</vmext:Start> <vmext:End>120</vmext:End> </vmext:VlanRange> <vmext:VimSwitchRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvserver+xml"

href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/> <vmext:MoRef>dvs-28</vmext:MoRef> <vmext:VimObjectType>DV_SWITCH</vmext:VimObjectType> </vmext:VimSwitchRef></vmext:VMWNetworkPool>

Response:

201 CreatedContent-Type: application/vnd.vmware.admin.networkPool+xml...<vmext:VMWNetworkPool xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" xsi:type="vmext:VlanPoolType" name="NewVlanPool" type="application/vnd.vmware.admin.networkPool+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41" ... >

<vcloud:Description>Extra pool for new Orgs</vcloud:Description> <vmext:VlanRange> <vmext:Start>100</vmext:Start> <vmext:End>120</vmext:End> </vmext:VlanRange> <vmext:VimSwitchRef>

NOTE You must use the VMware vSphere API to obtain the values you need to populate the VimSwitchRef element.

VMware, Inc. 137



<vmext:MoRef>dvs-28</vmext:MoRef> <vmext:VimObjectType>DV_SWITCH</vmext:VimObjectType> </vmext:VimSwitchRef></vmext:VMWNetworkPool>

Get Information About a Network Pool

A system administrator can use the href attribute value of any NetworkPoolReference or VMWNetworkPool element to get more information about the network pool. Example 7‐27 retrieves information about the

network pool created in Example 7‐26. The entire VMWNetworkPool body is returned in the response, but only part of the response is shown in the example

Example 7-27. Get Information About a Network Pool

Request:

GET http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41

Response:

200 OK...<vmext:VMWNetworkPool xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" xsi:type="vmext:VlanPoolType" name="NewVlanPool" type="application/vnd.vmware.admin.networkPool+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41" ... >

<vcloud:Description>Extra pool for new Org Nets</vcloud:Description> ...</vmext:VMWNetworkPool>

Modify a Network Pool

To modify a network pool, make a PUT request to its edit link, and supply a modified version of the

VMWNetworkPool body. In Example 7‐28, the client modifies the VlanRange End of the network pool created

in Example 7‐26, then includes the modified body in a PUT request to the edit link that was returned when

the network pool was created.

Example 7-28. Modify a Network Pool

Request:

PUT http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41Content-Type: application/vnd.vmware.admin.networkPool+xml...<vmext:VMWNetworkPool xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" xsi:type="vmext:VlanPoolType" name="NewVlanPool">

<vcloud:Description>Extra pool for new Org Nets</vcloud:Description> <vmext:VlanRange> <vmext:Start>100</vmext:Start> <vmext:End>150</vmext:End> </vmext:VlanRange> <vmext:VimSwitchRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvserver+xml"

href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/> <vmext:MoRef>dvs-28</vmext:MoRef> <vmext:VimObjectType>DV_SWITCH</vmext:VimObjectType> </vmext:VimSwitchRef></vmext:VMWNetworkPool>


138 VMware, Inc.

Response:

200 OK...<vmext:VMWNetworkPool xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" xsi:type="vmext:VlanPoolType" name="NewVlanPool">

...<vmext:VMWNetworkPool>

The response, most of which is not shown here, echoes the request.

Remove a Network Pool

To remove a network pool, a system administrator can make a DELETE request to its href attribute value. The response contains a Task that tracks the delete operation.

Example 7-29. Remove a Network Pool

Request:

DELETE http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41

Response:

204 No Content

Import a Virtual Machine from vCenterA system administrator can import virtual machines from any vCenter registered to a vCloud. The virtual

machines can be imported to any vDC in the vCloud, and can be imported in vApp or vApp template form.

Discover the Virtual Machines in a vCenter

A GET request to the vmsList URL in a VimServer response body returns a list of virtual machines registered

to that vCenter server. Example 7‐30 retrieves the list of virtual machines from the vmsList URL shown in

Example 7‐3 on page 121.

Example 7-30. Discover the Virtual Machines in a vCenter

Request:

GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/vmsList

Response:

200 OK Content-Type: application/vnd.vmware.admin.vmsobjectrefslist+xml...<vmext:VmObjectRefsList xmlns:vmext="http://www.vmware.com/vcloud/extension/v1"

xmlns:vcloud="http://www.vmware.com/vcloud/v1" ...><vmext:VmObjectRef name="Win2K8">

<vcloud:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="vCenter-PA-001" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/>

<vcloud:MoRef>vm-642</vcloud:MoRef><vcloud:VimObjectType>VIRTUAL_MACHINE</vcloud:VimObjectType>

</vmext:VmObjectRef><vmext:VmObjectRef ...>

...</vmext:VmObjectRef>

</vmext:VmObjectRefsList>

VMware, Inc. 139


Because the list of virtual machines registered to a vCenter server can be very long, responses to a GET

.../vmslist request present the list as a series of pages. The default page size is 100 VmObjectRef elements, each

representing a single virtual machine. The default response to a GET .../vmslist request returns the first page

of the list. You can add query parameters to the request to specify a page size and a page number. The syntax

for the query specification is:

GET API-URL/admin/extension/vimServer/id/vmsList?page=p&pageSize=s

where p represents an integer page number (starting with 1) and s represents an integer page size. The request shown in Example 7‐30 could be rewritten as shown in Example 7‐31 to return the first ten entries in the

vmsList.

Example 7-31. vmsList with Page Number and Page Size Query

Request:

GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/vmsList?page=1&pageSize=10

To return the complete list of virtual machines, make additional requests that increment the value of page.

Import a Virtual Machine as a vApp

To import a virtual machine as a vApp, a system administrator can make a request to the importVmAsVApp link in the VimServer response body whose vmslist contained the VmObjectRef that represents the virtual machine. Example 7‐32 imports the virtual machine shown in Example 7‐30 from the vCenter server

represented by the VimServer element shown in Example 7‐3 on page 121. The request body is an

ImportVmAsVAppParams element whose sourceMove attribute specifies whether or not the source virtual

machine should be removed from vCenter after the import is complete. The request body also specifies the

managed object reference of the virtual machine to import, and the href of the vDC to which the import goes.

The response is an unresolved vApp body containing a task that tracks the import.

Example 7-32. Import a Virtual Machine as a vApp

Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/importVmAsVappContent-type: application/vnd.vmware.admin.importVmAsVAppParams+xml...<ImportVmAsVAppParams xmlns="http://www.vmware.com/vcloud/extension/v1" name="ImportedWin2K8"

sourceMove="false"><VmMoRef>vm-642</VmMoRef><Vdc href="http://vcloud.example.com/api/v1.0/vdc/2"/>

</ImportVmAsVAppParams>

Response:


<VApp status="0" name="ImportedWin2K8" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-102" ...>

...<Description/><Tasks>

<Task ... operation=”Busy Virtual Application Win2K8” ...>...

</Task></Tasks>

</VApp>


140 VMware, Inc.

Import a Virtual Machine as a vApp Template

The workflow to import a virtual machine as a vApp template is similar. As shown in Example 7‐33, the

request URL is the importVmAsVAppTemplate link in the VimServer response body. The request body is an ImportVmAsVAppTemplateParams element that can contain an optional reference to a catalog in which the

template will be entered after the import is complete. The response is an unresolved vAppTemplate body containing a task that tracks the import.

Example 7-33. Import a Virtual Machine as a vApp Template

Request:

POST http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/importVmAsVappTemplateContent-type: application/vnd.vmware.admin.importVmAsVAppTemplateParams+xml...<ImportVmAsVAppTemplateParams xmlns="http://www.vmware.com/vcloud/extension/v1"

name="ImportedWin2K8-Template" sourceMove="false"><VmMoRef>vm-642</VmMoRef><Vdc href="http://vcloud.example.com/api/v1.0/vdc/2"/><Catalog href="http://vcloud.example.com/api/v1.0/catalog/32"/>

</ImportVmAsVAppTemplateParams>

Response:

201 CreatedContent-Type: application/vnd.vmware.vcloud.vAppTemplate+xml...<VAppTemplate status="0" name="ImportedWin2K8-Template"

type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-64" ...>

...<Description/><Tasks>

<Task ... operation=”Busy Virtual Application Template Win2K8” ...>...

</Task></Tasks>

</VApp>

VMware, Inc. 141

8

The vCloud API represents objects in a vCloud as XML documents in which object properties are encoded as

elements and attributes with typed values and an explicit object hierarchy defined by an XML schema. This

chapter provides reference information about how the vCloud API uses XML to represent vCloud objects.


“About Object Representations” on page 141

“Common Datatypes” on page 142

“Common Attributes” on page 143

“Common Elements” on page 146

“API Versioning” on page 147

“Extensibility” on page 148

About Object RepresentationsClient programs of RESTful Web services must be able to request object representations from the server, parse

the server’s responses to extract the information they contain, and compose requests that, in many cases, are

based on the information extracted from a response. Developers of such clients must understand the structure

of each representation that might be part of a request or response, as well as any requirements that the network

protocol (HTTP) places on client‐server interaction. In this guide, reference information on each object

representation includes the XML schema of the element that represents the object, the object type (encoded as

the MIME content type of the request or response), and a prototype of the object reference (a URL).

Schema

Each vCloud API object is defined in an XML schema document. Some objects are defined in their own schema

documents. Others are defined in the context of the larger schema in which they are used. Still others are

defined in a common schema document, from which other schemas inherit. This guide presents reference

information about XML schemas in tabular form, as shown in Table 8‐1.

XML Representations in the vCloud API 8

Table 8-1. Schema Reference Table Columns

Name Min Max Type Description

Name of an element or attribute contained. Element names begin with an uppercase character. Attribute names begin with a lowercase character.

Minimum number of this attribute or element required by the schema.

Maximum number of this attribute or element allowed by the schema. A value of n means that the maximum number is unlimited.

Type of the attribute or element, either a primitive XML datatype or a complex type defined by the vCloud API.

Description of the attribute or element


142 VMware, Inc.

Schema Validation

This release of Cloud Director uses a validating XML parser that requires elements in XML documents to agree

in both order and number with the schema. Required elements must appear in request bodies. All elements

that appear in request bodies must appear in the order established by the schema, and with content that

conforms to the type constraint specified in the schema. Default values, where defined, are supplied for

elements that are empty.

If a request contains elements from multiple XML namespaces, namespace identifiers must be supplied in

request bodies and prepended to element names. See “XML Namespace Identifiers” on page 145.

Content Type

All requests that have a body must include an HTTP Content‐Type header that specifies the content type of

the body. Content types have been defined for any element that can be used as a request body, and are shown

along with the schema and other reference information for the element.

Object Reference Prototype

Every object in a vCloud is uniquely identified by a URL. This URL is constructed by the server and returned

in the value of the href attribute of the XML element that represents the object. It also appears in various Link and ReferenceType elements that provide references to the object. This URL serves as a unique identifier that

persists for the life of the object and is never re‐used. When a client makes an HTTP GET request to an object

href, the server returns the current XML representation of that object.

Although URLs have a well‐known syntax and a well‐understood interpretation, a client should treat each

href as an opaque string. The rules that govern construction of href strings by the server are not guaranteed to remain in effect in future releases. In this release, they yield predictable content that conforms to one of two

prototypes:

Objects such as organizations, vDCs, networks, and catalogs have href values of the form API‐URL/object‐type/id

Objects such as vApp templates, vApps, and Vms have href values of the form API‐URL/xxxxxx/yyy‐id

For each prototype, API‐URL has the form http://vcloud.example.com/api/v1.0, and id is an integer. An object href prototype is included in the reference information for each object type that has an href attribute.

Common DatatypesThe vCloud API uses a number of primitive XML datatypes, as defined in W3C Recommendation 28

(http://www.w3.org/TR/xmlschema‐2/). It also defines a number of complex types, of which vCloud API

elements are instances.

Primitive XML Datatypes

Attributes and some element content are represented by primitive XML datatypes, which are shown in

Table 8‐2.

NOTE In the reference material, elements that are simply containers are listed by name, along with an

explanation of the purpose of the container, but do not include a schema reference.

Table 8-2. Primitive XML Data Types Used by the vCloud API

Value Description

xs:boolean A logical value, including true, false, 0, and 1.

xs:date Date values.

xs:dateTime Date/time values (timestamps).

xs:double Numeric value that corresponds to the IEEE double‐precision 64‐bit floating point type defined in IEEE 754‐1985.

http://www.w3.org/TR/xmlschema-2

VMware, Inc. 143

Chapter 8 XML Representations in the vCloud API

Complex Types

XML elements defined by the vCloud API are instances of complex types. For most elements, the complex type

name is the element name concatenated with the string Type (for example, the Org element is an instance of

OrgType, the vDC element is an instance of VdcType, and so on). In most of these cases, the schema

representation of the element provides an adequate reference for the underlying complex type.

There are also a few generic types of which many different kinds of element can be an instance. Because these

types are not associated with a particular kind of element, we provide schema information for them here.

EntityType

This is the base complex type for elements such as Org, vDC, and vApp.

IpAddressType

The IpAddressType imposes a pattern on the primitive xs:string type. The pattern defines an IPv4 address:

<xs:pattern value = "((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])"/>

Attributes of this type are invalid unless they conform to the pattern

ReferenceType

Many container elements are populated with references to contained objects. Each reference consists of a

hyperlink, an optional media type, and a name.

Common AttributesElements such as Org, Catalog, and vDC have a number of common attributes. With the exception of name, none of these attributes are required in request bodies, and are ignored if included. All of them are included

in response bodies.

xs:long Numeric value in the range ‐9223372036854775808 to 9223372036854775807.

xs:int Numeric value in the range ‐2147483648 to 2147483647.

xs:string Any character data.

Table 8-2. Primitive XML Data Types Used by the vCloud API (Continued)

Value Description

Schema


name 1 1 xs:string Name of the object

Description 0 1 xs:string Optional description of the object

Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object. Successfully completed tasks are not listed.

Schema


href 1 1 xs:anyURI Hyperlink to the referenced object

type 0 1 xs:string Object type, expressed as the media type of the XML representing of the object

name 0 1 xs:string Name of the referenced object.


144 VMware, Inc.

name

Every object requires a name attribute whose string value provides the display name for the object. The value

of name must be unique within a given scope, as shown in Table 8‐3.

href

Every object has unique reference encoded in the href attribute of its XML representation. See “Object

Reference Prototype” on page 142.

type

Every object allows a type attribute in its XML representation. The value of this attribute is the object type

expressed as a string, which clients should interpret as the media type (HTTP Content‐Type) of the

representation. This string is case‐insensitive in requests, and can be returned in either mixed case or lowercase

characters in responses. For more information, see “Content Type” on page 142.

status

Objects such as vAppTemplate, vApp, and Vm, that extend the ResourceEntity type have a status attribute whose value indicates the state of the object, as shown in Table 8‐4, where YES indicates that a status value is

allowed for the object listed in the column header. Status for an object, such as a vAppTemplate or vApp, whose

Children (Vm objects) each have a status of their own, is computed from the status of the Children.

Table 8-3. Requirements for Unique Object Names

Object Type Name Scope

ProviderVdc vCloud

Org, AdminOrg vCloud

Vdc Containing organization

Catalog Containing organization

CatalogItem Containing catalog

vAppTemplate Not constrained

vApp Containing organization

Vm Containing vApp

Media Not constrained

Network Container (Org, vApp, or vCloud)

NOTE The deployment status of an object is indicated by the value of its deployed attribute.

Table 8-4. vAppTemplate, vApp, and Vm status Attribute Values

Value Description vAppTemplate vApp Vm

‐1 The object could not be created. YES YES YES

0 The object is unresolved. YES YES YES

1 The object is resolved. YES YES YES

2 The object is deployed. No No No

3 The object is suspended. No YES † YES

4 The object is powered on. No YES † YES

5 The object is waiting for user input. No YES † YES

6 The object is in an unknown state. YES YES YES

7 The object is in an unrecognized state. YES YES YES

VMware, Inc. 145


XML Namespace Identifiers

Elements used as request or response bodies contain a set of attributes that enable XML validation. The body

of a PUT or POST request must contain all XML namespace identifiers required to validate the XML it

contains. A response body typically includes all the XML namespace identifiers that the server used to validate

it, in addition to other attributes that specify the schema locations searched during validation. Table 8‐5

summarizes these attributes and shows the namespace identifiers and prefixes used in the examples in this

guide.

XML namespace identifiers are omitted from most of the example responses (see “About the Examples” on

page 19). Example 8‐1 shows how they appear in a typical response body.

Example 8-1. Response Body Showing XML Namespace Identifiers

<VApp xmlns="http://www.vmware.com/vcloud/v1" status="8" name="Linux FTP server" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1 http://vcloud.example.com/api/v1.0/schema/master.xsd">

...</vApp>

8 The object is powered off. YES YES † YES

9 The object is in an inconsistent state. No YES YES

10 Children do not all have the same status. YES YES No

11 Upload initiated, OVF descriptor pending YES No No

12 Upload initiated, copying contents YES No No

13 Upload initiated, disk contents pending YES No No

14 Upload has been quarantined YES No No

15 Upload quarantine period has expired YES No No

† Indicates that all Children have this status

Table 8-4. vAppTemplate, vApp, and Vm status Attribute Values (Continued)

Value Description vAppTemplate vApp Vm

Table 8-5. XML Namespace Identifiers

Name Value Requirement

xmlns http://www.vmware.com/vcloud/v1.0 Required in all request bodies.

xmlns:vmext http://www.vmware.com/vcloud/extension/v1 Required in request bodies that include elements from the vSphere Platform Extensions

xmlns:ovf http://schemas.dmtf.org/ovf/envelope/1 Required in request bodies that include elements prefixed with ovf:

xmlns:rasd http://schemas.dmtf.org/wbem/wscim/1/cim‐schema/2/CIM_ResourceAllocationSettingData

Required in request bodies that include elements prefixed with rasd:

xmlns:vssd http://schemas.dmtf.org/wbem/wscim/1/cim‐schema/2/CIM_VirtualSystemSettingData

Not required in request bodies.

xsi:schemaLocation An installation‐dependent schema location search path. For more information, see http://www.w3.org/TR/xmlschema‐0/#schemaLocation

Not required in request bodies.

xmlns:xsi http://www.w3.org/2001/XMLSchema‐instance Not required in request bodies.


146 VMware, Inc.

XML Namespace Prefixes in Request and Response Bodies

When a request or response includes elements from multiple XML namespaces, each element name is prefixed

with a namespace identifier. Unless all elements in a request or response originate in the same XML

namespace, these prefixes are required in request bodies, and are always included in response bodies.

Example 5‐16 on page 78 and Example 7‐22 on page 133 show how namespace prefixes appear in element

names.

Common ElementsThe vCloud API defines a number of elements that can be contained by the representations of many kinds of

objects.

Description

The Description element contains a string that describes the object. This element is always optional.

Error

Error elements are used to transmit read‐only error information in a response.

Content-Type application/vnd.vmware.vcloud.error+xml

Table 8‐6 lists the minor error code values defined in this release of the vCloud API.

Schema


message 1 1 xs:string Message describing the error

majorErrorCode 1 1 xs:int Matches the HTTP status code. See “Status Codes” on page 18.

minorErrorCode 1 1 xs:string Error code specific to the failed operation

vendorSpecificErrorCode 0 1 xs:string Empty in this release

stackTrace 0 1 xs:string Stack trace of the error, if available. This attribute is returned only to a system administrator.

Table 8-6. Minor Error Codes

Error Code Description of Error

ACCESS_TO_RESOURCE_IS_FORBIDDEN The request was made by a user who had insufficient rights to the object or operation.

BAD_REQUEST The request could not be validated or contained invalid XML.

CONFLICT A conflict was detected between sections of an OVF descriptor.

EULA_NOT_ACCEPTED An attempt to instantiate a vAppTemplate or use a vAppTemplate or a Vm in a composition did not include an AllEULAsAccepted element with a value of true.

INTERNAL_SERVER_ERROR Returned for any failure that cannot be matched to another minor error code.

INVALID_REFERENCE One or more references (href attribute values) supplied in the request could not be resolved to an object.

METHOD_NOT_ALLOWED The HTTP method (GET, PUT, POST, DELETE) is not allowed for the request.

RESOURCE_NOT_FOUND One or more references (href attribute values) supplied in the request could not be resolved to an object, or the Content‐type of the request was incorrect.

VMware, Inc. 147


Link

A Link element defines a hyperlink with a relationship, URI, and an optional name and media type. For more

information about how Link elements are used and a list of the values allowed for the rel attribute, see “Links and Link Relations” on page 15.

This element is read‐only.

API VersioningvCloud API schema version information appears in the values of the xsi:schemaLocation and xmlns attributes in a response document. For example, a response body that used schema version 1.0 would include

the following attributes:

xsi:schemaLocation="http://vcloud.example.com/api/v1.0/schema/master.xsd" xmlns="http://www.vmware.com/vcloud/v1"

To discover the schema versions supported by a server, a client can make an unauthenticated GET request to

a well‐known URL on the server, as shown in Example 8‐2. The response to this kind of request is a

SupportedVersions document, from which the client can derive information about the media types and

schema locations used by the version of the API that the server supports. The response contains a

MediaTypeMapping element for each media type defined by the API. (The example shows only a few of these

elements.) The response also includes a LoginUrl element, which contains a URL that a client can use to obtain

an authentication token. For more information about using the LoginUrl, see “Authentication” on page 18.

Example 8-2. API Version Request

Request:

GET http://vcloud.example.com/api/versions

Response:

200 OKContent-Type: text/xml...<SupportedVersions ...>

<VersionInfo><Version>1</Version><LoginUrl>http://vcloud.example.com/api/v1/login</LoginUrl><MediaTypeMapping>

<MediaType>application/vnd.vmware.vcloud.org+xml</MediaType><ComplexTypeName>CatalogType</ComplexTypeName><SchemaLocation>http://vcloud.example.com/api/v1.0/schema/master.xsd</SchemaLocation>

</MediaTypeMapping><MediaTypeMapping>

UNKNOWN The request raised an exception that did not match any HTTP status code.

UNSUPPORTED_MEDIA_TYPE The wrong content type was specified for the request.

Table 8-6. Minor Error Codes (Continued)

Error Code Description of Error

Schema


rel 1 1 RelationType Relation of the link to the referenced object

href 1 1 xs:anyURI Hyperlink to the referenced object

type 0 1 xs:string Media type of the referenced object. Links to actions do not have a media type.

name 0 1 xs:string Name of the referenced object. Links to Tasks and actions do not have names.


148 VMware, Inc.

<MediaType>application/vnd.vmware.vcloud.vdc+xml</MediaType><ComplexTypeName>CatalogItemType</ComplexTypeName><SchemaLocation>http://vcloud.example.com/api/v1.0/schema/master.xsd</SchemaLocation>

</MediaTypeMapping><MediaTypeMapping>

...</MediaTypeMapping>

</VersionInfo></SupportedVersions>

SupportedVersions

A SupportedVersions element is a container for VersionInfo elements.

VersionInfo

A VersionInfo element defines the login URL and media types supported by a version of the vCloud API.


MediaTypeMapping

A MediaTypeMapping element defines the name, MIME content type, and schema location of a complex type

supported by this version of the vCloud API.


ExtensibilityThe vCloud API is designed to be extensible. All complex types defined by the API extend a single abstract

complex type. This complex type and all types based on it can include zero or more instances of an extension

element that can contain an arbitrary number of elements and attributes.

VCloudExtensibleType is an abstract type that all complex types defined in the vCloud API namespace

(http://www.vmware.com/vcloud/v1) extend. This type allows custom attributes to be added to any type and

supports definition of custom elements within the VCloudExtension element.

The VCloudExtension element has an attribute named required that specifies how clients and servers proceed when they see unknown extension. The required attribute is optional but if omitted is assumed to

be present with a value of true. That is to say, all VCloudExtension elements are assumed to require a server

that understands them.

Schema


Version 1 1 xs:string Version number

LoginUrl 1 1 xs:string URL for logging in to this version

MediaTypeMapping 0 n MediaTypeMappingType Media type of the referenced object. Links to actions do not have a media type.

Schema


MediaType 1 1 xs:string MIME content type of this complex type

ComplexTypeName 1 1 xs:string Name of this complex type

SchemaLocation 1 1 xs:anyURI URL for the XML schema definition document that defines this complex type

VMware, Inc. 149


This extensibility mechanism, which is not used in this release of the vCloud API, allows new servers to extend

the XML representations native to this release of the vCloud API without requiring existing clients to

understand those extensions.

VCloudExtension

A client should be prepared to encounter a VCloudExtension element in any response. If the element declares

required=”true” and client does not know how to interpret the contents of the element, the client can ignore

it, but it must include the VCloudExtension in any request to modify the element that contains it. A server

must return a failure when a request includes a VCloudExtension element that declares required=”true” but the server does not understand the extension.

Schema


required 0 1 xs:boolean True if this extension must be understood by the server

any attribute name 0 n xs:any An arbitrary number of attributes of any type

any element name 0 n xs:any An arbitrary number of elements of any type


150 VMware, Inc.

VMware, Inc. 151

9

This chapter provides reference information about the XML elements that represent the object model defined

for general use in this release of the vCloud API. Elements documented in this chapter are typically readable

by all users, and can be modified by users with appropriate rights. For more information about how the

vCloud API uses XML to represent objects, and how this reference material is organized, see “XML

Representations in the vCloud API” on page 141.

This chapter provides reference material on the following elements and the elements they contain:

“OrgList” on page 151

“Org” on page 151

“Vdc” on page 152

“OrgNetwork” on page 154

“Catalog” on page 160

“Media” on page 161

“VAppTemplate” on page 161

“VApp” on page 162

“Vm” on page 163

“Section” on page 163

“ScreenTicket” on page 168

“TasksList” on page 168

OrgListAn OrgList element is a container for references to organizations. It is returned in the response to a successful

login or a GET API‐URL/org request, and contains a reference to each organization to which the logged‐in user

has access.


Content-Type application/vnd.vmware.vcloud.orgList+xml

Object href prototype API‐URL/org

OrgThe Org element represents the user view of a vCloud organization object, which is a container and unit of

administration for resources and users.

Content-Type application/vnd.vmware.vcloud.org+xml

User API Reference 9


152 VMware, Inc.

Object href prototype API‐URL/org/id

VdcA vDC is a deployment environment for vApps. A Vdc element provides a user view of a vDC.

Content-Type application/vnd.vmware.vcloud.vdc+xml

Object href prototype API‐URL/vdc/id

Schema


name 1 1 xs:string Common object name attribute

any attribute name 0 n any Includes type, href, XML namespace identifiers

Link 0 n LinkType Links to actions and contained objects

Description 0 1 xs:string Optional description

Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object.

FullName 1 1 xs:string Full name of the organization

Schema




status 0 1 xs:int The creation status of the vDC:

-1 creation failed

0 not ready

1 ready

2 unknown

3 unrecognized status



AllocationModel 1 1 AllocationModelType Defines how resources are allocated by the vDC. The value of this element is set by the administrator who created the vDC. It is read‐only to users.

StorageCapacity 1 1 CapacityWithUsageType Defines the storage capacity available in the vDC

ComputeCapacity 1 1 ComputeCapacityType Defines the compute capacity available in the vDC

ResourceEntities 0 1 ResourceEntitiesType Read‐only container for ResourceEntity elements

AvailableNetworks 0 1 AvailableNetworksType Read‐only container for OrgNetwork elements that represent organization networks contained by the vDC

NicQuota 1 1 xs:int Maximum number of virtual NICs allowed in this vDC. Defaults to 0, which specifies an unlimited number.

NetworkQuota 1 1 xs:int Maximum number of OrgNetwork objects that can be deployed in this vDC. Defaults to 0, which specifies an unlimited number.

VMware, Inc. 153

Chapter 9 User API Reference

StorageCapacity

The StorageCapacity element reports storage resource consumption in a vDC.

ComputeCapacity

The ComputeCapacity element reports CPU and memory resource consumption in a vDC.

Cpu

The Cpu element reports CPU resource consumption in a vDC.

Memory

The Memory element reports memory resource consumption in a vDC.

AvailableNetworks

The AvailableNetworks element is a read‐only container for OrgNetwork elements.

Network

Each Network element contains a reference to an OrgNetwork object in the same organization as this vDC.

VmQuota 0 1 xs:int Maximum number of virtual machines that can be deployed in this vDC. Defaults to 0, which specifies an unlimited number.

IsEnabled 0 1 xs:boolean True if this vDC is enabled

Schema (Continued)


Schema


Used 0 1 xs:long Percentage of the allocation in use. This value is read‐only.

Overhead 0 1 xs:long Number of Units allocated to vShield Manager virtual machines provisioned from this vDC. This value is read‐only.

Schema


Cpu 1 1 CapacityWithUsageType Reports CPU resource consumption in a vDC

Memory 1 1 CapacityWithUsageType Reports memory resource consumption in a vDC

Schema




Schema





154 VMware, Inc.

ResourceEntities

The ResourceEntities element is a read‐only container for ResourceEntity elements.

ResourceEntity

The ResourceEntity element is a read‐only reference to a vAppTemplate or Media object contained by a vDC.

Files

The Files element is a container for File elements.

File

File elements are constructed by the server in response to an upload or download request.

OrgNetworkAn OrgNetwork element defines a network that has been allocated to an organization by the system

administrator.

Content-Type application/vnd.vmware.vcloud.network+xml

Object href prototype API‐URL/network/id

Schema



status 0 1 xs:int Creation status of the referenced object.


Files 0 1 FilesListType Read‐only container for File elements

Schema



size 0 1 xs:long Size of the file in bytes

bytesTransferred 0 1 xs:long If an upload or download of this file is in progress, this attribute indicates the number of bytes that have been transferred by the upload or download

checksum 0 1 xs:normalizedString Ignored in this release



Schema





VMware, Inc. 155


Configuration

The Configuration element specifies properties of a network.

FenceMode

The FenceMode element defines how this network is connected to its ParentNetwork. Table 9‐1 shows

permitted values for element content and the results they produce.

IpScope

The IpScope element defines the address range, gateway, netmask, and other properties of the network.


Configuration 0 1 NetworkConfigurationType Properties of the network

NetworkPool 0 1 ReferenceType A reference to the network pool from which this network is provisioned. This element, which is required when creating a natRouted or isolated network, is returned in response to a creation request but not shown in subsequent GET requests.

AllowedExternalIpAddresses 0 1 IpAddressesType List of external IP addresses that this network can use for NAT.

Schema (Continued)


Schema


IpScope 0 1 IpScopeType Defines the address range, gateway, netmask, and other properties of the network

ParentNetwork 0 1 ReferenceType Reference to a network to which this network connects

FenceMode 1 1 FenceModeValuesType Defines how this network is connected to its ParentNetwork

Features 0 1 NetworkFeaturesType Defines a set of network features.

Table 9-1. FenceMode Element Values

Value Result

bridged The two networks are bridged

isolated The two networks are not connected.

natRouted The two networks are connected as specified in their NatService elements.

Schema


IsInherited 1 1 xs:boolean True if the values in this IpScope element are inherited from the ParentNetwork of the containing Configuration

Gateway 0 1 IpAddressType IP address of the network gateway

Netmask 0 1 IpAddressType Netmask to apply to addresses on the network

Dns1 0 1 IpAddressType IP address of the primary DNS server for this network


156 VMware, Inc.

IpRange

The IpRange element defines a range of IP addresses available on a network.

Features

The Features element defines the DHCP and firewall features of a network.

DhcpService

The DhcpService element specifies the properties of the network’s DHCP service.

FirewallService

The FirewallService element defines the firewall service capabilities of a network.

Dns2 0 1 IpAddressType IP address of the secondary DNS server for this network

DnsSuffix 0 1 xs:string Suffix to be applied when resolving hostnames that are not fully‐qualified.

IpRanges 0 1 IpRangesType Read‐only container for IpRange elements.

AllocatedIpAddresses 0 1 IpAddressesType List of addresses allocated to connections to this network. Must fall within any specified IpRanges.

Schema


StartAddress 1 1 IpAddressType Lowest IP address in the range

EndAddress 1 1 IpAddressType Highest IP address in the range

Schema


DhcpService 0 1 DhcpServiceType Specifies the properties of the network’s DHCP service

FirewallService 0 1 FirewallServiceType Defines the firewall service capabilities of the network

NatService 0 1 NatServiceType Defines the NAT service capabilities of the network

Schema


IsEnabled 0 1 xs:boolean True if the service is enabled

DefaultLeaseTime 0 1 xs:int Default duration of a DCHP address lease

MaxLeaseTime 0 1 xs:int Maximum duration of a DCHP address lease.

IpRange 0 1 IpRangeType Range of IP addresses available to DHCP clients

Schema



FirewallRule 0 n FirewallRuleType Defines a single firewall rule

Schema (Continued)


VMware, Inc. 157


FirewallRule

The FirewallRule element defines a single firewall rule.

Policy

The Policy element of a FirewallRule specifies how packets are handled by the firewall. Table 9‐2 shows

permitted values for element content and the results they produce.

Protocols

The Protocols element specifies the protocols to which firewall rules apply.

NatService

The NatService element defines the network address translation capabilities of a network.

Schema


IsEnabled 0 1 xs:boolean True if the rule is enabled

Description 0 1 xs:string description of the rule

Policy 0 1 FirewallPolicyType Specifies how packets are handled by the firewall

Protocols 0 1 ProtocolsType Specifies the protocols to which this firewall rule applies

Port 1 1 xs:int Specifies the network port to which this firewall rule applies. A value of ‐1 matches any port.

DestinationIp 1 1 IpAddressType Specifies the destination IP address, inside the firewall, to which this firewall rule applies

Table 9-2. FirewallRule Policy Element Values

Value Result

drop Drop packets of this type

allow Allow packets of this type to pass through the firewall

Schema


Tcp 0 1 xs:boolean True if the firewall rules apply to the TCP protocol

Udp 0 1 xs:boolean True if the firewall rules apply to the UDP protocol

Schema



NatType 0 1 NatTypeType Specifies how Network Address Translation is implemented by the NAT service

Policy 0 1 NatPolicyType Specifies how packets are handled by the NAT service

NatRule 0 n NatRuleType Specifies a single NAT rule


158 VMware, Inc.

NatType

The NatType element specifies how network address translation is implemented by the NAT service. Table 9‐3

shows permitted values for element content and the results they produce.

Policy

The Policy element of a NatService element specifies how packets are handled by the NAT service. Table 9‐4


NatRule

The NatRule element specifies a single network address translation rule.

OneToOneVmRule

The OneToOneVmRule element describes a NAT rule that specifies network address translation details for a

single virtual machine. The external IP address can be specified manually or assigned automatically at

deployment time. The internal IP address is discovered by looking up the specified VmReference and NIC ID.

Table 9-3. NatType Element Values

Value Result

ipTranslation NAT service implemented by IP address translation

portForwarding NAT service implemented by network port forwarding

Table 9-4. NatService Policy Element Values

Value Result

allowTraffic Packets of this type pass through the firewall in both directions

allowTrafficIn Only inbound packets of this type pass through the firewall

Schema


Description 0 1 xs:string Optional description of the rule

OneToOneBasicRule 0 1 NatOneToOneBasicRuleType Ignored in this release

OneToOneVmRule 0 1 NatOneToOneVmRuleType Specifies network address translation details for a single virtual machine

PortForwardingRule 0 1 NatPortForwardingRuleType Maps an IP address and port in an organization network to an external IP address and port

VmRule 0 1 NatVmRuleType Maps an IP address and port in a vApp network to an external IP address and port

Schema


MappingMode 1 1 NatMappingModeType Specifies how IP address mapping is implemented by the NAT service

ExternalIP 0 1 IpAddressType If MappingMode is manual, specifies the external IP address of this Vm

VAppScopedVmId 1 1 xs:string Read‐only identifier created on import

VmNicId 1 1 xs:int Device number of the NIC on the referenced virtual machine

VMware, Inc. 159


MappingMode

The MappingMode element specifies how IP address mapping is implemented by the NAT service. Table 9‐5


PortForwardingRule

The PortForwardingRule element describes a NAT rule that maps an IP address and port in an organization

network to an external IP address and port.

VmRule

The VmRule element describes a NAT rule that maps an IP address and port in a vApp network to an external

IP address and port. The external IP address, external port, and internal port are specified in the element. The

internal IP address is discovered by looking up the specified VmReference and VmNicId.

Table 9-5. MappingMode Element Values

Value Result

manual The external IP address is specified in the ExternalIP element

automatic The external IP address is assigned automatically

Schema


ExternalIP 1 1 IpAddressType IP address to which this NAT rule maps the IP address specified in the InternalIP element

ExternalPort 1 1 xs:int Network port to which this NAT rule maps the port number specified in the InternalPort element

InternalIP 1 1 IpAddressType IP address to which this NAT rule maps the IP address specified in the ExternalIp element.

InternalPort 1 1 xs:int Network port to which this NAT rule maps the port number specified in the ExternalPort element.

Protocol 1 1 Layer4ProtocolType Specifies the network protocol to which this rule applies

Schema


ExternalIP 0 1 IpAddressType IP address to which this NAT rule maps the IP address specified in the InternalIP element.

ExternalPort 1 1 xs:int The network port to which this NAT rule maps the port number specified in the InternalPort element.

VAppScopedVmId 1 1 xs:string Read‐only identifier created on import

VmNicId 1 1 xs:int The device number of the NIC on the referenced virtual machine.

InternalPort 1 1 xs:int The network port to which this NAT rule maps the port number specified in the ExternalPort element.

Protocol 1 1 Layer4ProtocolType Specifies the network protocol to which this rule applies


160 VMware, Inc.

Protocol

The Protocol element of a VmRule element specifies the network protocol to which this rule applies. Table 9‐6


CatalogA Catalog element is a container for CatalogItems. An organization can contain zero or more catalogs. Users

with appropriate privileges can add or remove CatalogItem elements from a catalog.

Content-Type application/vnd.vmware.vcloud.catalog+xml

Object href prototype API‐URL/catalog/id

CatalogItems

The CatalogItems element is a read‐only container for individual CatalogItem elements.

CatalogItem

The CatalogItem element contains a reference to a media image or vApp template and optional related

metadata.

Content-Type application/vnd.vmware.vcloud.catalogItem+xml

Object href prototype API‐URL/catalogItem/id

Table 9-6. VmRule Protocol Element Values

Value Result

TCP The rule applies to the TCP protocol

UDP The rule applies to the UDP protocol

TCP_UDP The rule applies to the TCP and UDP protocols

Schema







CatalogItems 0 1 CatalogItemsType Read‐only container for CatalogItem elements.

IsPublished 0 1 xs:boolean Read‐only element, true if the catalog is published

Schema


Entity 1 1 ReferenceType Reference to the catalogued object

Property 0 n PropertyType Expresses a key=value relationship. (In this release, the maximum number of these elements in a CatalogItem is limited to ten).

VMware, Inc. 161


Property

Each CatalogItem can have up to ten Property elements, each of which expresses a key=value relationship.

The key is an attribute value, and the value is the content of the Property element itself. This element can be

used to hold arbitrary metadata attached to a CatalogItem. The vCloud API itself makes no use of this

information.

Example 9‐1 illustrates the use of the Property element in a CatalogItem.

Example 9-1. CatalogItem With Property Elements

<CatalogItem...<Property key="Originator">Example Corp.</Property><Property key="Project">Redwood</Property>

</CatalogItem>

MediaThe Media element represents virtual media, such as an ISO or floppy image.

Content-Type application/vnd.vmware.vcloud.media+xml

Object href prototype API‐URL/media/id

VAppTemplateA VAppTemplate is an abstract description of a vApp. It is created when you upload an OVF package to a vDC.

Content-Type application/vnd.vmware.vcloud.vAppTemplate+xml

Object href prototype API‐URL/vAppTemplate/vAppTemplate‐id

Schema


key 1 1 xs:string Key associated with the string value contained in the element. The length of the key cannot exceed 80 characters. The length of the value cannot exceed 256 characters.

Schema




status 0 1 xs:int Creation status of the object

imageType 1 1 ImageType One of:

iso Specifies ISO‐9660 media type

floppy Specifies 3.5” floppy media type

size 1 1 xs:long Size of the media file in bytes


Files 0 1 FilesListType Read‐only container for File elements

Schema


status 0 1 xs:int Creation status of the VAppTemplate.



162 VMware, Inc.

Children

The Children element is a read‐only container for the virtual machines (Vm elements) that are members of a

vApp or vAppTemplate.

VAppA VApp element represents a vApp, which is the result of instantiation of a vApp template.

Content-Type application/vnd.vmware.vcloud.vApp+xml

Object href prototype API‐URL/vApp/vapp‐id

ovfDescriptorUploaded 0 1 xs:boolean True if the OVF descriptor for the template has been uploaded to the containing vDC.





Files 0 n FilesListType Files that are part of the template

Children 0 1 VAppChildrenType Read‐only container for Vm elements representing virtual machines

Section 0 n ovf:Section_Type Any of the following ovf:Section_Type elements:


StartupSection


CustomizationSection

VAppScopedLocalId 0 1 xs:string Read‐only identifier created on import

Schema (Continued)


Schema


deployed 0 1 xs:boolean True if the vApp is deployed

status 0 1 xs:int Creation status of the vApp


ovfDescriptorUploaded 0 1 xs:boolean True if the associated OVF descriptor has been uploaded


Link 0 n LinkType Action links to vApp operations



VAppParent 0 1 ReferenceType Unsupported in this release

VMware, Inc. 163


VmA Vm represents a virtual machine, a member of a vApp’s Children container.

Content-Type application/vnd.vmware.vcloud.vApp+xml

Object href prototype API‐URL/vAppTemplate/vm‐id or API‐URL/vApp/vm‐id

SectionA VAppTemplate, VApp, and Vm can contain an arbitrary number of ovf:SectionType elements. In a vApp or Vm, some of these elements can be specified as instantiation parameters. The others are copied from the source

OVF Envelope and treated as read‐only by the vCloud API.

The following section types are allowed in a vApp or vAppTemplate:


StartupSection





StartupSection



Children 0 n VAppChildrenType Read‐only container for Vm elements representing virtual machines

Schema (Continued)


Schema


deployed 0 1 xs:boolean True if the Vm is deployed

status 0 1 xs:int Creation status of the Vm



Link 0 n LinkType Action links to operations









VAppScopedLocalId 0 1 xs:string Read‐only identifier created on import or composition


164 VMware, Inc.

The following section types are allowed in a Vm:






The LeaseSettingsSection element defines the terms of storage and deployment leases for a vApp.

Content-Type application/vnd.vmware.vcloud.leaseSettingsSection+xml

StartupSection

In an OVF package or VApp that contains multiple virtual machines, the StartupSection specifies the order in which the virtual machines (VirtualSystems in an OVF VirtualSystemCollection or the VAppChildren of a VApp) are powered on.

Content-Type application/vnd.vmware.vcloud.startupSection+xml


The CustomizationSection element of a VApp contains information about how customization is to be

applied to the virtual machines in the vApp.

Content-Type application/vnd.vmware.vcloud.customizationSection+xml

Schema


ovf:required 0 1 xs:boolean Optional indication of whether this element is required

type 0 1 xs:string Media type of this section

href 0 1 xs:anyURI URL to access this section

ovf:Info 1 1 ovf:Msg_Type

Required by the base ovf:Section_Type. It can contain xs:string information about the containing element, or can be empty

Link 0 n LinkType Configuration links

DeploymentLeaseInSeconds 0 1 xs:string Duration of the deployment lease, in seconds

StorageLeaseInSeconds 0 1 xs:string Duration of the storage lease, in seconds

DeploymentLeaseExpiration 0 1 xs:dateTime Date and time when the deployment lease expires

StorageLeaseExpiration 0 1 xs:dateTime Date and time when the storage lease expires

Schema





ovf:Info 1 1 ovf:Msg_Type Required by the base ovf:Section_Type. It can contain xs:string information about the containing element, or can be empty

VMware, Inc. 165



The NetworkConfigSection element specifies the configuration of a vApp network.

Content-Type application/vnd.vmware.vcloud.networkConfigSection+xml

NetworkConfig

The NetworkConfig element defines the configuration of a vApp network.


The NetworkConnectionSection element specifies how a Vm is connected to a vApp network. It extends the

ovf:NetworkConnection element.

Content-Type application/vnd.vmware.vcloud.networkConnectionSection+xml

CustomizeOnInstantiate 1 1 xs:boolean If true, then customization is executed for all children that include a GuestCustomizationSection. Default value is false.


Schema (Continued)


Schema







NetworkConfig 0 n VAppNetworkConfigurationType Defines the configuration of a VApp network

Schema


networkName 1 1 xs:string Name of the vApp Network

Description 0 1 xs:string Optional description of the network


IsDeployed 0 1 xs:boolean True if the network has been deployed (read‐only)

NOTE The OVF NetworkSection element and the vCloud API NetworkConnectionSection element

specify many of the same parameters for a network connection. If both are present in a Vm body, the values specified in the NetworkConnectionSection override those specified in the NetworkSection.

Schema





166 VMware, Inc.

NetworkConnection

The NetworkConnection element describes a single network connection.

IpAddressAllocationMode

The IpAddressAllocationMode element specifies how an IP address is allocated to this connection. Table 9‐7




PrimaryNetworkConnectionIndex 0 1 xs:int The value of the rasd:AddressOnParent element of the device (NIC) supporting the primary network connection to the containing virtual machine.

NetworkConnection 0 n NetworkConnectionType Describes a single network connection


Schema



network 1 1 xs:string The name of the network to which this connection connects.

NetworkConnectionIndex 1 1 xs:int The value in the rasd:AddressOnParent element of the device supporting this connection.

IpAddress 0 1 IpAddressType IP address of this connection

ExternalIpAddress 0 1 IpAddressType If the network that the NIC is connected to has NAT or port mapping, the external address is populated in this element.

IsConnected 1 1 xs:boolean If the vApp is deployed, specifies the current state of its connection. If the vApp is undeployed, specifies whether this connection should be connected at deployment time.

MACAddress 0 1 xs:string MAC address of this connection

IpAddressAllocationMode 1 1 IpAddressAllocationModeType Specifies how an IP address is allocated to this connection

Table 9-7. IpAddressAllocationMode Element Values

Value Result

NONE No IP addressing mode specified

MANUAL Static IP address assigned manually

POOL Static IP address allocated from a pool

DHCP IP address assigned by DHCP

Schema (Continued)


VMware, Inc. 167



The VirtualHardwareSection element of an ovf:VirtualSystem or Vm contains a description of the virtual hardware supported by a virtual machine.

Content-Type application/vnd.vmware.vcloud.virtualHardwareSection+xml


The OperatingSystemSection element of an ovf:VirtualSystem or Vm specifies the guest operating system installed on the virtual machine.

Content-Type application/vnd.vmware.vcloud.operatingSystemSection+xml


The GuestCustomizationSection element of a Vm contains customization parameters for the guest

operating system of the virtual machine.

Content-Type application/vnd.vmware.vcloud.guestCustomizationSection+xm

Schema







Enabled 0 1 xs:boolean If true, to enable guest customization at power on

ChangeSid 0 1 xs:boolean If true, customization will run sysprep to change the Windows SID for this virtual machine

VirtualMachineId 0 1 xs:int Unique identifier for this virtual machine (read‐only)

JoinDomainEnabled 0 1 xs:boolean If true, this virtual machine can join a Windows domain

UseOrgSettings 0 1 xs:boolean If true, this virtual machine uses the containing organization’s default values for Windows domain name, domain user name, and domain user password

DomainName 0 1 xs:string If UseOrgSettings is false, specifies the Windows domain to join. Required if JoinDomainEnabled is true.

DomainUserName 0 1 xs:string If UseOrgSettings is false, specifies the Windows domain user name. Required if JoinDomainEnabled is true.

DomainUserPassword 0 1 xs:string If UseOrgSettings is false, specifies the Windows domain user’s password. Required if JoinDomainEnabled is true.

AdminPasswordEnabled 0 1 xs:boolean True if the administrator password should be reset.

AdminPasswordAuto 0 1 xs:boolean True if the local administrator password should be automatically generated

AdminPassword 0 1 xs:string Local administrator password for this virtual machine

ResetPasswordRequired 0 1 xs:boolean If true, the local administrator must reset his password on first use

CustomizationScript 0 1 xs:string This element contains the customization script to run

ComputerName 0 1 xs:string Name of this virtual machine in DNS or Windows domain


168 VMware, Inc.

RasdItemsList

A RasdItemsList element is a read‐only container for groups of related ovf:Item elements such as hard

disks, network cards, and media devices. Vm elements typically contain several Link elements that reference

elements of this type.

Content-Type application/vnd.vmware.vcloud.rasdItemsList+xml

ScreenTicketA ScreenTicket element contains a string that represents a screen ticket (required to access a virtual

machine’s console).

Content-Type application/vnd.vmware.vcloud.screenTicket+xml

TasksListThe TasksList element is a read‐only container for Task elements that represent queued, running, or recently

completed tasks owned by a member of the organization that contains the TasksList.

Content-Type application/vnd.vmware.vcloud.tasksList+xml

Tasks

The Tasks element is a read‐only container for Task elements owned by the containing object. Tasks shown

in this element also appear in the TasksList of the organization that contains the object.

Task

Whenever the result of a request cannot be returned immediately, the server creates a Task object. Tasks owned by an object such as a vApp or vDC are contained in the Tasks element of the object’s XML

representation. Each Task in a Tasks or TasksList element contains all the information about the task. A GET

request to an individual task’s href does not return any additional information about the task.


Content-Type application/vnd.vmware.vcloud.taskt+xml

Schema


status 1 1 TaskStatusType The current status of the task. One of:

queued The task has been queued for execution.

running The task is running.

success The task has completed and returned a value indicating success.

error The task has completed and returned a value indicating an error.

operation 0 1 xs:string Description of the operation being tracked by the task

startTime 0 1 xs:dateTime Date and time when the task was started.

endTime 0 1 xs:dateTime Date and time when the task completed. Does not appear for running tasks.

expiryTime 0 1 xs:dateTime Date and time at which the task expires. By default, tasks expire 24 hours after their start time. Expired tasks cannot be queried.

href 0 1 xs:anyURI Link to the task

VMware, Inc. 169


Owner 0 1 ReferenceType A link to the object that owns the task. For copy operations, the owner is the copy that is being created. For delete operations, the owner is the deleted object, so this element is not included. For all other operations, the owner is the object to which the request was made.

Error 0 1 ErrorType Error message or related information returned by the task

Schema (Continued)



170 VMware, Inc.

VMware, Inc. 171

10

This chapter provides reference information about the request parameters defined in this release of the vCloud

API. Elements documented in this chapter provide parameters to requests that create, delete, modify, or

change the state of an object. For more information about how the vCloud API uses XML to represent objects,

and how this reference material is organized, see “XML Representations in the vCloud API” on page 141


“UploadVAppTemplateParams” on page 171

“InstantiateVAppTemplateParams” on page 172

“InstantiationParams” on page 172

“ComposeVAppParams” on page 173

“RecomposeVAppParams” on page 174

“DeployVAppParams” on page 175

“UndeployVAppParams” on page 175

“CaptureVAppParams” on page 175

“CloneMediaParams” on page 176

“CloneVAppTemplateParams” on page 176

“CloneVAppParams” on page 176

“MediaInsertOrEjectParams” on page 177

“VmPendingQuestion” on page 177

“VmQuestionAnswer” on page 177

“ControlAccessParams” on page 177

UploadVAppTemplateParamsThe UploadVAppTemplateParams element forms the body of an uploadVappTemplate request.

Content-Type application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml

Request Parameters Reference 10

Schema


name 1 1 xs:string Specifies the name given to the template

Description 0 1 xs:string Description of the template

transferFormat 0 1 xs:string Ignored in this release

manifestRequired 0 1 xs:boolean True if the upload includes a manifest file


172 VMware, Inc.

InstantiateVAppTemplateParamsThe InstantiateVAppTemplateParams element forms the body of an instantiateVappTemplate request.

Content-Type application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml

InstantiationParamsThe InstantiationParams element contains zero or more ovf:Section_Type elements that specify the

configuration of a vApp or virtual machine.

An InstantiationParams element can appear in a number of request bodies, including

InstantiateVAppTemplateParams, ComposeVAppParams, RecomposeVAppParams, and CloneVAppParams. The container of the InstantiationParams element determines what section types it can contain.

InstantiationParams contained by an Item element that specifies a Vm as its Source can contain the following section types:




Schema


name 1 1 xs:string Specifies the name of the vApp created by this instantiation

linkedClone 0 1 xs:boolean Ignored in this release

deploy 0 1 xs:boolean True if the vApp should be deployed after instantiation. Defaults to false.

powerOn 0 1 xs:boolean True if the vApp should be deployed and powered on after instantiation. Defaults to false.

Description 0 1 xs:string Optional description. Used for the Description of the vApp created by this instantiation.


Source 1 1 ReferenceType A reference to the vApp template to instantiate

IsSourceDelete 0 1 xs:boolean True if the object referenced by Source should be deleted after the copy is made

InstantiationParams 0 1 InstantiationParamsType Container for any of the following ovf:Section_Type elements:


StartupSection



AllEULAsAccepted 0 1 xs:boolean True if you accept the terms and conditions in the template’s EULA sections. Instantiation fails if false.

Schema


Section 0 n ovf:Section_Type Any permitted OVF Section type

VMware, Inc. 173

Chapter 10 Request Parameters Reference

InstantiationParams contained by any other element apply to a vApp and can contain the following

section types:


StartupSection



ComposeVAppParamsThe ComposeVAppParams element forms the body of a composeVapp request.

Content-Type application/vnd.vmware.vcloud.composeVAppParams+xml

Item

An Item element is a container for information about a vApp template, vApp, or virtual machine to be used

when composing or recomposing a vApp.

Schema


name 1 1 xs:string Specifies the name of the vApp created by this composition

Description 0 1 xs:string Optional description. Used for the Description of the composed vApp

deploy 0 1 xs:boolean True if the vApp should be deployed after composition. Defaults to false.

powerOn 0 1 xs:boolean True if the vApp should be deployed and powered on after composition. Defaults to false.

linkedClone 0 1 xs:boolean Ignored in this release.

VAppParent 0 1 ReferenceType Unsupported in this release.



StartupSection



Item 0 n CompositionItemParamsType Specifies a source vAppTemplate, vApp, or Vm to include in the composition

AllEULAsAccepted 0 1 xs:boolean True if you accept the terms and conditions in the template’s EULA sections. Composition fails if false.

Schema


sourceDelete 0 1 xs:boolean If the object referenced in Source is a Vm, this attribute specifies whether the Vm should be removed from its parent vApp or copied. Ignored if the object referenced in Source is not a Vm.

Source 1 1 ReferenceType A reference to a vAppTemplate, vApp, or Vm to include in the composition


174 VMware, Inc.

For more information, see “Compose a vApp” on page 65.

NetworkAssignment

When a vApp includes Vm elements that connect to networks with different names, you can use a

NetworkAssignment element to assign the network connection for each Vm to a specific network in the parent

vApp.

RecomposeVAppParamsThe RecomposeVAppParams element forms the body of a recomposeVapp request. This element allows an

arbitrary number of DeleteItem elements, but is otherwise identical to ComposeVAppParams.

Content-Type application/vnd.vmware.vcloud.recomposeVAppParams+xml

VAppScopedLocalId 0 1 xs:string If the object referenced in Source is a Vm, this element can be used to provide a unique identifier for this Vm in the composed vApp.

InstantiationParams 0 1 InstantiationParamsType Required if Source is a Vm, and can contain for any of the following ovf:Section_Type elements:




NetworkAssignment 0 n NetworkAssignmentType Maps logical networks in the Source to logical networks in the composed vApp

Schema (Continued)


Schema


innerNetwork 1 1 xs:string Name of the network in the Vm

containerNetwork 1 1 xs:string Name of the vApp network to which innerNetwork is mapped

Schema


name 1 1 xs:string Specifies the name of the vApp created by this composition

Description 0 1 xs:string Optional description. Used for the Description of the composed vApp

deploy 0 1 xs:boolean True if the vApp should be deployed after composition. Defaults to false.

powerOn 0 1 xs:boolean True if the vApp should be deployed and powered on after composition. Defaults to false.

linkedClone 0 1 xs:boolean Ignored in this release.


InstantiationParams 0 1 InstantiationParamsType container for any of the following ovf:Section_Type elements:


StartupSection



VMware, Inc. 175


DeployVAppParamsThe DeployVAppParams element forms the body of a deploy request.

Content-Type application/vnd.vmware.vcloud.deployVAppParams+xml

UndeployVAppParamsThe UndeployVAppParams element forms the body of an undeploy request.

Content-Type application/vnd.vmware.vcloud.undeployVAppParams+xml

CaptureVAppParamsThe CaptureVAppParams element forms the body of a captureVapp request.

Content-Type application/vnd.vmware.vcloud.captureVAppParams+xml

Item 0 n CompositionItemParamsType Specifies a source vAppTemplate, vApp, or Vm to include in the composition

DeleteItem 0 n ReferenceType Reference to a Vm to remove from the vApp

AllEULAsAccepted 0 1 xs:boolean True if you accept the terms and conditions in the template’s EULA sections. Composition fails if false.

Schema (Continued)


Schema


powerOn 0 1 xs:boolean True if the vApp should be powered on after deployment

deploymentLeaseSeconds 0 1 xs:int Duration of the deployment lease, in seconds

Schema


saveState 0 1 xs:boolean True if powered‐on children should be suspended and their state saved before undeployment. Default is false, specifying that children are powered off.

Schema


name 1 1 xs:string Specifies the name of the vAppTemplate created by this operation

Description 0 1 xs:string Optional description. Used for the Description of the vAppTemplate created by this operation.

Source 1 1 ReferenceType Reference to the vApp to capture.


176 VMware, Inc.

CloneMediaParamsThe CloneMediaParams element forms the body of a cloneMedia request.

Content-Type application/vnd.vmware.vcloud.cloneMediaParams+xml

CloneVAppTemplateParamsThe CloneVAppTemplateParams element forms the body of a cloneVAppTemplate request.

Content-Type application/vnd.vmware.vcloud.cloneVAppTemplateParams+xml

CloneVAppParamsThe CloneVAppParams element forms the body of a cloneVapp request.

Content-Type application/vnd.vmware.vcloud.cloneVAppParams+xml

Schema


name 1 1 xs:string Specifies the name of the new media image created by the clone operation

Description 0 1 xs:string Optional description. Used for the Description of the cloned Media image.

Source 1 1 ReferenceType Reference to the media image to clone (copy)


Schema


name 1 1 xs:string Specifies the name of the new vApp template created by the clone operation

Description 0 1 xs:string Optional description. Used for the Description of the cloned vApp template

Source 1 1 ReferenceType Reference to the vAppTemplate to clone (copy)


Schema


name 1 1 xs:string Specifies the name of the cloned vApp

Description 0 1 xs:string Common Description element. Used for the Description of the clone

deploy 0 1 xs:boolean True if the clone should be deployed. Defaults to false.

powerOn 0 1 xs:boolean True if the clone should be deployed and powered on. Defaults to false.

linkedClone 0 1 xs:boolean Ignored in this release




StartupSection



VMware, Inc. 177


MediaInsertOrEjectParamsA MediaInsertOrEjectParams element forms the body of an insertMedia or ejectMedia request.

Content-Type application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml

VmPendingQuestionThe VmPendingQuestion element contains a request from a virtual machine for user input.

Content-Type application/vnd.vmware.vcloud.vmPendingQuestion+xml

VmQuestionAnswerThe VmQuestionAnswer element contains user input to a specific VmPendingQuestion request.

Content-Type application/vnd.vmware.vcloud.vmPendingAnswer+xml

ControlAccessParamsThe ControlAccessParams element appears in Catalogs and vApps. This element can be read by all users but

can be modified only by administrators and privileged users.

Content-Type application/vnd.vmware.vcloud.controlAccess+xml

Source 1 1 ReferenceType Reference to the vApp to clone (copy)


Schema (Continued)


Schema


Media 1 1 ReferenceType Reference to a media image to insert or eject

Schema


Question 1 1 xs:string The question requiring use input.

QuestionId 1 1 xs:int Question identifier

Choices 1 n VmQuestionAnswerChoiceType Allowable answers

Schema


ChoiceId 1 1 xs:int The answer to provide

QuestionId 1 1 xs:int Question identifier

Schema


IsSharedToEveryone 1 1 xs:boolean True if this object is shared with everyone in the organization. Defaults to false.

EveryoneAccessLevel 0 1 AccessLevelType If IsSharedToEveryone is true, this element must be present and determines the access level

AccessSettings 0 1 AccessSettingsType A container for AccessSetting elements. This element must be present and not empty if IsSharedToEveryone is false.


178 VMware, Inc.

AccessSettings

The AccessSettings element is a container for AccessSetting elements. This container must be present and

not empty if the value of IsSharedToEveryone in the containing ControlAccessParams element is set to

false.

AccessSetting

An AccessSetting element defines the level of access granted to the user or group referenced in the Subject element.

AccessLevel

The AccessLevel element specifies the access level allowed for the user or group specified in Subject. Table 10‐1 shows permitted values for element content and the results they produce.

Schema


Subject 1 1 ReferenceType Reference to the user or group to which the specified AccessLevel applies.

AccessLevel 1 1 AccessLevelType Specifies the access level allowed for the user or groups specified in Subject

Table 10-1. AccessLevel Element Values

Value Result

FullControl Subject has full control of this object

Change Subject can change this object

ReadOnly Subject has read access to this object

VMware, Inc. 179

11

This chapter provides reference information about the XML elements that support administrative operations

in the vCloud API. Elements documented in this chapter are generally readable by all users, but can be created

and modified only by a system administrator, organization administrator or other privileged user. Many of

the schemas shown here extend elements and complex types that are defined in the user API. For more

information about how the vCloud API uses XML to represent objects, and how this reference material is

organized, see “XML Representations in the vCloud API” on page 141.


“VCloud” on page 179

“ExternalNetwork” on page 180

“AdminOrg” on page 180

“ProviderVdc” on page 186

“User” on page 190

“Group” on page 191

“Role” on page 191

VCloudThe vCloud element is a read‐only container for references to top‐level objects in a vCloud instance.

Content-Type application/vnd.vmware.admin.vcloud+xml

Object href prototype API‐URL/admin

Administrative API Reference 11

Schema


OrganizationReferences 0 1 OrganizationReferencesType A container for references to AdminOrg objects in the vCloud

ProviderVdcReferences 0 1 ProviderVdcReferencesType A container for references to ProviderVdc objects in the vCloud

RightReferences 0 1 RightReferencesType A container for references to Right objects in the vCloud

RoleReferences 0 1 RoleReferencesType A container for references to Role objects in the vCloud

Networks 0 1 NetworksType A container for references to ExternalNetwork objects in the vCloud.


180 VMware, Inc.

OrganizationReferences

The OrganizationReferences element is a read‐only container for ReferenceType elements that reference

AdminOrg objects a vCloud. To create a new organization, see “Create an Organization” on page 95.

ProviderVdcReferences

The ProviderVdcReferences element is a read‐only container for ReferenceType elements that reference

ProviderVdc objects a vCloud. To create a ProviderVdc, see “Create a Provider vDC” on page 127.

RightReferences

The RightReferences element is a read‐only container for ReferenceType elements that reference the

predefined Right objects in a vCloud.

RoleReferences

The RoleReferences element is a read‐only container for ReferenceType elements that reference Role objects in a vCloud. To create a role, see “Create a Role” on page 114.

Networks

The Networks element is a read‐only container for ReferenceType elements that reference ExternalNetwork objects in a vCloud. To add a network to an AdminOrg, see “Add a Network to an Organization” on page 100.

ExternalNetworkA ExternalNetwork element defines a network that has been allocated to an organization by the system

administrator.

Content-Type application/vnd.vmware.vcloud.admin.network+xml

Object href prototype API‐URL/admin/network/id

AdminOrgThe AdminOrg element provides an administrative view of an organization. It includes all members of the Org element, and adds several elements that can be viewed and modified only by system administrators.

Content-Type application/vnd.vmware.admin.organization+xml

Object href prototype API‐URL/admin/organization/id

Schema






ProviderInfo 1 1 xs:string Read‐only information about the underlying vCenter network

Schema




VMware, Inc. 181

Chapter 11 Administrative API Reference

Settings

The Settings element establishes quotas and policies for the organization. It also contains elements that

specify the details of how the organization connects to LDAP and email services.



FullName 1 1 xs:string Full name of the organization

Settings 1 1 OrgSettingsType Establishes quotas and policies, specifies how the organization connects to LDAP and email services

Users 0 1 UsersListType Container for ReferenceType elements that reference users in the organization.

Groups 0 1 GroupsListType Container for ReferenceType elements that reference groups in the organization.

Catalogs 0 1 CatalogsListType Container for ReferenceType elements that reference catalogs in the organization.

Vdcs 0 1 VdcsType Container for ReferenceType elements that reference vDCs in the organization.

Networks 0 1 NetworksType Container for ReferenceType elements that reference networks in the organization.

Schema (Continued)


Schema


IsEnabled 0 1 xs:boolean True if this organization is enabled. If enabled, the organization allows login and all other operations.

CanPublishCatalogs 0 1 xs:boolean True if this organization is allowed to publish catalogs

DeployedVmQuota 0 1 xs:int Maximum number of virtual machines that can be deployed simultaneously by a member of this organization

StoredVmQuota 0 1 xs:int Maximum number of vApps or vApp templates that can be stored (in an undeployed state) by a member of this organization

OrgLeaseSettings 0 1 OrgLeaseSettingsType Defines default lease durations and related policies

OrgLdapMode 0 1 LdapModeType Defines whether this organization is connected to an LDAP service, and whether it uses the system default LDAP service or a custom LDAP service. Cannot be changed after the organization has been created.

CustomUsersOu 0 1 xs:string If OrgLdapMode is SYSTEM, specifies an LDAP attribute=value pair to use for OU (organizational unit)

OrgLdapSettings 0 1 OrgLdapSettingsType Defines the hostname and connection details for the organization’s primary LDAP service

OrgEmailSettings 0 1 OrgEmailSettingsType Defines the email settings for this organization


182 VMware, Inc.

OrgLeaseSettings

The OrgLeaseSettings element defines default lease durations and policies for the organization.

OrgLdapMode

The OrgLdapMode element defines whether this organization is connected to an LDAP service, and whether it

uses the system default LDAP service or a custom LDAP service. Table 11‐1 shows permitted values for

element content and the results they produce.

OrgLdapSettings

If OrgLdapMode is CUSTOM, the OrgLdapSettings element defines the hostname and connection details for the

organization’s LDAP service.

UseServerBootSequence 0 1 xs:boolean True if virtual machines in this organization use the server boot sequence by default

DelayAfterPowerOnSeconds 0 1 xs:int Specifies an organization default for virtual machine boot delay after power‐on

Schema


DeleteOnStorageLeaseExpiration 0 1 xs:boolean If true, storage for a vApp is deleted when the vApp’s lease expires. If false, the storage is flagged for deletion, but not deleted.

DeploymentLeaseSeconds 0 1 xs:int Default duration of a vApp deployment lease, in seconds.

StorageLeaseSeconds 0 1 xs:int Default duration of a storage lease, in seconds.

NOTE The value of OrgLdapMode cannot be changed after the organization has been created.

Table 11-1. OrgLdapMode Element Values

Value Result

NONE Organization does not use an LDAP service.

SYSTEM Organization uses the system default LDAP service.

CUSTOM Organization uses a custom LDAP service defined in OrgLdapSettings

Schema


HostName 1 1 xs:string Hostname of the LDAP server.

Port 1 1 xs:int Port at which to connect to the LDAP service

IsSsl 0 1 xs:boolean True if the LDAP service requires an SSL connection

IsSslAcceptAll 0 1 xs:boolean True if the LDAP service accepts all SSL certificates

Realm 0 1 xs:string LDAP realm to use when looking up users

SearchBase 0 1 xs:string LDAP search base

Schema (Continued)


VMware, Inc. 183


AuthenticationMechanism

The AuthenticationMechanism element defines the authentication mechanism used by the LDAP service.

Table 11‐2 shows permitted values for element content and the results they produce.

ConnectorType

The ConnectorType element defines the type of an LDAP service. Table 11‐3 shows permitted values for

element content and the results they produce.

UserName 0 1 xs:string Username to use when logging in to LDAP, specified using LDAP attribute=value pairs (for example: cn="ldap-admin", dc="example", dc="com")

Password 0 1 xs:string Password for the user identified by UserName. This value is never returned by GET. It is inspected on create and modify. On modify, the absence of this element indicates that the password should not be changed.

AuthenticationMechanism 1 1 LdapAuthenticationMechanismType

Defines the authentication mechanism used by the LDAP service

GroupSearchBase 0 1 xs:string LDAP group search base

IsGroupSearchBaseEnabled 1 1 xs:boolean True if the group search base is enabled

ConnectorType 1 1 LdapConnectorType Defines the type of the LDAP service

UserAttributes 1 1 OrgLdapUserAttributesType Defines how LDAP attributes are used when importing a user

GroupAttributes 1 1 OrgLdapGroupAttributesType Defines how LDAP attributes are used when importing a group

Table 11-2. AuthenticationMechanism Element Values

Value Result

SIMPLE LDAP connection uses simple authentication as specified in RFC 2251 and RFC 2829.

KERBEROS LDAP connection uses Kerberos authentication.

MD5DIGEST LDAP connection uses Digest‐MD5 authentication as specified in RFC 2831.

NTLM LDAP connection uses Windows NTLM authentication.

Table 11-3. ConnectorType Element Values

Value Result

ACTIVE_DIRECTORY LDAP service is provided by Windows Active Directory

OPEN_LDAP LDAP service is provided by OpenLDAP (see http://www.openldap.org).

Schema (Continued)


http://www.openldap.org


184 VMware, Inc.

UserAttributes

If OrgLdapMode is CUSTOM, the UserAttributes element defines how LDAP attributes are used when

importing a user.

GroupAttributes

If OrgLdapMode is CUSTOM, the GroupAttributes element defines how a group is imported from LDAP.

Schema


ObjectClass 1 1 xs:string LDAP objectClass of which imported users are members. For example, user or person

ObjectIdentifier 1 1 xs:string LDAP attribute to use as the unique identifier for a user. For example, objectGuid

UserName 1 1 xs:string LDAP attribute to use when looking up a user name to import. For example, userPrincipalName or samAccountName

Email 1 1 xs:string LDAP attribute to use for the user’s email address. For example mail

FullName 1 1 xs:string LDAP attribute to use for the user’s full name. For example displayName

GivenName 1 1 xs:string LDAP attribute to use for the user’s given name. For example, givenName

Surname 1 1 xs:string LDAP attribute to use for the user’s surname. For example sn

Telephone 1 1 xs:string LDAP attribute to use for the user’s telephone number. For example telephoneNumber

GroupMembershipIdentifier 1 1 xs:string LDAP attribute that identifies a user as a member of a group. For example, dn

GroupBackLink 0 1 xs:string LDAP attribute that returns the identifiers of all the groups of which the user is a member

Schema


ObjectClass 1 1 xs:string LDAP objectClass of which imported groups are members. For example, group

ObjectIdentifier 1 1 xs:string LDAP attribute to use as the unique identifier for a group. For example, objectGuid

GroupName 1 1 xs:string LDAP attribute to use for the group name. For example, cn

Membership 1 1 xs:string LDAP attribute to use when getting the members of a group. For example, member

MembershipIdentifier 1 1 xs:string LDAP attribute that identifies a group as a member of another group. For example, dn

BackLinkIdentifier 0 1 xs:string LDAP group attribute used to identify a group member

VMware, Inc. 185


OrgEmailSettings

The OrgEmailSettings element defines the email settings for an organization.

SmtpServerSettings

If IsDefaultSmtpServer (in OrgEmailSettings) is false, the SmtpServerSettings element specifies

connection details for the organization’s SMTP server.

Users

The Users element is a read‐only container for ReferenceType elements that reference users in an

organization. To add users to an organization, see “Create or Import a User” on page 110.

Groups

The Groups element is a read‐only container for ReferenceType elements that reference groups in an

organization. To add groups to an organization, see “Import a Group” on page 113.

Catalogs

The Catalogs element is a read‐only container for ReferenceType elements that reference the catalogs in an

organization. To add catalogs to an organization, see “Create a Catalog” on page 107.

Schema


IsDefaultSmtpServer 1 1 xs:boolean True if this organization uses the system default SMTP server

IsDefaultOrgEmail 1 1 xs:boolean True if this organization uses the system default email properties.

FromEmailAddress 1 1 xs:string If IsDefaultOrgEmail is false, specifies the sender’s email address that appears in email notifications.

DefaultSubjectPrefix 1 1 xs:string If IsDefaultOrgEmail is false, specifies a prefix for system email notifications.

IsAlertEmailToAllAdmins 1 1 xs:boolean True if system email notifications should be sent to all users who have the Administrator role

AlertEmailTo 0 n xs:string If IsAlertEmailToAllAdmins is false, specifies a list of users to receive system email notifications.

SmtpServerSettings 0 1 SmtpServerSettingsType If IsDefaultSmtpServer is False, this element specifies connection details for an SMTP server to use.

Schema


IsUseAuthentication 1 1 xs:boolean True if the SMTP server requires authentication

Host 1 1 xs:string Hostname of the SMTP server.

Username 1 1 xs:string Username to use when logging in to the SMTP service. (Required if IsUseAuthentication is True).

Password 0 1 xs:string Password for the user identified by Username. This value is never returned by GET. It is inspected on create and modify. On modify, the absence of this element indicates that the password should not be changed. Required if IsUseAuthentication is true.


186 VMware, Inc.

Catalog

A Catalog element is a container for CatalogItems. An Org or AdminOrg may contain zero or more Catalog elements. To create, delete, or modify a catalog, an administrator must access it using the admin URL and content type shown here.

Content-Type application/vnd.vmware.vcloud.admin.catalog+xml

Object href prototype vCloud‐URL/admin/catalog/catalog‐id

For more information about the Catalog element schema, see “Catalog” on page 160. For information about

user operations on Catalogs, see “Cataloging vApp Templates and Media Images” on page 54.

PublishCatalogParams

The PublishCatalogParams element forms the body of a publish request for a catalog.

Vdcs

The Vdcs element is a read‐only container for ReferenceType elements that reference vDCs in an

organization. To add a vDC to an organization, see “Allocate a vDC to an Organization” on page 104.

ProviderVdcA ProviderVdc element represents a provider vDC object.

Content-Type application/vnd.vmware.admin.providervdc+xml

Object href prototype API‐URL/admin/providervdc/id

Schema


IsPublished 1 1 xs:boolean Set to true to publish a catalog (make it visible to all organizations). Set to false to unpublish a catalog. This element can be changed only in a publish request. It is Read‐only in a Catalog body.

Schema




status 0 1 xs:int creation status of the ProviderVdc:

-1 Creation failed

0 Not ready

1 Ready

2 Unknown

3 Unrecognized


Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed task owned by this object

ComputeCapacity 0 1 RootComputeCapacityType Defines the compute capacity available in this provider vDC

StorageCapacity 0 1 ProviderVdcCapacityType Defines the storage capacity available in this provider vDC

AvailableNetworks 0 1 AvailableNetworksType Container for references to ExternalNetwork objects provisioned from this provider vDC.

VMware, Inc. 187


ComputeCapacity

The administrative view of a ComputeCapacity element includes two elements: IsElastic and IsHa, that an administrator can change. These elements are not visible in the user view.

Cpu

Unlike the Cpu element that appears in the ComputeCapacity of a Vdc, the Cpu element that appears in the

ComputeCapacity of a ProviderVdc is an instance of ProviderVdcCapacityType. It defines the CPU capacity that can be allocated from a vDC and optionally reports how much of that capacity is in use.

Memory

Unlike the Memory element that appears in the ComputeCapacity of a Vdc, the Memory element that appears

in the ComputeCapacity of a ProviderVdc is an instance of ProviderVdcCapacityType. It defines the memory capacity that can be allocated from a vDC and optionally reports how much of that capacity is in use.

Vdcs 0 1 VdcsType Container for Vdc objects that are provisioned from this provider vDC.

IsEnabled 0 1 xs:boolean True if this provider vDC is enabled

NetworkPoolReferences 0 1 NetworkPoolReferencesType Container for NetworkPoolReference objects that are provisioned from this provider vDC

Schema (Continued)


Schema


Cpu 1 1 ProviderVdcCapacityType Defines CPU capacity available in the provider vDC

Memory 1 1 ProviderVdcCapacityType Defines memory capacity available in the provider vDC

IsElastic 0 1 xs:boolean True if compute capacity can grow or shrink based on demand

IsHA 0 1 xs:boolean True if compute capacity is highly available.

Schema


Units 1 1 xs:string Units in which the capacity is measured. For CPU devices, this is always Megahertz, represented by the string MHz.

Allocation 0 1 xs:long Number of Units that have been allocated to consumers

Total 1 1 xs:long Maximum number of Units that can be allocated to all consumers

Used 0 1 xs:long Percentage of the allocation in use. This value is read‐only, and is always 0 if AllocationModel is AllocationVApp.

Overhead 0 1 xs:long Number of Units allocated to vShield Manager virtual machines provisioned from this vDC. This value is read‐only, and is always 0 if AllocationModel is AllocationVApp.

Schema


Units 1 1 xs:string Specifies the units in which the capacity is measured. For storage devices, this is always Megabytes, represented by the string MB.

Allocation 0 1 xs:long Number of Units that have been allocated to consumers. This value is read‐only, and is always 0 if AllocationModel is AllocationVApp.

Total 1 1 xs:long Maximum number of Units that can be allocated to all consumers. This value is read‐only, and is always 0 if AllocationModel is AllocationVApp.


188 VMware, Inc.

StorageCapacity

The administrative view of aStorageCapacity defines the amount of storage available in a ProvidervDC and

optionally reports how much of that capacity is in use.

NetworkPoolReferences

The NetworkPoolReferences element is a read‐only container for NetworkPoolReference elements.

NetworkPoolReference

A NetworkPoolReference element is a ReferenceType element that references a network pool in a provider

vDC. This element is read‐only.

VdcReferences

The VdcReferences element is a read‐only container for VdcReference elements that reference organization

vDCs supported by this provider vDC.

Content-Type application/vnd.vmware.vcloud.admin.vdcreferences+xml

AdminVdcThe AdminVdc element provides an administrative view of a vDC. It includes all members of the Vdc element,

and adds several elements that can be viewed and modified only by administrators.

Content-Type application/vnd.vmware.admin.vdc+xml

Object href prototype API‐URL/admin/vdc/id



Schema


Schema


Units 1 1 xs:string Units in which the capacity is measured. For CPU devices, this is always Megahertz, represented by the string MHz.

Allocation 0 1 xs:long Number of Units that have been allocated to consumers

Total 1 1 xs:long Total number of Units that can be allocated to all consumers


Overhead 0 1 xs:long Number of Units allocated to vShield Manager virtual machines provisioned from this provider vDC. This value is read‐only.

Schema



Link 0 n LinkType Link to containing provider vDC

VdcReference 0 n ReferenceType Reference to an organization vDCs supported by this provider vDC

VMware, Inc. 189


Schema




status 0 1 xs:int The creation status of the vDC:

-1 creation failed

0 not ready

1 ready

2 unknown

3 unrecognized status



AllocationModel 1 1 AllocationModelType Defines how resources are allocated by the vDC

StorageCapacity 1 1 StorageCapacityType Defines the storage capacity available in the vDC

ComputeCapacity 1 1 ComputeCapacityType Defines the compute capacity available in the vDC

ResourceEntities 0 1 ResourceEntitiesType Container for ResourceEntity elements

AvailableNetworks 0 1 AvailableNetworksType Container for Network elements that reference OrgNetwork objects contained by the vDC

NicQuota 1 1 xs:int Maximum number of virtual NICs allowed in this vDC. Defaults to 0, which specifies an unlimited number.

NetworkQuota 1 1 xs:int Maximum number of OrgNetwork objects that can be deployed in this vDC. Defaults to 0, which specifies an unlimited number.

VmQuota 0 1 xs:int Maximum number of virtual machines that can be deployed in this vDC. Defaults to 0, which specifies an unlimited number.

IsEnabled 0 1 xs:boolean True if this vDC is enabled

ResourceGuaranteedMemory 0 1 xs:double Percentage of allocated memory resources guaranteed to vApps deployed in this vDC. For example, if this value is 0.75, then 75% of allocated resources are guaranteed. Required when AllocationModel is AllocationVApp or AllocationPool. Value defaults to 1.0 if the element is empty.

ResourceGuaranteedCpu 0 1 xs:double Percentage of allocated CPU resources guaranteed to vApps deployed in this vDC. For example, if this value is 0.75, then 75% of allocated resources are guaranteed. Required when AllocationModel is AllocationVApp or AllocationPool. Value defaults to 1.0 if the element is empty.


190 VMware, Inc.

AllocationModel

The AllocationModel element defines how resources are allocated in a vDC. Table 11‐4 shows permitted

values for element content and the results they produce.

UserA User object defines a member of an organization or group.

Content-Type application/vnd.vmware.admin.user+xml

Object href prototype API‐URL/admin/user/id

VCpuRatingMHz 0 1 xs:long Specifies a clock frequency, in Megahertz, for each virtual CPU core provisioned from this vDC

IsThinProvision 0 1 xs:boolean True if thin provisioning has been enabled for this vDC

NetworkPoolReference 0 1 ReferenceType Reference to a network pool in the provider vDC referenced by ProviderVdcReference

ProviderVdcReference 0 1 ReferenceType Reference to the ProviderVdc from which this vDC is provisioned

Schema (Continued)


Table 11-4. AllocationModel Element Values

Value Result

AllocationVApp Resources are committed to a vDC only when vApps are created in it

AllocationPool Only a percentage of the resources you allocate are committed to the organization vDC.

ReservationPool All the resources you allocate are committed as a pool to the organization vDC. vApps in vDCs that support this allocation model can specify values for resource and limit.

Schema


name 1 1 xs:string Common object name attribute. The name of the user.



FullName 0 1 xs:string User’s full name.

EmailAddress 0 1 xs:string User’s email address

Telephone 0 1 xs:string User’s telephone number

IsEnabled 0 1 xs:boolean True if the user can log in

IM 0 1 xs:string User’s instant messaging address

NameInSource 0 1 xs:string User name as retrieved from, and in the encoding used by, LDAP

IsAlertEnabled 0 1 xs:boolean True if alerts are enabled for the user

AlertEmailPrefix 0 1 xs:string String to prepend to alert message Subject line

AlertEmail 0 1 xs:string Alert email address

isExternal 0 1 xs:boolean True if this user was imported from LDAP

IsDefaultCached 0 1 xs:boolean True if this user is cached

IsGroupRole 0 1 xs:boolean True if this user has a group role

VMware, Inc. 191


GroupA Group object defines a group.

Content-Type application/vnd.vmware.admin.group+xml

Object href prototype API‐URL/admin/group/id

RoleThe Role element contains a single RightReferences element, which is a container for RightReference elements.

Content-Type application/vnd.vmware.admin.role+xml

Object href prototype API‐URL/admin/role/id

RightReferences

The RightReferences element is a container for zero or more RightReference elements.

RightReference

The RightReference element contains a reference to a Right.

StoredVmQuota 0 1 xs:int Quota of vApps that this user can store. A value of 0 specifies an unlimited quota.

DeployedVmQuota 0 1 xs:int Quota of vApps that this user can deploy concurrently. A value of 0 specifies an unlimited quota

Role 0 1 ReferenceType A reference to the user’s role. When you are creating a User, the request body must contain exactly one Role element.

Password 0 1 xs:string The user’s password. This value is never returned by GET. It is inspected on create and modify. On modify, the absence of this element indicates that the password should not be changed.

GroupReferences 0 1 GroupsListType Container for ReferenceType elements that reference groups of which this user is a member

Schema (Continued)


Schema


name 1 1 xs:string Common object name attribute. The Group’s name.



NameInSource 0 1 xs:string Group name as retrieved from, and in the encoding used by, LDAP

UsersList 0 1 UsersListType A list of references to users in the group

Role 0 1 ReferenceType Reference to the group’s role.

Schema


Right 1 1 ReferenceType A reference to a right defined in the vCloud.


192 VMware, Inc.

Right

Right elements are predefined by Service Manager. They are read‐only to users and administrators, and can

be retrieved with a GET operation that specifies the URL in a RightReference. For more information, see

“Get an Administrative View of a Cloud” on page 93.

Content-Type application/vnd.vmware.admin.right+xml

Object href prototype API‐URL/admin/right/id

Schema


name 1 1 xs:string Name of the right

Description 0 1 xs:string Optional description of the right.

Category 1 1 xs:string Optional category name

VMware, Inc. 193

12

This chapter provides reference information about the elements defined in the vSphere Platform extensions to

this release of the vCloud API. Elements documented in this chapter can be created and modified only by a

system administrator. For more information about how the vCloud API uses XML to represent objects, and

how this reference material is organized, see “XML Representations in the vCloud API” on page 141.


“VMWExtension” on page 193

“VimServer” on page 194

“VmObjectRefsList” on page 195

“ResourcePoolList” on page 196

“ShieldManager” on page 196

“VMWProviderVdc” on page 197

“VMWNetworkPool” on page 198

“VMWExternalNetwork” on page 199

“VMWHostReferences” on page 199

“Request Parameters” on page 200

VMWExtensionThe VMWExtension element is a read‐only container for links to vCenter servers registered to Cloud Director

and vSphere objects such as ESX/ESXi hosts, resource pools and networks.

Content-Type application/vnd.vmware.admin.vmwExtension+xml

Object href prototype API‐URL/admin/extension

vSphere Platform Extensions Reference 12

Schema


href 1 1 xs:anyURI Object reference

type 0 1 xs:string Media type of the element (application/vnd.vmware.admin.vmwExtension+xml)

any attribute name 0 n any Includes XML Namespace Identifiers.

Link 0 n LinkType Links to actions and contained objects.


194 VMware, Inc.

VMWProviderVdcReferences

The VMWProviderVdcReferences element is a read‐only container for ProviderVdcReference elements.

Content-Type application/vnd.vmware.admin.vmwProviderVdcReferences+xml

Object href prototype API‐URL/admin/extension/providerVdcReferences

VMWExternalNetworkReferences

The VMWExternalNetworkReferences element is a read‐only container for ExternalNetworkReference elements.

Content-Type application/vnd.vmware.admin.vmwExternalNetworkReferences+xml

Object href prototype API‐URL/admin/extension/externalNetworkReferences

VMWNetworkPoolReferences

The VMWNetworkPoolReferences element is a read‐only container for NetworkPoolReference elements.

Content-Type application/vnd.vmware.admin.vmwNetworkPoolReferences+xml

Object href prototype API‐URL/admin/extension/networkPoolReferences

VMWVimServerReferences

The VMWVimServerReferences element is a read‐only container for VimServerReference elements.

Content-Type application/vnd.vmware.admin.vmwVimServerReferences+xml

Object href prototype API‐URL/admin/extension/vimServerReferences

VMWHostReferences

The VMWHostReferences element is a read‐only container for HostReference elements.

Content-Type application/vnd.vmware.admin.vmwHostReferences+xml

Object href prototype API‐URL/admin/extension/hostReferences

VimServerA VimServer object represents a vCenter server.

Content-Type application/vnd.vmware.admin.vmwvirtualcenter+xml

Object href prototype API‐URL/admin/extension/vimServer/id

Schema



any attribute name 0 n any Includes type, href, XML Namespace Identifiers



Username 1 1 xs:string User name of the administrator of this vCenter server

VMware, Inc. 195

Chapter 12 vSphere Platform Extensions Reference

VmObjectRefsListThe VmObjectRefsList element is a read‐only container for VmObjectRef elements.

Content-Type application/vnd.vmware.admin.vmsobjectrefslist+xml

Object href prototype API‐URL/admin/extension/vimServer/id/vmsList

VimObjectRef

The VimObjectRef element is a reference to a Virtual Infrastructure Management object.

VimObjectType

The VimObjectType element defines the type of a Virtual Infrastructure Management object. Table 12‐1 shows

permitted values for element content. These values are read‐only.

Password 0 1 xs:string Password for the user identified by Username. This value is never returned by GET. It is inspected on create and modify. On modify, the absence of this element indicates that the password should not be changed.

Url 1 1 xs:anyURI URL, including port, to use when connecting to this vCenter server with a vSphere client

IsEnabled 1 1 xs:boolean True if the server is enabled for use with Cloud Director

IsConnected 0 1 xs:boolean True if this vCenter is ready to be used by the vCloud

ShieldManagerIP 0 1 xs:anyURI IP address of the associated vShield Manager

ShieldManagerUserName 0 1 xs:string User name of vShield Manager administrator

Schema (Continued)


Schema


VimServerRef 1 1 ReferenceType Reference to the server hosting this object

MoRef 1 1 xs:string Managed object ID of this object

VimObjectType 1 1 VimObjectTypeEnum Type of this object

Table 12-1. VimObjectType Element Values

Value Object Type

RESOURCE_POOL The object is a resource pool.

DATASTORE The object is a vSphere datastore.

HOST The object is an ESX host.

VIRTUAL_MACHINE The object is a virtual machine.

VIRTUAL_APP The object is a vApp.

NETWORK The object is an external network.

DV_PORTGROUP The object is a distributed virtual portgroup

DV_SWITCH The object is a distributed virtual switch.


196 VMware, Inc.

ResourcePoolListThe ResourcePoolList element is a read‐only container for ResourcePool elements.

Content-Type application/vnd.vmware.admin.resourcepoollist+xml

Object href prototype API‐URL/admin/extension/vimServer/id/resourcePoolList

ResourcePool

The ResourcePool element includes the MoRef (managed object ID) of the pool itself and additional

DataStoreRefs for each datastore in a pool.

ShieldManagerThe ShieldManager object represents a vShield Manager server.

Content-Type application/vnd.vmware.admin.vmwvirtualcenter+xml

Object href prototype API‐URL/admin/extension/shieldmanager/id

Schema


MoRef 1 1 xs:string Managed object ID of this object

VimObjectType 1 1 VimObjectTypeEnum Type of this object

DataStoreRefs 0 1 VimObjectRefsType Read‐only container for references to datastores in this resource pool

Schema





Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or recently completed Task owned by this organization.

Username 1 1 xs:string User name of the administrator of this vShield Manager server

Password 0 1 xs:string Password for the user identified by Username. This value is never returned by GET. It is inspected on create and modify. On modify, the absence of this element indicates that the password should not be changed.

Url 1 1 xs:anyURI URL, including port, to use when connecting to this vShield Manager server with a vSphere client

AssociatedVimServer 0 1 ReferenceType Reference to the vCenter server associated with this vShield Manager server

VMware, Inc. 197


VMWProviderVdcA VMWProviderVdc object represents a provider vDC.

Content-Type application/vnd.vmware.admin.vmwprovidervdc+xml

Object href prototype API‐URL/admin/extension/providervdc/id

Schema




status 0 1 xs:int The creation status of the ProviderVdc:

‐1 – Creation failed

0 – Not ready

1 – Ready

2 – Unknown

3 – Unrecognized


Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or recently completed Task owned by this organization.

ComputeCapacity 0 1 RootComputeCapacityType Defines the compute capacity available in this provider vDC

StorageCapacity 0 1 ProviderVdcCapacityType Defines the storage capacity available in this provider vDC

AvailableNetworks 0 1 AvailableNetworksType Read‐only container for Network elements that reference external networks contained by the provider vDC

Vdcs 0 1 VdcsType Read‐only container for references to Vdc objects that are provisioned from this provider vDC.

IsEnabled 0 1 xs:boolean True if this provider vDC is enabled

NetworkPoolReferences 0 1 NetworkPoolReferencesType Container for NetworkPoolReference elements

DataStoreRefs 1 1 VimObjectRefsType Container for VimObjectRef elements of type DATASTORE

ResourcePoolRef 1 1 VimObjectRefType Reference to the resource pool backing this provider vDC (VimObjectRef element of type RESOURCE_POOL)

VimServer 1 1 ReferenceType Reference to the vCenter server hosting the datastores contained in DataStoreRefs and the resource pool contained in ResourcePoolRef

HostReferences 0 1 HostsType Read‐only container for Host objects


198 VMware, Inc.

VMWNetworkPoolThe VMWNetworkPool element represents a network pool. There are three different types of this element, all of

which have the same name, VMWNetworkPool, and are distinguished in request bodies by the value of the HTTP Content‐Type header.

FencePoolType

A VMWNetworkPool of the FencePoolType represents a network pool backed by one or more vSphere isolated

networks.

Content-Type application/vnd.vmware.admin.fencePool+xml

PortGroupPoolType

A VMWNetworkPool of the PortGroupPoolType represents a network pool backed by one or more vSphere

port groups.

Content-Type application/vnd.vmware.admin.portGroupPool+xml

VlanPoolType

A VMWNetworkPool of the VlanPoolType represents a network pool backed by one or more vSphere VLANs.

Content-Type application/vnd.vmware.admin.vlanPool+xml

Schema





FenceIdCount 1 1 xs:int Number of fence IDs in this pool

VlanId 1 1 xs:int Set to 0 for no VLAN

VimSwitchRef 1 1 VimObjectRefType Reference to the switch that supports this VLAN

UsedNetworksCount 0 1 xs:int Read‐only indication of how many networks in this pool are in use

Schema





PortGroupRefs 1 1 VimObjectRefsType References to the portgroups that support this VLAN

VimServer 1 1 ReferenceType Reference to the server hosting this object


Schema





VlanRange 1 n NumericRangeType Defines a range of VLAN IDs

VMware, Inc. 199


VMWExternalNetworkThe VMWExternalNetwork element defines an external network.

Content-Type application/vnd.vmware.vcloud.admin.network+xml

Object href prototype API‐URL/admin/extension/externalnet/id

VlanRange

The VlanpRange element defines a range of VLAN IDs.

VMWHostReferencesThe VMWHostReferences element is a read‐only container for Host elements representing the hosts in a

specific provider vDC.

Host

A Host object represents an ESX/ESXi host in a provider vDC.

Content-Type application/vnd.vmware.admin.+xml

Object href prototype API‐URL/admin/extension/host/id

VimSwitchRef 1 1 VimObjectRefType Reference to the switch that supports this VLAN


Schema (Continued)


Schema






VimPortGroupRef 1 1 VimObjectRefType Reference to the portgroup that supports this network

Schema


Start 1 1 xs:int Lowest VLAN ID in the range

End 1 1 xs:int Highest VLAN ID in the range

Schema



any attribute name 0 n any Includes type, href, XML Namespace Identifiers.


Tasks 0 1 TasksInProgressType Read‐only container for Task elements. Each element in the container represents a queued, running, or failed Task owned by this object.

Link 0 n LinkType Links to contained objects.


200 VMware, Inc.

Request ParametersThe vSphere Platform extensions defined several elements that provide parameters to requests that create,

delete, modify, or change the state of a vSphere Platform object.

PrepareHostParams

The PrepareHostParams element forms the body of a prepare or unprepare request for an ESX host.

RegisterVimServerParams

The RegisterVimServerParams element forms the body of a registervimserver request.

Ready 1 1 xs:boolean True if the host is ready

Available 1 1 xs:boolean True if the host is available

Enabled 1 1 xs:boolean True if the host is enabled for use with Cloud Director

Busy 1 1 xs:boolean True if the host is busy

EnableHostForHostSpanning 1 1 xs:boolean True if the host is enabled for host spanning. If true, the host cannot be put in standby or maintenance mode.

CpuType 0 1 xs:string CPU type of the host

NumOfCpusLogical 1 1 xs:int Number of logical CPUs

NumOfCpusPackages 1 1 xs:int Number of CPU packages

CpuTotal 1 1 xs:long Total CPU capability of this host

MemUsed 1 1 xs:double Memory reserved

MemTotal 1 1 xs:double Total memory

HostOsName 0 1 xs:string Host operating system name

HostOsVersion 0 1 xs:string Host operating system version

SystemMessages 0 1 xs:string vCenter messages for this host

VimPropertyPageUrl 0 1 xs:string URL for host property page in vSphere

VmMoRef 0 1 xs:string vSphere managed object reference for this object

Schema (Continued)


Schema


Username 1 1 xs:string User name of a host administrator

Password 1 1 xs:string Password for specified Username

Schema


VimServer 1 1 VimServerType vCenter server to register

ShieldManager 1 1 ShieldManagerType vShield Manager associated with the vCenter server to register

VMware, Inc. 201


ImportVmAsVAppParams

The ImportVmAsVAppParams element forms the body of an importVmAsVApp request.

ImportVmAsVAppTemplateParams

The ImportVmAsVAppTemplateParams element forms the body of an importVmAsVAppTemplate request.

Schema


name 1 1 xs:string Specifies the name of the vApp created by this operation

sourceMove 0 1 xs:boolean True if the imported VM should be removed from the source vCenter

deploy 0 1 xs:boolean Not supported in this release

powerOn 0 1 xs:boolean Not supported in this release




StartupSection



VmName 0 1 xs:string Virtual machine name


ComputerName 0 1 xs:string Display name of this virtual machine

VmMoRef 1 1 xs:string Managed object reference of the VM to import

Vdc 1 1 ReferenceType URL of the target vDC

Schema


name 1 1 xs:string Specifies the name of the vApp created by this operation

sourceMove 0 1 xs:boolean True if the imported VM should be removed from the source vCenter


VmMoRef 1 1 xs:string Managed object reference of the VM to import

Vdc 1 1 ReferenceType URL of the target vDC

Catalog ReferenceType Reference to a catalog in which the template will be included. If this element is omitted or empty, the template is imported into the target vDC but not references in any catalog.

VmName 0 1 xs:string Virtual machine name


ComputerName 0 1 xs:string Display name of this virtual machine


202 VMware, Inc.

VMware, Inc. 203

A

The Open Virtualization Format (OVF) is an open, portable, efficient and extensible format for packaging and

distributing virtual systems. OVF was developed by the Distributed Management Task Force (DMTF), a

not‐for‐profit association of industry members dedicated to promoting enterprise and systems management

and interoperability. For more information about the DMTF and OVF, visit http://www.dmtf.org.

The vCloud API supports Version 1 of the OVF standard. In particular, it supports uploading and

downloading vApp templates as OVF packages. In addition, vApp, Vm, and vAppTemplate elements

incorporate a number of ovf:Section_Type elements in their definitions of virtual machines (see “Section”

on page 163 for details on how these sections are used).

This appendix includes the following topics:

“About OVF” on page 203

“How the vCloud API Uses OVF” on page 204

About OVFBecause it is a widely accepted standard format, OVF provides considerable flexibility in accommodating the

needs of a diverse collection of virtualization technologies. While this flexibility entails more complexity than

a vendor‐specific format might require, it also provides many advantages.

Virtual machines and appliances are distributed as OVF packages by many vendors.

Many vendors, including VMware, offer tools that simplify creating and customizing OVF virtual

machines, support converting virtual machines on existing virtualization platforms to OVF, or both.

OVF has the power to express the complex relationships between virtual appliances in enterprise

applications. Most of the complexity can be handled by the author of the appliance rather than the user

deploying it.

OVF is extensible, allowing new policies and requirements to be inserted by ISVs and implemented by

the virtualization platforms that support them without requiring changes to other clients, other platforms,

or the vCloud API itself.

While most users do not need to interact directly with the OVF‐derived elements of the vCloud API,

administrators and advanced users should become familiar with the details of the OVF standard before

developing applications with the vCloud API. This chapter provides an overview of OVF, one that

concentrates on the aspects of the standard that are of special interest to users of the vCloud API. The complete

OVF specification document is available at

http://www.dmtf.org/standards/published_documents/DSP0243_1.0.0.pdf. An informative white paper on

OVF is available at http://www.dmtf.org/standards/published_documents/DSP2017_1.0.0.pdf.

OVF and the vCloud API A

NOTE The vCloud API supports uploading OVF 1.0 and OVF 1.1, and downloading OVF 1.0. OVF 1.1

packages are converted to OVF 1.0 for download.

http://www.dmtf.org/standards/published_documents/DSP2017_1.0.0.pdf

http://www.dmtf.org/standards/published_documents/DSP0243_1.0.0.pdf


204 VMware, Inc.

A virtual application or virtual machine is typically made up of one or more virtual disk files that contain the

operating system and applications that run on the virtual machine, and a configuration file containing

metadata that describe how the virtual machine is configured and deployed. An OVF package includes these

components, as well as optional certificate and manifest files. The package can be distributed and stored as a

collection of individual files, or as a single archive (OVA) file.

About OVF Packages

An OVF package includes four kinds of files:

An OVF descriptor, an XML file that contains metadata that describe a virtual machine or collection of

related virtual machines and the deployment environment they require. By convention, this file has the

suffix .ovf.

Virtual disk files. The descriptor lists these files and includes information about their format.

An optional certification file, which can be used to certify the authenticity of the package.

An optional manifest file, which contains a SHA‐1 digest of each of the files in the package.

About OVA Files

An OVA file collects all the files in an OVF package into a single archive. By convention, this file has the

suffix .ova. This release of the vCloud API does not support upload or download of OVA files.

How the vCloud API Uses OVFThe vCloud API uses the OVF package as a unit of distribution and storage for vApp templates. Because these

artifacts are uploaded, downloaded, and stored in OVF package form, the vCloud API supports access to and

deployment of the widest possible variety of virtual applications. The vCloud API implements an instantiation

mechanism that transforms an OVF package into a vApp by binding the package’s abstract resource

requirements to specific resources in a deployment environment defined by a vDC.

Because of its generality, the OVF includes a great deal of information, nearly all of which is reused in VApp elements. Some of this information is reused in unaltered form, with entire ovf:Section_Type elements

included in the VApp body. Other sections are transformed or extended by instantiation. While it is not

necessary for a user of the vCloud API to have a detailed knowledge of all the elements of an OVF package, a

basic understanding of a few key parts the package and how they relate to vApp templates and vApps can be

useful.

Virtual Machines

An OVF Envelope collects all of the metadata that describes a single virtual machine into a VirtualSystem element. An Envelope that contains more than one VirtualSystem collects them into a VirtualSystemCollection element. This arrangement supports packaging a group of related virtual

machines as a single object, and includes provisions for specifying global parameters such as virtual machine

startup order, network connections, and a range of resource configurations (such as processing power and

memory) to which the virtual machines can be deployed.

The vCloud API also supports this kind of packaging of multiple virtual machines. When you instantiate a

VAppTemplate, information from its VirtualSystem and VirtualSystemCollection elements is

propagated to the created VApp. VirtualSystem elements in a VirtualSystemCollection become Vm elements contained by the Children element of a VApp.

For more information about instantiation, see “Instantiate a vApp Template” on page 61. For a detailed

example of an Envelope and its sections, see “Reconfiguring vApps and Virtual Machines” on page 69. For

more information about the purpose and contents of the OVF Sections included in a vApp or Vm, see “VApp” on page 162.

VMware, Inc. 205

Appendix A OVF and the vCloud API

Virtual Disk Files

Virtual disk file information extracted from the References section of the OVF package is used to populate the Files element of the VAppTemplate. An OVF package can include exactly one References section. It lists all the files required by all the VirtualSystems defined in the package, including virtual disks and locale‐specific resource files. Virtual disk files are enumerated again in the DiskSection element of the

package, one file per Disk element. Disk elements include additional information about the capacity and

format of each disk. (Disk elements can also specify empty virtual disk, in which case they are not associated

with a virtual disk file.)

Example A‐1 shows how a virtual disk reference appears in an Envelope. (In this example, attributes and

other elements in the Envelope have been omitted for clarity.) The href value of the File element in the

References section specifies the file pathname relative to the location of the OVF descriptor file in which the

Envelope appears. (In this case, the disk file, SimpleVM-disk1.vmdk, is in the same folder as the OVF

descriptor.) The Disk element is then associated with a virtual machine, as a HostResource of a VirtualSystem, referenced by its ovf:diskId attribute value.

Example A-1. Virtual Disks in an OVF Envelope

<Envelope ......<References>

<File ovf:href="SimpleVM-disk1.vmdk" ovf:id="file1" ovf:size="68096"/></References>...<DiskSection>

<Info>Virtual disk information</Info><Disk ovf:capacity="8589934593" ovf:capacityAllocationUnits="byte * 2^20"

ovf:diskId="vmdisk1" ovf:fileRef="file1" ovf:format="http://www.vmware.com/interfaces/specifications/vmdk.html#streamOptimized"/>

</DiskSection>...<VirtualHardwareSection>

<VirtualSystem>...<Item>

...<rasd:ElementName>Hard Disk 1</rasd:ElementName><rasd:HostResource>ovf:/disk/vmdisk1</rasd:HostResource>...

</Item>...

</VirtualHardwareSection></VirtualSystem>

</Envelope>

Networks

The NetworkSection element of an OVF Envelope lists all the logical networks required by the package. Each

network is defined in this section by a name and can have an optional description. Logical network names are

used when specifying connection details for a virtual NIC.

The OVF is extensible, and the vCloud API has implemented extensions that enable a more comprehensive

specification of network features, such as firewall and NAT rules, than what is currently supported by the OVF

standard. See “NetworkConfig” on page 165.

Example A‐2 illustrates a subset of Envelope elements that specify vApp networking configuration.

The OVF NetworkSection element specifies the name of the network

The vCloud API NetworkConfigSection defines various network features such as DHCP and firewall

services.


206 VMware, Inc.

The vCloud API NetworkConnectionSection is a read‐only section that lists the network connections

and IP addresses that a vApp has acquired or been assigned at deployment. This section is present only

in a deployed vApp that has a network connection.

The OVF Item element, one of many that apply to the Envelope’s VirtualHardwareSection, specifies that the virtual machine’s NIC (resource type 10) is connected to Internet. It also specifies many other

details about the device. For more information about DMTF resource types, visit http://www.dmtf.org.

Example A-2. Network Information in an OVF Envelope

<Envelope ......<NetworkSection>

<ovf:Info>The list of logical networks</ovf:Info><Network ovf:name="Internet"/>

</NetworkSection><NetworkConfigSection>

<ovf:Info>Configuration parameters for logical networks</ovf:Info><NetworkConfig networkName="Internet">

<Features><Dhcp>true</Dhcp><Nat></Nat><Firewall></Firewall>

</Features></NetworkConfig>

</NetworkConfigSection><NetworkConnectionSection>

<NetworkConnection network="Internet"><IPAddress>192.168.1.100</IPAddress>

</NetworkConnection></NetworkConnectionSection>...<VirtualSystem>

<VirtualHardwareSection>...<Item>

...<rasd:Connection>Internet</rasd:Connection><rasd:Description>PCNet32 ethernet adapter on "Internet"

network</rasd:Description><rasd:ElementName>Network Adapter 1</rasd:ElementName>...

</Item>...

</VirtualSystem><VirtualHardwareSection>

</Envelope>

http://www.dmtf.org

VMware, Inc. 207

B

REST, an acronym for Representational State Transfer, is a term that has been widely employed to describe an

architectural style characteristic of programs that rely on the inherent properties of hypermedia to create and

modify the state of an object that is accessible at a URL.

This appendix includes the following topics:

“How REST Works” on page 207

“Using the vCloud REST API” on page 207

“For More Information About REST” on page 208

How REST WorksIf a URL of such an object is known to a client, the client can use an HTTP GET request to discover the

properties of the object. These properties are typically communicated in a structured document with an HTTP

Content‐Type of XML or JSON, that provides a representation of the state of the object. In a RESTful workflow,

documents (representations of object state) are passed back and forth (transferred) between a client and a

service with the explicit assumption that neither party need know anything about an object other than what is

presented in a single request or response. The URLs at which these documents are available are often “sticky,”

in that they persist beyond the lifetime of the request or response that includes them. The other content of the

documents is nominally valid until the expiration date noted in the HTTP Expires header.

Using the vCloud REST APIA “REST API” is in some ways an unfortunate term, since the application programs written to a REST API

actually use HTTP requests (which are often executed by a script or other higher‐level language) as a way of

making what are essentially remote procedure calls that create, modify, or delete the objects defined by the

API. This REST API (and others) is defined by a collection of XML documents that represent the objects on

which the API operates. The operations themselves (HTTP requests) are generic to all HTTP clients.

To write a RESTful client, you need to understand only the HTTP protocol and the semantics of standard

HTML markup. To use the vCloud API effectively in such a client, you need to know three things

the set of objects that the API supports, and what they represent (What is a vDC? How does it relate to an

organization or catalog?)

how the API represents these objects (What does the XML schema for an Org look like? What do the

individual elements and attributes represent?)

how the client refers to an object on which it wants to operate (Where are the links to objects in a vDC?

How does a client obtain and use them?)

To answer these questions, you need to understand the vCloud API XML schemas. These schemas define a

number of XML types, many of which are extended by other types. The vCloud API schemas also use and

extend types defined by the Open Virtualization Format. The XML elements defined in these schemas, along

with their attributes and composition rules (minimum and maximum number of elements or attributes, for

An Introduction to REST for vCloud API Users B


208 VMware, Inc.

example, or the prescribed hierarchy with which elements can be nested) represent the data structures of

objects in the cloud. A client can “read” an object by making an HTTP GET request to the object’s URL. A client

can “write” (create or modify) an object with an HTTP PUT or POST request that includes a new or changed

XML body document for the object. And a client can usually delete an object with an HTTP DELETE request.

In this document, we present example requests and responses, and also provide reference information on the

XML schemas that define the request and response bodies.

RESTful Workflow Patterns

All RESTful workflows fall into a pattern that includes only two fundamental operations:

Make an HTTP request (typically GET, PUT, POST, or DELETE). The target of this request is either a

well‐known URL (such as the root of a vCloud service or an organization hosted on such a service) or a

link obtained from the response to a previous request. (For example, a GET request to an organization

URL returns links to catalog and vDC objects contained by the organization.)

Examine the response, which always includes an HTTP response code and often includes a body (an XML

document, in the vCloud API). The response body may contain links or other information about the state

of an object. (For example, a response that includes a vApp body contains the details of the vApp’s current

virtual hardware configurations, as well as links that you can use to edit that configuration). If the

response is an HTTP response code, it indicates whether the request succeeded or failed, and may be

accompanied by a URL that points to a location from which additional information can be retrieved.

These two operations can repeat, in this order, for as long as necessary.

For More Information About RESTFor a comprehensive discussion of REST from both the client and server perspectives, see:

Richardson, Leonard, and Sam Ruby. RESTful Web Services. North Mankato: OʹReilly Media, Inc., 2007.

There are also many sources of information about REST on the Web, including:

http://www.infoq.com/articles/rest‐introduction

http://www.infoq.com/articles/subbu‐allamaraju‐rest

http://www.stucharlton.com/blog/archives/000141.html

http://www.infoq.com/articles/subbu-allamaraju-rest

http://www.infoq.com/articles/rest-introduction

http://www.stucharlton.com/blog/archives/000141.html

VMware, Inc. 209

Index

AAccessLevel element

example of use 57

schema reference 178

AccessSetting element

example of use 56, 57


AccessSettings element

example of use 56


AdminVdc element

example of use 104

AllEULAsAccepted

description 172

AllEULAsAccepted element


authentication

about 18

example request 21

AvailableNetworks element

example of use 103, 104, 129


CCaptureVAppParams element

example of use 68


Catalog element

example of use 35


CatalogItem element

example of use 36


CatalogItems element


Catalogs

about 14

controlling access to 56

CloneMediaParams element

example of use 51


CloneVAppParams element

example of use 52


CloneVAppTemplateParams element

example of use 51


ComposeVAppParams element

example of use 65


Configuration element


ControlAccessParams element

example of use 56


DDeployVAppParams


DeployVAppParams element


EError codes 146

Error element


examples

about 19

ExternalNetwork element

example of use 99


FFile element


Firewall rules

to create or modify 72

FirewallRule element

example of use 72

FirewallService element

example of use 72


GGroup element

example of use 113


GuestCustomizationSection element

cannot be passed in InstantiationParams 80

HHost element

example of use 124


210 VMware, Inc.


HTTP headers

Content-Type 142

HTTP status codes 18

IInstantiateVAppTemplateParams element



Instantiation Parameters

about 62

InstantiationParams element



IpRange element

example of use 72


LLink element

about 15

rel attribute 15

login

example of 21

logout

example of 30

MMedia element

example of use 50


MediaInsertOrEjectParams element

example of use 85


NNAT rules

to create or modify 72

NatRule element

example of use 72


network

vApp 62

NetworkConfigSection element

example of use 71

OOrg element

example of use 22


Org entity

to retrieve 34

OrgList element

example of use 21

OrgNetwork element

schema definition 154

OVF

to create vApp template from 42

to download vApp template as 47

to upload 171

PProperty element



Rrel attribute

about 15

ResourceEntity element

about 38



responses

contents of 18

Role element

example of use 114


SScreenTicket element


Source element


TTask element

example of use 89


Tasks

about 14

TasksList element

example of use 97

technical support resources 12

UUndeployVAppParams element


UploadVAppTemplateParams element

example of use 43


User element

example of use 110


VMware, Inc. 211

Index

VvApp

to compose from templates and virtual machines 65

to create from template 24, 61

to deploy and power-on 26

to instantiate 24

VApp element

example of use 65, 66, 67, 69


vApp networks

about 62

vApp template

add to catalog 54

to create from OVF 42

to create from vApp 68

VAppScopedVmId element

example of use 72

VAppTemplate element

example of use 61


to create 42

vDC

about 14

Vdc element



VimServer

example of use 120


Vm element



searching for 66

VmQuestionAnswer


VMWExtension

example of use 119


VMWExternalNetwork

example of use 133


VMWNetworkPool

example of use 136


VMWProviderVdc

example of use 127



212 VMware, Inc.

vcd 10 api guide

Documents

trademark of vmware

com2 vmware

vmware products

vmware web site

product listed andsupports

latest product updates

registered trademark