vCloud API Programming Guide for

Service Providers
vCloud API 27.0
vCloud Director 8.20

This document supports the version of each product listed and

supports all subsequent versions until the document is
replaced by a new edition. To check for more recent editions of
this document, see [Link]

EN-002438-00
vCloud API Programming Guide for Service Providers

You can find the most up-to-date technical documentation on the VMware Web site at:
[Link]
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to:
docfeedback@[Link]

Copyright © 2009–2017 VMware, Inc. All rights reserved. Copyright and trademark information.

VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
[Link]

2 VMware, Inc.
Contents

vCloud API Programming Guide for Service Providers 7

1 About the VMware vCloud API 9

Object Taxonomy 10
Objects, References, and Representations 12
Links and Link Relations 13
Client Workflow Overview 18
Using the vCloud API with vCloud Director 24
About the vCloud API Examples 26

2 Hello vCloud: A Simplified RESTful

Workflow 27
Logging In 28
Find a Catalog and a VDC 30
Retrieve the Contents of a Catalog 31
Retrieve a Catalog Item 32
Retrieve Deployment Information From the VDC 34
Deploy the vApp 35
Get Information About a vApp 38
Displaying the Virtual Machine Console 41
Undeploy, Power Off, and Delete the vApp 43
Log Out 44

3 Exploring a Cloud 47
Create a vCloud API Session 47
Retrieve a List of Organizations Accessible to You 54
Retrieve an Administrative View of a Cloud 56
Retrieve a List of vSphere Platform Operations and Objects for a Cloud 58

4 Provisioning an Organization 61
Upload an OVF Package to Create a vApp Template 62
Download a vApp or vApp Template as OVF 72
Upload a Media Image 76
Download a Media Image 78
Capturing and Importing vApps 79
Discovering and Adopting vApps 80
Managing Catalog Items 81
Creating and Using Independent Disks 85
View or Change the Owner of an Object 90
Controlling Access to vApps and Catalogs 91

VMware, Inc. 3
vCloud API Programming Guide for Service Providers

5 Deploying and Operating vApps and Virtual Machines 95

About Instantiation 98
Create a vApp From a Template 105
Modify Virtual Machine Hardware and Other Properties During vApp Template Instantiation 108
Compose a vApp From Existing Virtual Machines 111
Recompose a vApp to Add, Remove, or Reconfigure Virtual Machines 114
Clone a vApp 118
Create a vApp From an OVF Package 120
Capture a vApp as a Template 123
Update vApp Access Controls 125
Create a VM-VM Affinity Rule 126
Using Metadata to Control Virtual Machine Placement 129
Operate a vApp 133

6 Reconfiguring vApps and Virtual Machines 151

Retrieve the Configuration Links for a vApp 152
Retrieve the Configuration Links for a Virtual Machine 153
Update Multiple Sections of a Virtual Machine 157
Retrieve or Update a Modifiable Section 159
Update a vApp Network Configuration 161
Update the NetworkConnectionSection of a Virtual Machine 164
Retrieve or Modify the CPU Configuration of a Virtual Machine 165
Retrieve or Modify the GuestCustomizationSection of a Virtual Machine 167
Retrieve or Modify ProductSection Elements 168
Retrieve or Modify Groups of Related Sections in a Virtual Machine 171
Retrieve or Modify the Hard Disk Configuration of a Virtual Machine 173
Update the Storage Profile for a Virtual Machine 175
Override the Default Storage Profile for a Hard Disk 177
Specify Hard Disk IOPS 180

7 Managing an Organization 185

Administrator Credentials and Privileges 185
Organization Administration 186
VDC Administration 191
Network Administration 199
Catalog Administration 219
User and Group Administration 241
About Federation and Single Sign-On 251
Working With Roles and Rights 257

8 Managing and Monitoring a Cloud 267

Retrieve or Update System Settings 268
Attach a vCenter Server 269
Finding Available vCenter Resources 270
Create an Organization 279
Create a Provider VDC 286
Create an External Network 297
Create a Network Pool 300

4 VMware, Inc.
Contents

Add a VDC to an Organization 304

Creating and Managing VM-Host Affinity Rules 323
Creating and Managing VDC Templates 329
Import a Virtual Machine from vCenter 343
Relocate a Virtual Machine to a Different Datastore 346
Configure the vCloud Director AMQP Service 347
System Truststore and Keytab Maintenance 351
Retrieve the vSphere URL of an Object 354

9 Working With Object Metadata 357

Retrieve or Update a Metadata Element 360
Retrieve or Update a Metadata Value 363

10 Using the Query Service 365

Typed Queries 366
Packaged Queries 370
Query Parameters 375
Add a Metadata Filter to a Query 379

11 Configuring and Using Blocking Tasks and Notifications 381

Configure Notifications 382
Retrieve or Update Blocking Task Settings 383
Monitor Blocking Tasks 388
Take Action on a Blocking Task 389
Extend The Timeout Expiration of an Active Task 392
Notification Message Format 393

12 Extending vCloud Director 399

vCloud Director Object Extensions 399
vCloud Director Extension Services 409

13 XML Representations in the vCloud API 439

XML Namespace Identifiers 441
Common vCloud API Attributes 442
Retrieve an Object as an Entity 444

Index 447

VMware, Inc. 5
vCloud API Programming Guide for Service Providers

6 VMware, Inc.
vCloud API Programming Guide for Service
Providers

This edition of the vCloud API Programming Guide for Service Providers provides information about version
27.0 of the vCloud API.

VMware provides many different APIs and SDKs for applications and goals. This guide provides
information about the vCloud API for developers who are interested in creating RESTful clients of
VMware vCloud Director.

Revision History
The vCloud API version number is incremented whenever any of its types or operations changes. The
vCloud API Programming Guide for Service Providers is revised with each release of VMware vCloud Director.
Versions of the vCloud API that were not introduced in a VMware vCloud Director release are documented
in the vCloud Air Compute Service Programming Guide . An API version can be deprecated whenever a newer
version of the API supports an equivalent set of features. Use of a deprecated API version is not
recommended. Support for an API version may be removed in the release following deprecation.

Table 1. Revision History

Revision Date Description Release Vehicle Status

21 FEB 2017 API Version 27.0 vCloud Director 8.20 supported

26 MAY 2016 API Version 20.0 vCloud Director 8.10 supported

N/A API Version 19.0 vCloud Air Compute Service deprecated

N/A API Version 18.0 vCloud Air Compute Service deprecated

25 JAN 2016 API Version 17.0 vCloud Air Compute Service supported

N/A API Version 16.0 vCloud Air Compute Service deprecated

15 DEC 2015 API Version 14.0 vCloud Air Compute Service deprecated

21 SEP 2015 API Version 13.0 vCloud Air Compute Service supported

22 AUG 2015 API Version 12.0 vCloud Air Compute Service deprecated

10 JUL 2015 API Version 11.0 vCloud Air Compute Service deprecated

10 SEP 2015 API Version 9.0 vCloud Director 8.0, vCloud Air supported
Compute Service

15 APR 2015 API Version 7.0. vCloud Air Compute Service deprecated

16 MAR 2015 API Version 6.0 vCloud Air Compute Service deprecated

13 JAN 2015 API Version 5.11 vCloud Air Compute Service deprecated

24 OCT 2014 API Version 5.10 vCloud Air Compute Service deprecated

19 SEP 2014 API Version 5.9 vCloud Air Compute Service deprecated

VMware, Inc. 7
vCloud API Programming Guide for Service Providers

Table 1. Revision History (Continued)

Revision Date Description Release Vehicle Status

05 SEP 2014 API Version 5.8 vCloud Air Compute Service deprecated

01 AUG 2014 API Version 5.7. vCloud Air Compute Service deprecated

07 OCT 2014 API Version 5.6 vCloud Director 5.6 supported

19 SEP 2013 API Version 5.5 vCloud Director 5.5 supported

10 SEP 2012 API Version 5.1 vCloud Director 5.1 deprecated

01 SEP 2011 API Version 1.5 vCloud Director 1.5 deprecated

30 AUG 2010 API Version 1.0 vCloud Director 1.0 not supported

14 APR 2010 API Version 0.9 N/A not supported

Intended Audience
This guide is intended for software developers who are building VMware Ready Cloud Services, including
interactive clients of VMware vCloud Director. This guide discusses Representational State Transfer (REST)
and RESTful programming conventions, the Open Virtualization Format Specification, and VMware Virtual
machine technology. You must be familiar with these and other widely deployed technologies such as XML,
HTTP, and the Windows or Linux operating system.

Related Publications
The vCloud API Schema Reference includes reference material for all elements, types, queries, and operations
in the vCloud API. It also includes the schema definition files. The schema reference is available in HTML
format in the vCloud Director documentation center. The vCloud Air Compute Service Programming Guide
provides information about the subset of vCloud API operations and objects that are accessible to tenants of
®
the VMware vCloud Air™ Virtual Private Cloud OnDemand service option.

The VMware vCloud Director Administrator's Guide and VMware vCloud 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 publications, go to [Link]

8 VMware, Inc.
About the VMware vCloud API 1
The VMware vCloud API provides support for developers who are building interactive clients of
VMware vCloud Director using a RESTful application development style.

vCloud API clients communicate with servers over HTTP, exchanging representations of vCloud objects.
These representations take the form of XML elements. You use HTTP GET requests to retrieve the current
representation of an object, HTTP POST and PUT requests to create or modify an object, and HTTP DELETE
requests to delete an object.

This chapter includes the following topics:

n “Object Taxonomy,” on page 10

n “Objects, References, and Representations,” on page 12

n “Links and Link Relations,” on page 13

n “Client Workflow Overview,” on page 18

n “Using the vCloud API with vCloud Director,” on page 24

n “About the vCloud API Examples,” on page 26

VMware, Inc. 9
vCloud API Programming Guide for Service Providers

Object Taxonomy
The vCloud API defines a set of objects common to cloud computing environments. An understanding of
these objects, their properties, and their relationships is essential to using the vCloud API.

Figure 1‑1. vCloud API Object Taxonomy

Organization

vDC1
Catalog 3
vApp
vApp template Catalogitem
External
em Publish
Media Catalog 2 em catalog

Media em
Catalogitem
em
Network Catalog 1 em
em
Catalogitem
Catalogitem
vDC2
Catalogitem
Catalogitem External
vApp Subscribe
vApp template catalog

Media
Media

Network users groups TasksList

vCloud API objects have the following high-level properties:

Organizations A cloud can contain one or more organizations. Each organization is a unit of
administration for a collection of users, groups, and computing resources.
Users authenticate at the organization level, supplying credentials
established when the user was created or imported. User credentials are
authenticated by the organization's identity provider. vCloud Director
includes an integrated identity provider. It also supports several standards-
based external identity providers.

Users and Groups An organization can contain an arbitrary number of users and groups. Users
can be created locally or managed by an external identity provider. Groups
must be managed by an external identity provider. Permissions within an
organization are controlled through the assignment of rights and roles to
users and groups.

Catalogs Catalogs contain references to vApp templates and media images. You can
configure a catalog in several different ways:

n as a repository for local content that can remain private to the catalog
owner or can be shared with other users, groups, or organizations in
your cloud

n as a source of published content, to which other clouds can subscribe.

10 VMware, Inc.
Chapter 1 About the VMware vCloud API

n as a local repository for content published by another cloud or any Web

site that hosts a VMware Content Subscription Protocol (VCSP)
endpoint.

An organization administrator or catalog owner controls catalog sharing.

Organization administrators in organizations that have permission to
publish catalogs control publication and subscription options for catalogs in
their organization. A system administrator can enable background
synchronization of catalogs with external sources and set background
synchronization schedules to regulate consumption of network bandwidth
by this activity.

Organization VDCs An organization virtual datacenter (organization VDC) is a deployment

environment for virtual systems owned by the containing organization, and
an allocation mechanism for resources such as networks, storage, CPU, and
memory. In an organization VDC, computing resources are fully virtualized,
and can be allocated based on demand, service level requirements, or a
combination of the two.

Organization VDC An organization VDC can be provisioned with zero or more networks. These
Networks organization VDC networks can be configured to provide direct or routed
connections to external networks, or can be isolated from external networks
and other organization VDC networks. Routed connections require an Edge
Gateway and network pool in the VDC. The Edge Gateway provides firewall,
network address translation, static routing, VPN, and load balancing
services.

Virtual Systems and Virtual systems and ISO-format media images are stored in a catalog and
Media Images represented as catalog item objects. 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, including:

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

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

n End-user license agreement terms for each virtual machine.

n Deployment lease terms, typically inherited from the containing

organization, that constrain the consumption of VDC resources by the
vApp.

n 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 that it contains.

Tasks Asynchronous operations are tracked by task objects. Running and recently
completed tasks initiated by members of an organization are kept on the
organization’s tasks list.

VMware, Inc. 11
vCloud API Programming Guide for Service Providers

Objects, References, and Representations

The vCloud API represents objects as XML documents in which object properties appear as elements and
attributes with typed values. The object hierarchy is defined by an XML schema.

XML representations of first-class vCloud API objects, such as the objects in Figure 1-1, include these
attributes.

id The object identifier, expressed in URN format. The value of the id attribute
uniquely identifies the object, persists for the life of the object, and is never
reused. The id attribute value is intended to provide a context-free identifier
that can be used with the vCloud API entityResolver (see “Retrieve an
Object as an Entity,” on page 444).

type The object type, specified as a MIME content type.

href An object reference, expressed in URL format. This reference includes the
object identifier portion of the id attribute value, and supplies additional
information, including the current location of the object when accessed in a
specific view. 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 how the server constructs href strings might
change in future releases.

Views
The vCloud API defines several contexts, or views, in which you can access objects in a cloud. These views
are expressed in the URL returned as the href of an object, and have the following forms, where API-URL is
a URL of the form [Link] and object-type is a string indicating the type of the
object.

user view A URL of the form API-URL/object-type/id indicates that any user can
access the object.

admin view A URL of the form API-URL/admin/object-type/id indicates that

organization administrators and system administrators can access the object.
Organization administrators do not have rights to modify some objects in the
admin view.

extension view A URL of the form API-URL/admin/extension/object-type/id indicates that

system administrators can access the object.

A given object retrieved in one view may have a different representation and media type from the same
object retrieved in a different view. Not all objects are presented in every view.

Example: Object id, type, and href Attributes

These abbreviated request and response examples show the id, type, and href attributes in the user and
admin views of an organization.

Request:

GET [Link]

12 VMware, Inc.
Chapter 1 About the VMware vCloud API

Response:

<Org
...
id="urn:vcloud:org:72fe715c-5f6a-407f-bbb2-bf465915b5f4"
type="application/[Link]+xml"
href="[Link]
...>
...
</Org>

The id value is the same in both cases, but the type and href attributes have values specific to the view.

Request:

GET [Link]

Response:

<AdminOrg
...
id="urn:vcloud:org:72fe715c-5f6a-407f-bbb2-bf465915b5f4"
type="application/[Link]+xml"
href="[Link]
...>
...
</AdminOrg>

The value of the id attribute is a permanent, unique object identifier. The value of the href attribute is an
object locator that refers to a specific view of the object in its current location. Unlike the value of the id
attribute, object location and view context can change during the life of an object. The example in
“Example: Using the entityResolver URL,” on page 445 shows how to retrieve this object as entity.

When a client application must keep a persistent reference to an object, the best practice is to keep a
reference to the id and the href (URL) that was most recently used to access the object. When the application
needs to access the object in the future, it should first try using the saved href. If that fails, use the id with
the entity resolver to obtain a valid reference to the object, then replace the saved href with that valid
reference.

Links and Link Relations

The vCloud API makes extensive use of Link elements to provide references to objects and the actions that
they support. These elements are the primary mechanism by which a server tells a client how to access and
operate on an object.

The server creates Link elements in a response body. They are read-only at the client. If a request body
includes a Link element, the server ignores it.

Attributes of a Link Element

In the XML representation of a vCloud object, each Link element has the following form:

<Link rel="relationship"
type="application/[Link].object_type+xml"
href="URL"
name="string"/>

VMware, Inc. 13
vCloud API Programming Guide for Service Providers

Attribute values in a Link element supply the following information:

rel Defines the relationship of the link to the object that contains it. A
relationship can be the name of an operation on the object, a reference to a
contained or containing object, or a reference to an alternate representation of
the object. The relationship value implies the HTTP verb to use when you use
the link's href value as a request URL.

type The object type, specified as a MIME content type, of the object that the link
references. This attribute is present only for links to objects. It is not present
for links to actions.

href An object reference, expressed in URL format. This reference includes the
object identifier portion of the id attribute value, and supplies additional
information, including the current location of the object when accessed in a
specific view. 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 how the server constructs href strings might
change in future releases.

name The name of the referenced object, taken from the value of that object's name
attribute. Action links do not include a name attribute.

Table 1‑1. Link Relationships and HTTP Request Types

rel Attribute Value Action or Relationship Description Implied HTTP Verb

abort Abort this blocking task. POST

add Add an item to this container. POST

alternate References an alternate representation of this object. GET

answer Provide user input requested by a virtual machine. POST

authorization:check Check whether an extension service operation is POST

authorized for an entity.

blockingTask A list of pending blocking task requests in this cloud. GET

bundle:upload Upload an extension service localization bundle. PUT

bundles:cleanup Remove unused extension service localization bundles. POST

catalogItem References the CatalogItem object that refers to this GET

object.

certificate:reset Removes the SSL certificate used by this service. POST

certificate:update Updates the SSL certificate used by this service. POST

checkCompliance Check that this virtual machine is using a storage profile POST
of the intended type.

consolidate Consolidate this virtual machine. POST

controlAccess Apply access controls to this object. POST

copy Reserved N/A

customizeAtNextPowerOn Force guest customization to be applied the next time POST

this virtual machine is powered on.

deploy Deploy this vApp. POST

disable Disable this object. POST

discardState Discard the suspended state of this virtual machine. POST

disk:attach Attach an independent disk to this virtual machine. POST

14 VMware, Inc.
Chapter 1 About the VMware vCloud API

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

rel Attribute Value Action or Relationship Description Implied HTTP Verb

disk:detach Detach an independent disk from this virtual machine. POST

down References an object contained by this object. GET

down:aclRules Retrieve the ACL rules for this resource class action. GET

down:apiDefinitions Retrieve the API definitions for this extension service. GET

down:apiFilters Retrieve the API filters for this extension service. GET

down:extensibility Add an extension service to the system. POST

down:fileDescriptors Retrieve file descriptors for extension services APIs GET

down:files Retrieve files for extension services APIs GET

down:resourceClassActions Retrieve the actions defined for this extension service GET
resource class.

down:resourceClasses Retrieve the resource classes defined by this extension GET

service.

down:serviceLinks Retrieve the service links defined by this extension GET

service.

down:serviceResources Retrieve the list of extension service resources of this

class.

down:services Retrieve the list of registered extension services. GET

download:alternate Reserved N/A

download:default References the default location from which this file can GET
be downloaded.

download:identity References the extended OVF descriptor of this vApp GET

template. The extended OVF descriptor contains
additional information such as MAC address, BIOS
UUID, and NetworkConfigSection

edgeGateway:configureServices Update the network services offered by this Edge POST

Gateway.

edgeGateway:reapplyServices Reapply (after an update) the network services offered POST

by this Edge Gateway.

edgeGateway:redeploy Redeploy the vShield Edge supporting this Edge POST

Gateway.

edgeGateway:syncSyslogSettings Synchronize syslog server addresses used by this Edge POST

Gateway with system defaults.

edgeGateway:upgrade Upgrade the backing configuration of this Edge Gateway POST

from compact to full.

edgeGateways List the Edge Gateway objects in this organization VDC. GET

edit Modify this object, typically by replacing its current PUT

representation with the one in the request body.

enable Enable this object. POST

enterMaintenanceMode Put this virtual machine into maintenance mode. POST

entity Retrieve a representation of the object on which an GET

operation triggered this notification.

entityResolver Retrieve an object id as a context-free Entity element. GET

event:create Create an event in an this organization's event stream. POST

exitMaintenanceMode Take this virtual machine out of maintenance mode. POST

VMware, Inc. 15
vCloud API Programming Guide for Service Providers

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

rel Attribute Value Action or Relationship Description Implied HTTP Verb

fail Fail this blocking task. POST

firstPage Reference to the first page of a paginated response. GET

installVmwareTools Install VMware Tools on this virtual machine. POST

instantiate Instantiate a VDC template to create a VDC in this POST

organization.

keystore:reset Removes the keystore used by this service. POST

keystore:update Updates the keystore used by this service. POST

keytab:reset Removes the keytab used by this service. POST

keytab:update Updates the keytab used by this service. POST

lastPage Reference to the last page of a paginated response. GET

media:ejectMedia Eject virtual media from a virtual device. POST

media:insertMedia Insert virtual media into a virtual device. POST

metrics Retrieve a subset of current or historic metrics from a POST

virtual machine

merge Merge one or more Provider VDCs with this Provider POST
VDC.

migrateVms Migrate virtual machines from this resource pool to a POST

different one.

move Reserved N/A

nextPage Reference to the next page of a paginated response. GET

orgVdcNetworks List the organization VDC networks supported by this GET

Edge Gateway.

ova Reserved N/A

ovf References the OVF descriptor of this vApp template. GET

power:powerOff Power off this vApp or virtual machine. POST

power:powerOn Power on this vApp or virtual machine. POST

power:reboot Reboot this vApp or virtual machine. POST

power:reset Reset this vApp or virtual machine. POST

power:shutdown Shut down this vApp or virtual machine. POST

power:suspend Suspend this vApp or virtual machine. POST

previousPage Reference to the previous page of a paginated response. GET

publish Share this catalog. POST

publishToExternalOrganizations Publish this catalog externally POST

recompose Recompose this vApp to add, remove, or reconfigure POST

virtual machines.

reconfigureVm Update multiple sections of a virtual machine. POST

reconnect Reconnect this vCenter Server to the system. POST

refreshStorageProfiles Refresh the list of storage profiles that exist on the POST
vCenter service backing this Provider VDC.

refreshVirtualCenter Refresh the representation of this vCenter server POST

register Register a VCenter Server with the system. POST

16 VMware, Inc.
Chapter 1 About the VMware vCloud API

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

rel Attribute Value Action or Relationship Description Implied HTTP Verb

reloadFromVc Reload certain properties of this virtual machine from POST

the vCenter database.

relocate Relocate this virtual machine. POST

remove Remove this object. DELETE

remove:force Force removal of this object. DELETE

repair Repair this host or network. POST

resourcePoolVmList List the virtual machines using this resource pool. GET

resume Resume this blocking task. POST

rights List the service-specific rights created by this extension GET

service.

rights:cleanup Remove service-specific rights no longer used by any POST

extension service.

screen:acquireTicket Retrieve a screen ticket for this virtual machine. GET

screen:thumbnail Retrieve a thumbnail view of the screen of this virtual GET

machine.

shadowVms List shadow virtual machines associated with the virtual GET
machines in this vApp template.

snapshot:create Create a snapshot of the virtual machines in this vApp. POST

snapshot:removeAll Remove all snapshots created for the virtual machines in POST
this vApp.

snapshot:revertToCurrent Revert all virtual machines in this vApp to their current POST
snapshot.

storageProfile References the storage profile for this object. GET

subscribeToExternalCatalog Add an external subscription to this catalog. POST

sync Synchronize this catalog or catalog item with its external POST
source.

syncSyslogSettings Synchronize syslog server addresses used by this vApp POST

network with system defaults.

takeOwnership Take ownership of this user's vApps, media, and POST

catalogs.

task Retrieve the blocking task that triggered this notification. GET

task:cancel Cancel this task. POST

task:create Create a task object. POST

task:owner Reference to the owner of a task. GET

truststore:reset Remove the truststore used by this service. POST

truststore:update Update the truststore used by this service. PUT

undeploy Undeploy this vApp. POST

unlock Unlock this user account. POST

unregister Unregister this vCenter Server. POST

up References an object that contains this object. GET

update:resourcePools Update the resource pools of this Provider VDC POST

updateProgress Request an update of this task's progress. POST

VMware, Inc. 17
vCloud API Programming Guide for Service Providers

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

rel Attribute Value Action or Relationship Description Implied HTTP Verb

upgrade Upgrade this host. POST

upload:alternate Reserved N/A

upload:default References the default location to which this object can PUT
be uploaded.

vSphereWebClientUrl A URL that you can use to view this object with the GET
vSphere Web Client

Client Workflow Overview

vCloud API clients implement a RESTful workflow, making HTTP requests to the server and retrieving the
information they need from the server’s responses.

About RESTful Workflows

REST, an acronym for Representational State Transfer, describes an architectural style characteristic of
programs that use the Hypertext Transfer Protocol (HTTP) to exchange serialized representations of objects
between a client and a server. In the vCloud API, these representations are XML documents.

In a RESTful workflow, representations of objects are passed back and forth between a client and a server
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 often 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.

vCloud REST API Workflows

Application programs written to a REST API use HTTP requests that are often executed by a script or other
higher-level language to make remote procedure calls that create, retrieve, update, or delete objects that the
API defines. In the vCloud REST API, these objects are defined by a collection of XML schemas. The
operations themselves are HTTP requests, and so are generic to all HTTP clients.

To write a RESTful client application, you must understand only the HTTP protocol and the semantics of
XML, the transfer format that the vCloud API uses. To use the vCloud API effectively in such a client, you
need to know only a few things:

n The set of objects that the API supports, and what they represent; for example, what is a VDC and how
does it relate to an organization or catalog?

n How the API represents these objects; for example, what does the XML schema for an Org look like?
What do the individual elements and attributes represent?

n How a client refers to an object on which it wants to operate; for example, where are the links to objects
in a VDC? How does a client obtain and use them?

You can find that information in this Guide, and in the vCloud API Schema Reference. See “About the Schema
Reference,” on page 26.

RESTful Workflow Patterns

All RESTful workflows follow a common pattern.

1 Make an HTTP request, typically GET, PUT, POST, or DELETE. The target of this request is either a
well-known URL such as the vCloud API versions URL, or a URL obtained from the response to a
previous request. For example, a GET request to an organization URL returns links to catalog and VDC
objects that the organization contains.

18 VMware, Inc.
Chapter 1 About the VMware vCloud API

2 Examine the response, which always includes an HTTP response code and usually includes a body. In
the vCloud API, a response body is an XML document that can contain any of the following items.
n XML elements and attributes that represent object properties

n Link elements that implement operations on the object or its contents

n If the object is being created or modified, an embedded Task object that tracks the progress of the
creation or modification

These operations can repeat, in this order, for as long as necessary.

vCloud API REST Requests

To retrieve object representations, clients make HTTP requests to object references. The server supplies these
references as href attribute values in responses to GET requests.

Every vCloud Director installation has a well-known URL from which an unauthenticated user can retrieve
a SupportedVersions document, which lists each version of the vCloud API that the server supports. For
each version, the response lists the names and MIME types of the complex types defined in the version's
XML namespace, and the version login URL. A system administrator can use that URL to authenticate to the
cloud by logging in to the System organization. An authenticated user can discover other vCloud API URLs
by making GET requests to URLs retrieved from the login response, and the URLs contained in responses to
those requests. See Chapter 3, “Exploring a Cloud,” on page 47.

Requests are typically categorized by the type of requested operation: create, retrieve, update, and delete.
This sequence of verbs is often abbreviated with the acronym CRUD. Each type of request is characterized
by the use of specific HTTP verb to access a URL found in a Link element that has an operation-specific
value for its rel (relation) attribute.

Table 1‑2. CRUD Operations Summary

Operation Type HTTP Verb Link Relation Operation Summary

Create POST add Creates a new object.

Retrieve GET down Retrieves the representation of an existing object in its current
state.

Update PUT edit Modifies an existing object.

Delete DELETE remove Deletes an existing object. If the object is a container, you must
remove all of its contents before you can delete it.

For example, this Link element indicates that you can use the URL
[Link] to update the Org object that contains it.

<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />

The implied HTTP verb is PUT.

Important Request bodies must contain all required elements and attributes, even if you are not changing
their values. Because optional elements and attributes typically revert to default values if they are omitted or
empty, it is a best practice to include optional elements in request bodies that modify existing objects. Link
elements and href attributes from responses do not need to be included in modified sections. Some elements
and attributes are read-only and cannot be modified. See the schema reference for details.

Security
HTTP communications between a vCloud API client and server are secured with SSL. API clients must also
complete a login request to receive an authorization token that must be included in all subsequent requests.

VMware, Inc. 19
vCloud API Programming Guide for Service Providers

Request Headers
The following HTTP headers are typically included in vCloud API requests:

Accept All requests must include an HTTP Accept header that designates the vCloud
API version that the client is using. Two forms of this header are supported:

Accept: application/*;version=api-version

Accept: application/[Link]+xml;version=api-version

The second form constrains acceptable responses to a type defined the

vCloud API schema. For example, the following header indicates that the
request is from a vCloud API version 5.6 client, and will accept any type
defined in that API version:

Accept: application/*;version=5.6

In general, client requests can access objects defined by any version of the
vCloud API that is less than or equal to the version specified in the Accept
header. See “API Versions,” on page 439.

Note Accept headers of the following form are also allowed in vCloud API
requests, but they are not compliant with RFC 2616 and might be rejected by
future versions of the vCloud API.

Accept: application/*+xml;version=api-version

Accept-Encoding By default, the system returns response content as uncompressed XML.

Compressing the response can improve performance, especially when the
response is large and network bandwidth is a factor. (Requests cannot be
compressed.) To request a response to be returned as compressed XML,
include the following header:

Accept-Encoding: gzip

The response is encoded using gzip encoding as described in RFC 1952, and
includes the following header:

Content-Encoding: gzip

In the default configuration, responses smaller than 64KB are never

compressed.

Accept-Language Message strings in ErrorType responses are localized. To specify the language
desired in responses, use the Accept-Language request header. To request a
response with message strings localized to French, use the following header:

Accept-Language: fr

Authorization All requests to create a vCloud API session must include an Authorization
header of the form prescribed by the identity provider that your organization
uses. See “Create a vCloud API Session,” on page 47.

20 VMware, Inc.
Chapter 1 About the VMware vCloud API

Content-Type Requests that include a body must include an appropriate HTTP Content-
Type header. Content types for all elements are listed in the schema reference.
In addition, 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 object is
application/[Link]+xml.

<CatalogItem
type="application/[Link]+xml"
name="Ubuntu Template with vsftpd"
... />

A POST or PUT request that supplies a CatalogItem in the request body

requires the following Content-Type header:

Content-Type: application/[Link]+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.

x-vcloud-authorization This header, which is returned with the Session response after a successful
log-in, must be included in all subsequent requests from clients that
authenticate to the integrated identity provider (see “Create a Session Using
Basic Authentication,” on page 53) or the SAML identity provider (see
“Create a Session Using SAML Authentication,” on page 50).

Note Clients that authenticate to the OAuth identity provider can include
either the x-vcloud-authorization header or the OAuth Authorization:
Bearer header to authorize a request. See “Create a Session Using OAuth
Authentication,” on page 48.

X-VMWARE-VCLOUD- The value of this header is used to build a request ID returned in the value of
CLIENT-REQUEST-ID the X-VMWARE-VCLOUD-REQUEST-ID header (see “Response Headers,”
on page 23). The value of this header cannot contain more than 128
characters drawn from the set of letters, numbers, and the hyphen (-). Values
with invalid characters are ignored. Values with more than 128 characters are
truncated.

Request Bodies
vCloud Director uses a validating XML parser that requires elements in a request body to agree with the
schema in order and number. Request bodies are rejected as invalid unless they meet the following criteria:

n XML namespace attributes must be supplied for all namespaces represented by elements in the request.
See “XML Namespace Identifiers,” on page 441.

n If multiple namespaces are represented in the request, XML namespace attributes must include an
identifying prefix, and that prefix must be used with all elements from that namespace.

n All required elements must appear in request bodies. All elements that appear in request bodies must
appear in the order that the schema establishes, and with content that conforms to the type constraint
that the schema specifies.

VMware, Inc. 21
vCloud API Programming Guide for Service Providers

Request Limits
To guard against denial-of-service attacks, vCloud Director imposes the following limits on vCloud API
requests:

n Requests cannot exceed 512 KB.

n Requests cannot contain more than 4096 XML elements.

n Requests cannot have a depth greater than 100.

vCloud API REST 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.

Response Content
Response content depends on the requested operation. The response to a GET request is typically the
complete representation of an existing object. The response to a PUT or POST request always contains
values for the href, name, and id attributes of the object being created or updated. It also contains at most
one Task element that you can retrieve to track the progress of the operation. When the Task completes with
a status of success, a GET request to the object's href returns all properties of the object. If the Task
completion status is not success, the object is in an indeterminate state, and should be deleted.

HTTP Response Codes

A vCloud API client can expect a subset of HTTP status codes in a response.

Table 1‑3. HTTP Status Codes that the vCloud API Returns
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 element.

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

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

invalid.

401 Unauthorized Login failed or authentication token has expired.

403 Forbidden Any of:

n One or more objects specified in the request could not
be found in the specified container.
n The user is not authenticated or does not have
adequate privileges to access one or more objects
specified in the request.
n The user 's session has expired.

404 Not Found Usually indicates a malformed request URL or request

body.

405 Method Not Allowed The HTTP method specified in the request is not supported
for this object.

22 VMware, Inc.
Chapter 1 About the VMware vCloud API

Table 1‑3. HTTP Status Codes that the vCloud API Returns (Continued)
Status Code Status Description

406 Not Acceptable The resource identified by the request is not capable of
generating a response of the type specified in the request's
Accept header.

409 Conflict The object state is not compatible with the requested
operation.

415 Unsupported Media Type The resource identified by the request does not support a
request of the specified Content-Type and HTTP method.

500 Internal Server Error The request was received but could not be completed
because of an internal error at the server.

503 Service Unavailable The server is currently unable to handle the request due to
a temporary condition such as resource exhaustion or
server maintenance.

504 Gateway Timeout The server, while acting as a gateway or proxy, did not
receive a timely response from the upstream server
specified by the request URL.

Response Headers
The following HTTP headers can appear in responses to vCloud API requests:

x-vcloud-authorization This header is returned with the Session response after a successful log-in
and must be included in all subsequent requests from clients that
authenticate to the integrated identity provider (see “Create a Session Using
Basic Authentication,” on page 53) or the SAML identity provider (see
“Create a Session Using SAML Authentication,” on page 50).

Note Clients that authenticate to the OAuth identity provider can include
either the x-vcloud-authorization header or the OAuth Authorization:
Bearer header to authorize a request. See “Create a Session Using OAuth
Authentication,” on page 48.

X-VMWARE-VCLOUD- If a request supplied an X-VMWARE-VCLOUD-CLIENT-REQUEST-ID

REQUEST-ID header, the response contains an X-VMWARE-VCLOUD-REQUEST-ID
header whose value combines the value in the X-VMWARE-VCLOUD-
CLIENT-REQUEST-ID with a unique ID. This value is added to every
vCloud Director, vCenter, and ESXi log message related to processing the
request, and provides a way to correlate the processing of a request across all
participating systems. If a request did not supply a X-VMWARE-VCLOUD-
CLIENT-REQUEST-ID header, the response contains an X-VMWARE-
VCLOUD-REQUEST-ID header with a generated value that cannot be used
for log correlation.

X-VMWARE-VCLOUD- The execution time, in milliseconds, of the request that generated this
REQUEST-EXECUTION- response.
TIME

VMware, Inc. 23
vCloud API Programming Guide for Service Providers

Using the vCloud API with vCloud Director

VMware vCloud Director supports several versions of the vCloud API. You can use a browser or other
HTTP client program to send requests and receive responses.

The vCloud Director REST API Reference documentation includes HTML reference material for all XML
elements and complex types defined by the vCloud API. It also includes example XML representations. See
“About the Schema Reference,” on page 26. For information about HTTP client programs to use with
vCloud Director, see “REST Client Programs,” on page 25.

Procedure
1 Configure the vCloud Director REST API base URL.

a Log in to the vCloud Director Web Console as a system administrator.

b In the vCloud Director Web Console, open System Settings > Public Addresses

c Type the URL in the VCD public REST API base URL text box.

2 (Optional) Retrieve the list of supported API versions from the server.

After the vCloud Director REST API base URL has been configured, any HTTP client can request a
document that lists all the API versions that the server supports. See “Example: Retrieve the Login URL
and List of Supported API Versions,” on page 24.

3 (Optional) If you want to use the vSphere Web Client to access vCloud API objects on a vSphere server,
verify that the vSphere Web Client URL is enabled for all vCenter servers from which you want to
retrieve the vSphere URL of an object.

You can manage this feature on the General tab of the vCenter Properties page of the vCloud Director
Web console.

Example: Retrieve the Login URL and List of Supported API Versions
The api/versions request can be made by any client, whether or not the client is authenticated by
vCloud Director. The response, a small subset of which is shown here, includes a VersionInfo element for
each API version that this vCloud Director installation supports. Each VersionInfo element contains:

n A LoginUrl element that contains the URL to which a client can make a login request to access that
version of the vCloud API. See “Logging In,” on page 28.

n For API versions earlier than 5.7, MediaTypeMapping elements for each complex type supported by that
version of the vCloud API. This optional element is not returned in the VersionInfo for API version 5.7
and later.

Request:

GET [Link]

Response:

200 OK
Content-Type: text/xml
...
<SupportedVersions
xmlns="[Link]
xmlns:xsi="[Link]
xsi:schemaLocation="[Link]
[Link]
<VersionInfo>
<Version>5.1</Version>

24 VMware, Inc.
Chapter 1 About the VMware vCloud API

<LoginUrl>[Link]
<MediaTypeMapping>
<MediaType>application/[Link]+xml</MediaType>
<ComplexTypeName>CatalogType</ComplexTypeName>
<SchemaLocation>[Link]
</MediaTypeMapping>
<MediaTypeMapping>
...
</MediaTypeMapping>
...
</VersionInfo>
<VersionInfo>
<Version>5.6</Version>
<LoginUrl>[Link]
<MediaTypeMapping>
...
</MediaTypeMapping>
...
</VersionInfo>
<VersionInfo>
<Version>5.7</Version>
<LoginUrl>[Link]
</VersionInfo>
</SupportedVersions>

Note You can use the URL in the SchemaLocation element with a GET request to retrieve the file in which
that complex type is defined. This type of request can be made by any client, whether or not the client is
authenticated by vCloud Director. For example, this request retrieves the schema file [Link]:

GET [Link]

All vCloud API requests are processed in the [Link] XML namespace. Schema
files for all API versions can be retrieved from a .../api/v1.5/... URL.

What to do next
Decide on an HTTP client program to use. See “REST Client Programs,” on page 25.

REST Client Programs

Any client application that can send HTTPS requests can be an appropriate tool for developing RESTful
applications with the vCloud API.

REST client plug-ins are available for most browsers and many IDEs. Many of the examples in the vCloud
API Programming Guide for Service Providers were developed using two open-source programs: cURL
([Link] and the RESTclient ([Link]

VMware provides additional SDK products that implement language-specific bindings for the vCloud API,
and include their own HTTP client capability. See
[Link]

VMware, Inc. 25
vCloud API Programming Guide for Service Providers

About the Schema Reference

The vCloud API Schema Reference includes reference material for all elements, types, queries, and operations
in the vCloud API. It also includes a downloadable set of the schema definition files.

The vCloud API Schema Reference is available in HTML format in the vCloud Director documentation center.

Important The schema reference includes reference topics for the entire vCloud API, including topics that
apply to objects and operations that are accessible only to vCloud Air tenants.

About the vCloud API Examples

The vCloud API Programming Guide for Service Providers includes many examples of HTTP requests and
responses. These examples show the workflow and content associated with operations such as browsing,
provisioning, and managing your cloud and its contents, and operating virtual systems.

Example requests generally conform to the rules listed in “Request Bodies,” on page 21. Most example
responses show only those elements and attributes that are relevant to the operation being discussed.
Ellipses (…) indicate omitted content within response bodies. Several additional conventions apply.

n The HTTP Accept header, which is required in all requests, is omitted from most examples. See “API
Versions,” on page 439 for more about this header and how it is used by the vCloud API.

n Authorization headers such as x-vcloud-authorization are omitted from most examples. See “vCloud
API REST Requests,” on page 19 for more about how authorization headers are used by the vCloud
API.

n All other request headers required by the vCloud API are included in example requests that are not
fragments of some larger example. Although the examples show these strings using the character case
in which the implementation defines them, header names and values are case-insensitive, and can be
submitted or returned in any character case. Other HTTP headers, such as Date, Content-Length, and
Server, are omitted because they are not relevant to the specifics of any example.

n The XML version and encoding header

<?xml version="1.0" encoding="UTF-8"?>

is included in example requests but omitted from example responses.

n In most examples, object IDs shown in href attribute values appear as small integers, for example
vapp-7 or org/3. In the vCloud API that vCloud Director supports, object IDs are universal unique
identifiers (UUIDs) as defined by RFC 4122, for example vapp-f5e185a4-7c00-41f1-8b91-0e552d538101
or org/89a1a8f9-c518-4f53-960c-950db9e3a1fd. Examples that show Role or Right objects use the
actual UUIDs for roles and rights, which are invariant across installations.

Required Roles and Rights

Where a topic includes an example, it specifies a prerequisite role that normally has the rights required to
run the example. Some examples can be run by roles with fewer rights, or different rights. The prerequisite
role might include more rights than the minimum subset required.

26 VMware, Inc.
Hello vCloud: A Simplified RESTful
Workflow 2
vCloud API clients and vCloud Director servers communicate over HTTPS, exchanging XML
representations of vCloud API objects.

This simplified example of a RESTful workflow includes requests that discover and deploy a particular
vApp, in this case, an FTP server with a connection to the public Internet.

These examples assume that you have access to a catalog that includes a vApp template with certain
characteristics and an organization network that supports connections to the public Internet. The workflow
and examples are flexible, and can accommodate various vApp templates and cloud capabilities.

Prerequisites
If you want to run the Hello vCloud examples, verify that the following conditions are met.

n You have the login credentials of a user with the predefined vApp Author role or another role that has
an equivalent set of rights.

n Your organization contains at least one VDC that has at least one network. For information about
creating VDCs and networks, see Chapter 7, “Managing an Organization,” on page 185.

n Your organization contains a catalog in which at least one vApp template is available. For information
about adding a vApp template to a catalog, see Chapter 4, “Provisioning an Organization,” on page 61.

Procedure
1 Logging In on page 28
To begin using the API, you request the system to create a Session object. In this request, you supply
your credentials in an Authorization header of the form prescribed by the identity provider that your
organization uses. The response includes an authorization token, which you must include in
subsequent requests.

2 Find a Catalog and a VDC on page 30

Before you can deploy a vApp, you must find a vApp template in one of your organization's catalogs
and a VDC in your organization to use for the deployment.

3 Retrieve the Contents of a Catalog on page 31

You can make a GET request to a catalog URL to retrieve a list of vApp templates and media images
referenced by the catalog.

4 Retrieve a Catalog Item on page 32

You can examine the list of items in a catalog to find items of interest based on the values of their name
and type attributes. You must retrieve a catalog item to get a Description and a usable reference to the
underlying object.

VMware, Inc. 27
vCloud API Programming Guide for Service Providers

5 Retrieve Deployment Information From the VDC on page 34

To deploy your template as a vApp, you must specify an organization VDC to deploy it in and an
organization VDC network to connect it to.

6 Deploy the vApp on page 35

To create a vApp from a vApp template, you must bind the template's 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.

7 Get Information About a vApp on page 38

When you instantiate a vApp template, the server returns the URL of the resulting vApp. You can use
this URL with a GET request to retrieve information that you can use to connect to the vApp, modify
its configuration, and operate it.

8 Displaying the Virtual Machine Console on page 41

After a vApp is powered on, you can retrieve a screen ticket from any of its virtual machines. You use
that ticket with the VMware HTML Console SDK to access the virtual machine console from a
browser.

9 Undeploy, Power Off, and Delete the vApp on page 43

After you undeploy a vApp and power it off, you can use an HTTP DELETE request to delete the
vApp object.
10 Log Out on page 44
To log out and terminate a vCloud API session, delete the Session you created when you logged in.

Logging In
To begin using the API, you request the system to create a Session object. In this request, you supply your
credentials in an Authorization header of the form prescribed by the identity provider that your
organization uses. The response includes an authorization token, which you must include in subsequent
requests.

Every version of the vCloud API supported by vCloud Director has a login URL that a client can obtain by
making an unauthenticated GET request to the api/versions URL. See “Example: Retrieve the Login URL
and List of Supported API Versions,” on page 24. Because all other vCloud API requests must be
authenticated, any vCloud API workflow must begin with a login request that creates a session and returns
an authorization token in the value of the x-vcloud-authorization header. The token must be included in
subsequent vCloud API requests.

Prerequisites
Verify that the following conditions are met:

n You know the type of identity provider that your organization uses. See “Create a vCloud API Session,”
on page 47 for more about identity providers, or ask your organization administrator.

n You have the login credentials of a user with the predefined vApp Author role or another role that has
an equivalent set of rights.

n Your organization contains at least one VDC and one network. For more information about setting up
an organization to support the Hello vCloud workflow, see Chapter 7, “Managing an Organization,” on
page 185.

n Your organization contains a catalog in which at least one vApp template is available. For more
information about adding a vApp template to a catalog, see Chapter 4, “Provisioning an Organization,”
on page 61.

28 VMware, Inc.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow

Procedure
1 Make an API versions request to vCloud Director to obtain the vCloud API login URL.

This request has the following form:

GET [Link]

2 POST a request to the login URL to create a login session.

Regardless of the type of identity provider your organization uses, the form of this request is always the
same:

POST [Link]

See “Example: Login Session Request and Response,” on page 29.

3 Examine the response.

A successful request returns an x-vcloud-authorization authorization token, which you must included
in subsequent vCloud API requests.

Example: Login Session Request and Response

To create a session object, you supply your credentials in an Authorization header of the form prescribed by
the identity provider that your organization uses, then POST a request to the vCloud API login URL. This
request does not have a body. All the information required to create a session is included in the
Authorization header. See “Create a vCloud API Session,” on page 47 for examples of this request for all
supported types of identity provider.

The response includes a re-usable x-vcloud-authorization authorization token and a Session element
whose Link elements reference the vCloud API objects to which you have access rights. This example shows
a response for a user named HelloUser who is a member of an organization named ExampleOrg.

Response:

200 OK
x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM=
Content-Type: application/[Link]+xml;version=5.6
...
<Session
xmlns="[Link]
user="HelloUser"
org="ExampleOrg"
... >
<Link
rel="down"
type="application/[Link]+xml"
href="[Link]
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="entityResolver"
type="application/[Link]+xml"
href="[Link] />
</Session>

VMware, Inc. 29
vCloud API Programming Guide for Service Providers

The response code indicates whether the request succeeded, or how it failed.

n If the request is successful, the server returns HTTP response code 200 (OK) and headers that include a
header of the form:

x-vcloud-authorization: token

This header, including the token, must be included in each subsequent vCloud API request.

n If the Authorization header is missing from the request, the server returns HTTP response code 403.

n If the credentials supplied in the Authorization header are invalid, the server returns HTTP response
code 401.

Important The authorization token expires after a configurable interval of client inactivity. The default
interval is 30 minutes. After the token expires, you must log in again to obtain a new token. The system
administrator can change this default.

Find a Catalog and a VDC

Before you can deploy a vApp, you must find a vApp template in one of your organization's catalogs and a
VDC in your organization to use for the deployment.

After you log in, you can make a GET request to your organization's URL to retrieve the XML representation
of the organization. This representation shows the organization's attributes and contents, including links to
its catalogs and VDCs.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Examine the list of organizations to which you have access.

Make a GET request to the URL in the href value of the orgList link, which is present in the response to
all login requests.

GET [Link]

Unless you are a system administrator, the response to this request is an OrgList element containing a
single Org element, which represents your organization.

<OrgList
xmlns="[Link]
type="application/[Link]+xml"
href="[Link]
<Org
type="application/[Link]+xml"
name="ExampleOrg"
href="[Link] />
</OrgList>

2 Retrieve the representation of your organization.

See the request portion of “Example: Retrieve the Contents of an Organization,” on page 31.

3 Examine the response to find the links to the organization's catalogs and VDCs.

See the response portion of “Example: Retrieve the Contents of an Organization,” on page 31.

30 VMware, Inc.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow

Example: Retrieve the Contents of an Organization

This example retrieves the ExampleOrg organization listed in the OrgList element shown in Step 1.

Request:

GET [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<Org
name="ExampleOrg"
type="application/[Link]+xml"
href="[Link]
<Link
rel="down"
type="application/[Link]+xml"
href="[Link]
name="ExampleCatalog" />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link]
name="ExampleVdc01" />
<Link ... />
<Link ... />
<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. This example shows the subset of those items that we reference in the Hello vCloud example:

n A catalog named ExampleCatalog, at URL [Link] where you can

look for vApp templates.

n An organization VDC named ExampleVdc01, at URL [Link] where you

can deploy the vApp.

Retrieve the Contents of a Catalog

You can make a GET request to a catalog URL to retrieve a list of vApp templates and media images
referenced by the catalog.

To use a vApp template or media image listed in a catalog, retrieve the catalog to discover the set of
CatalogItem elements it contains, then make an additional request to retrieve the CatalogItem of interest.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the XML representation of your organization.

Use a request like this one:

GET [Link]

VMware, Inc. 31
vCloud API Programming Guide for Service Providers

2 Examine the response to find the links to the organization's catalogs.

These links have the following form:

<Link
rel="down"
type="application/[Link]+xml"
href="[Link]
name="catalog_name" />

3 Retrieve the contents of the catalog.

Use a GET request of the form shown in the request portion of “Example: Retrieve the Contents of a
Catalog,” on page 32.

Example: Retrieve the Contents of a Catalog

This example retrieves the catalog shown in the response portion of “Example: Retrieve the Contents of an
Organization,” on page 31.

Request:

GET [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<Catalog
xmlns="[Link]
name="ExampleCatalog"
type="application/[Link]+xml"
href="[Link]
<Description>Main Org Catalog</Description>
<CatalogItems>
<CatalogItem
type="application/[Link]+xml"
name="Ubuntu Template with vsftpd"
href="[Link]
<CatalogItem ... />
<CatalogItem ... />
</CatalogItems>
</Catalog>

Retrieve a Catalog Item

You can examine the list of items in a catalog to find items of interest based on the values of their name and
type attributes. You must retrieve a catalog item to get a Description and a usable reference to the
underlying object.

Every vApp template or media image that is 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, the client requires more information. In “Example: Retrieve a Catalog Item,” on
page 33, the client makes a GET request to the URL in the value of the href attribute of a CatalogItem. 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.

32 VMware, Inc.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the representation of a catalog in your organization.

Use a request like this one:

GET [Link]

2 Examine the response to find the CatalogItem elements that the catalog contains.

The value of the name attribute of a CatalogItem element is taken from the name attribute of the
referenced object. You can use it as a preliminary indicator of what the item represents.

3 Retrieve a CatalogItem.

Use a GET request of the form shown in the request portion of “Example: Retrieve a Catalog Item,” on
page 33.

Example: Retrieve a Catalog Item

This example retrieves the CatalogItem shown in the response portion of “Example: Retrieve the Contents of
a Catalog,” on page 32.

Request:

GET [Link]

In addition to the name attribute and Description element, the CatalogItem contains a rel="up" link to the
catalog that contains it, and other links that you can use to manage the CatalogItem.

Response:

200 OK
Content-Type: application/[Link]+xml
...
<CatalogItem
xmlns="[Link]
name="Ubuntu Template with vsftpd"
id="urn:vcloud:catalogitem:221"
href="[Link] ... >
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="remove"
href="[Link] />
<Description>Approved template for public FTP sites</Description>
<Entity

VMware, Inc. 33
vCloud API Programming Guide for Service Providers

href="[Link]
type="application/[Link]+xml"
name="Ubuntu Template with vsftpd"/>
</CatalogItem>

Retrieve Deployment Information From the VDC

To deploy your template as a vApp, you must specify an organization VDC to deploy it in and an
organization VDC network to connect it to.

Instantiation, deployment, and operation of a vApp all take place in the context of an organization VDC.
The XML representation of a VDC object defines that context in detail. For this exercise, you need several
pieces of information from the VDC:

n The URL that a client can use to request an instantiateVAppTemplate operation in the VDC.

n A list of networks in the organization VDC that the vApp can connect to.

“Example: Deployment Information in a VDC,” on page 34 shows this subset of VDC contents.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the representation of your organization.

See the request portion of “Example: Retrieve the Contents of an Organization,” on page 31.

2 Examine the Org response to find the links to the organization's VDCs.

Links to VDCs have the form:

<Link
rel="down"
type="application/[Link]+xml"
href="[Link]
name="VDC_name" />

3 Retrieve the contents of the VDC.

Use a GET request of the form shown in the request portion of “Example: Deployment Information in a
VDC,” on page 34.

Example: Deployment Information in a VDC

This example shows a request to retrieve the XML representation of a VDC. It shows only the subset of the
response that contains deployment information.

Request:

GET [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<Vdc
xmlns="[Link]
name="ExampleVdc01"
type="application/[Link]+xml"

34 VMware, Inc.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow

href="[Link]
...
<Link
rel="add"
type="application/[Link]+xml"
href="[Link] />
...
<AvailableNetworks>
<Network
href="[Link]
type="application/[Link]+xml"
name="Isolated" />
<Network
href="[Link]
type="application/[Link]+xml"
name="Internet" />
</AvailableNetworks>
...
</Vdc>

The information that you need is available in the following elements of the response:

n A Link element that contains an action URL for instantiateVAppTemplate. The rel attribute of this link
has a value of add. It implements an action that adds an object (a vApp) to the VDC.

n A list of AvailableNetworks that includes all the networks in the VDC.

Deploy the vApp

To create a vApp from a vApp template, you must bind the template's 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.

To deploy the vApp, you construct an InstantiateVAppTemplateParams element that specifies a vApp
template to use and a network to connect to, then POST the element to the action/instantiateVAppTemplate
URL of the VDC.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the XML representation of the vApp template.

Make a GET request to the URL provided in the href attribute of the Entity contained by the
CatalogItem that references the template. You can also use the query service to return a list of references
to vApp templates that you can access.

2 Examine the template to find the Vm elements of the virtual machines that it contains.

Look for a NetworkConnection element in the Vm. You need some of the information in that element to
create a vApp network that the virtual machine can connect to.

3 Create an InstantiateVAppTemplateParams element.

See “Example: Deploying a vApp,” on page 36 for guidelines.

4 Make a POST request to the action/instantiateVAppTemplate URL of the VDC.

Supply the InstantiateVAppTemplateParams element as the request body.

VMware, Inc. 35
vCloud API Programming Guide for Service Providers

The server takes the requested action and returns a VApp element. The element has a status attribute value of
0, meaning it is unresolved because the vApp is still being constructed. It also contains a Task element that
tracks the progress of the request.

See the response portion of “Example: Deploying a vApp,” on page 36.

Example: Deploying a vApp

This simple instantiateVAppTemplate request assumes that the vApp template includes one Vm and has no
special requirements other than connecting that Vm to a network. For a look at a more complex instantiation
request, see “Example: Instantiate a vApp Template and Modify Virtual Machine Name, Description, and
Storage Profile,” on page 106. The InstantiateVAppTemplateParams includes the following information:

n A name for the vApp, supplied in the name attribute of the InstantiateVAppTemplateParams element.
This request also provides a description, which is optional but a good practice.

n A reference to a template, obtained from the href attribute of the Entity contained by the CatalogItem
that you retrieved in “Retrieve a Catalog Item,” on page 32 and suppled in the Source element of the
InstantiateVAppTemplateParams.

n Configuration parameters for a vApp network, supplied in the NetworkConfigSection element. This
specification includes the following parameters:
n A name for the network, supplied in the name attribute of the NetworkConfigSection element. The
name you specify for the vApp network must match the value of the network attribute of the
NetworkConnection of the Vm. This example assumes that this NetworkConnection element includes
the following values, which specify that the Vm connects to a network named vAppNetwork:

<NetworkConnectionSection
...
<NetworkConnection
network="vAppNetwork">
...
</NetworkConnection>
</NetworkConnectionSection>

n A reference to the organization VDC network to which the vApp network connects, specified in the
ParentNetwork element. The URL used in this reference is one shown in the AvailableNetworks
element in “Example: Deployment Information in a VDC,” on page 34.

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

For more information about creating networks with the vCloud API, see “About vCloud Director
Networks,” on page 199.

The target of the request is the instantiateVAppTemplate URL of this VDC. See “Example: Deployment
Information in a VDC,” on page 34. Because the operation creates a new vApp object, the HTTP request type
is POST.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<InstantiateVAppTemplateParams
xmlns="[Link]
name="Linux FTP server"
deploy="true"
powerOn="true"
xmlns:xsi="[Link]

36 VMware, Inc.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow

xmlns:ovf="[Link]
<Description>Example FTP Server</Description>
<InstantiationParams>
<NetworkConfigSection>
<ovf:Info>Configuration parameters for logical networks
</ovf:Info>
<NetworkConfig
networkName="vAppNetwork">
<Configuration>
<ParentNetwork
href="[Link] />
<FenceMode>bridged</FenceMode>
</Configuration>
</NetworkConfig>
</NetworkConfigSection>
</InstantiationParams>
<Source
href="[Link] />
</InstantiateVAppTemplateParams>

The response to the instantiation request is a sparsely populated vApp element that includes the following
information:

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

n The name of the vApp, as supplied in the request.

n The vApp URL, shown in the href attribute of the VApp element. You can use this reference to retrieve
information about the vApp.

n 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. The vApp
is the owner of the task.

Response:

201 Created
Content-Type: application/[Link]+xml
...
<VApp
xmlns="[Link]
xmlns:ovf="[Link]
deployed="false"
status="0"
name="Linux FTP server"
type="application/[Link]+xml"
href="[Link]
<Link
rel="up"
type="application/[Link]+xml"
href="[Link]
<Description>Example FTP Server vApp</Description>
<Tasks>
<Task
status="running"
operation="Creating Virtual Application Linux FTP server(7)"
... >
<Owner

VMware, Inc. 37
vCloud API Programming Guide for Service Providers

type="application/[Link]+xml"
name="LinuxFtpServer"
href="[Link] />
</Task>
</Tasks>
</VApp>

Get Information About a vApp

When you instantiate a vApp template, the server returns the URL of the resulting vApp. You can use this
URL with a GET request to retrieve information that you can use to connect to the vApp, modify its
configuration, and operate it.

As other examples have shown, a client can always use an HTTP GET request to the URL in the object's href
attribute to discover the current state of any vCloud API object, including a vApp.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the XML representation of the vApp.

Make a GET request to the URL in the href attribute of the VApp element that is returned when you
create the vApp from the template.

2 Examine the response.

See “Example: Getting Information About the vApp,” on page 38.

Example: Getting Information About the vApp

This response reveals several things about the vApp:

n The vApp is deployed (its deployed attribute is set to true) and powered on (status="4"). See “Object
Creation Status,” on page 443.

n 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: Deploying a vApp,” on page 36. Properties of this
network are included in the NetworkConfigSection of the vApp, although most are not shown here.
Properties of the virtual machine's connection to the network, including its IP address, are shown in the
NetworkConnection of the Vm.

n Action links for all operations except powerOn are present in the VApp element and the Vm element that it
contains. 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 are not applicable to a vApp. Actions such as acquiring a screen ticket or thumbnail, and inserting
or removing media, are meaningful only in the context of a virtual machine. Other actions, like
shutdown and reboot, can be applied to either object. See Chapter 5, “Deploying and Operating vApps
and Virtual Machines,” on page 95.

Request:

GET [Link]

38 VMware, Inc.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow

Response:

200 OK
Content-Type: application/[Link]+xml
...
<VApp
...
deployed="true"
status="4"
name="Linux FTP server"
type="application/[Link]+xml"
href="[Link] ... >
...
<Link
rel="power:reboot"
href="[Link] />
<Link
rel="power:powerOff"
href="[Link] />
<Link
rel="undeploy"
href="[Link] />
<Link
rel="deploy"
href="[Link] />
<Link
rel="power:shutdown"
href="[Link] />
<Link
rel="power:reset"
href="[Link] />
<Link
rel="power:suspend"
href="[Link] />
<Link ... />
...
<Description>Example FTP Server vApp</Description>
<LeaseSettingsSection ... >
...
</LeaseSettingsSection>
<ovf:StartupSection ... >
...
</ovf:StartupSection>
<ovf:NetworkSection ... >
<ovf:Info />
<ovf:Network
ovf:name="vAppNetwork">
<ovf:Description />
</ovf:Network>
</ovf:NetworkSection>
<NetworkConfigSection
href="[Link]
ovf:required="false">
<Link
rel="edit"
type="application/[Link]+xml"

VMware, Inc. 39
vCloud API Programming Guide for Service Providers

href="[Link] />
<ovf:Info>Configuration parameters for vAppNetwork</ovf:Info>
<NetworkConfig
networkName="vAppNetwork">
<Configuration>
<IpScopes>
...
</IpScopes>
<ParentNetwork
type="application/[Link]+xml"
name="Internet"
href="[Link] />
<FenceMode>bridged</FenceMode>
</Configuration>
<IsDeployed>true</IsDeployed>
</NetworkConfig>
</NetworkConfigSection>
<Children>
<Vm
deployed="true"
status="4"
name="ubuntu10-x86"
type="application/[Link]+xml"
href="[Link]
...
<Link
rel="power:reboot"
href="[Link] />
<Link
rel="power:powerOff"
href="[Link] />
<Link
rel="undeploy"
href="[Link] />
<Link
rel="deploy"
href="[Link] />
<Link
rel="power:shutdown"
href="[Link] />
<Link
rel="power:reset"
href="[Link] />
<Link
rel="power:suspend"
href="[Link] />
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="screen:thumbnail"
href="[Link] />
<Link
rel="screen:acquireTicket"

40 VMware, Inc.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow

href="[Link] />
<Link
rel="media:insertMedia"
type="application/[Link]+xml"
href="[Link] />
<Link ... />
...
<Description />
<ovf:VirtualHardwareSection>
...
</ovf:VirtualHardwareSection>
...
<NetworkConnectionSection>
...
<NetworkConnection>
network="vAppNetwork">
<NetworkConnectionIndex>0</NetworkConnectionIndex>
<IpAddress>[Link]</IpAddress>
<IsConnected>true</IsConnected>
<MACAddress>[Link]</MACAddress>
<IpAddressAllocationMode>DHCP</IpAddressAllocationMode>
</NetworkConnection>
</NetworkConnectionSection>
<GuestCustomizationSection>
...
</GuestCustomizationSection>
...
</Vm>
</Children>
</VApp>

Displaying the Virtual Machine Console

After a vApp is powered on, you can retrieve a screen ticket from any of its virtual machines. You use that
ticket with the VMware HTML Console SDK to access the virtual machine console from a browser.

Each Vm element in a vApp includes a link where rel="screen:acquireMksTicket" if the virtual machine it
represents is powered on. You can use that link to retrieve a screen ticket that includes all the information
you need to create a VMware HTML Console to access the virtual machine.

Note A Vm element might also contain a link of the form:

<Link
rel="screen:acquireTicket"
href="[Link] />

This link is provided for compatibility with older systems. The ticket returned by a request to this link is not
compatible with this release of vCloud Director.

Prerequisites
n This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

n Verify that the virtual machine whose console you want to display is powered on.

n Download and unzip the VMware HTML Console SDK version 2.1 or later.

VMware, Inc. 41
vCloud API Programming Guide for Service Providers

Procedure
1 Retrieve the screen ticket.

POST a request to the acquireMksTicket link of the Vm.

Request:

POST [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<MksTicket
xmlns="[Link]
xmlns:xsi="[Link]
... >
<Host>[Link]</Host>
<Vmx>vmfs/volumes/5331e00b-467faf9c-5561-d48564677c70/example-vm (19115346-c01c-4c9b-a21f-
d487865a9f98)/example-vm
(19115346-c01c-4c9b-a21f-d487865a9f98).vmx</Vmx>
<Ticket>ticket-string</Ticket>
<Port>902</Port>
</MksTicket>

2 Construct an HTML Script element from the information in the MksTicket response.

See “Example: Using an MksTicket in a VMware HTML Console SDK Script,” on page 42.

3 Use the Script element with the VMware HTML Console SDK .

Replace the final script element in the Quick Start example shown in the VMware HTML Console SDK
Release Notes (release number 2.1, build number 4504321) with the script you constructed. Replace the
ticket-string with one from a freshly-retrieved MksTicket, then open the example in a browser.

Example: Using an MksTicket in a VMware HTML Console SDK Script

This HTML fragment shows a Script element derived from an example in the VMware HTML Console SDK
Release Notes. In this example:
n The contents of the Vmx element in the MksTicket is quoted and passed as the first parameter to the as
SDK createWMKS method. You must also pass the boolean option enableUint8Utf8 to this method
specifying a value of true.

n The URL passed as a parameter to the SDK [Link] method includes the following information
from the MksTicket.
n console-ip-address is the IP address of the virtual machine, returned in the Host element of the
MksTicket.

n console-port is the vCloud Director console proxy port (defaults to 443).

n Mks-port is the value returned in the Port element of the MksTicket

n ticket is the string returned in the Ticket element of the MksTicket. The ticket-string is valid for 30
seconds from the time you retrieve the MksTicket.

<script>
var wmks = [Link]("wmksContainer",{VCDProxyHandshakeVmxPath:
"vmfs/volumes/5331e00b-467faf9c-5561-d48564677c70/example-vm (19115346-c01c-4c9b-a21f-
d487865a9f98)/example-vm
(19115346-c01c-4c9b-a21f-d487865a9f98).[Link]", enableUint8Utf8:true})
.register([Link].CONNECTION_STATE_CHANGE, function(event,data){

42 VMware, Inc.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow

if([Link] == [Link]){
[Link]("connection state change : connected");}
});
[Link]("[Link]
</script>

Undeploy, Power Off, and Delete the vApp

After you undeploy a vApp and power it off, you can use an HTTP DELETE request to delete the vApp
object.

A deployed vApp has a link that you can use with a POST request to undeploy the vApp and take a power
action such as powering it off or suspending it. A powered-off vApp has a link that you can use with a
DELETE request to remove the vApp.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the XML representation of the vApp.
Make a GET request to the URL in the href attribute of the VApp element that was returned when you
created the vApp from the template. See “Get Information About a vApp,” on page 38.

2 Undeploy the vApp, and specify that it should also be powered off.

Make a POST request to the vApp action/undeploy link, which has the following form:

<Link
rel="undeploy"
href="[Link]

In the request body, specify that the undeployment include powering off the vApp. See
“Example: Undeploy, Power Off, and Delete a vApp,” on page 43.

3 Retrieve the XML representation of the vApp again.

After it is powered off and undeployed, the vApp includes a rel="remove" link of the following form:

<Link
rel="remove"
href="[Link]

4 Remove the vApp.

Make a DELETE request to the vApp's rel="remove" link, as shown in the request portion of
“Example: Undeploy, Power Off, and Delete a vApp,” on page 43.

The server starts a task to manage the events that lead up to the removal of the vApp, and returns a Task
element that you can use to track the progress of the task.

Example: Undeploy, Power Off, and Delete a vApp

You can use the undeploy request body, an UndeployVAppParams element, to specify an UndeployPowerAction
element. This example specifies an UndeployPowerAction of powerOff. Even though powerOff is the default
UndeployPowerAction, It appears here for completeness.

VMware, Inc. 43
vCloud API Programming Guide for Service Providers

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<UndeployVAppParams
xmlns="[Link]
<UndeployPowerAction>powerOff</UndeployPowerAction>
</UndeployVAppParams>

Response:

202 Accepted
...
<Task
xmlns="[Link]
...
operation="Undeploying Virtual Application Linux FTP server (7)"
... >
</Task>

After the vApp is undeployed and powered off, its representation includes a link where rel="remove". Make
a DELETE request to this link to remove the vApp.

Request:

DELETE [Link]

Response:

202 Accepted
...
<Task
...
operation="Deleting Virtual Application Linux FTP server (7)"
... >
</Task>

Note You can force deletion of a vApp that is powered on, deployed, or both by appending a force=true
query string to the vApp href and using that URL with a DELETE request, as shown here:

DELETE [Link]

Log Out
To log out and terminate a vCloud API session, delete the Session you created when you logged in.

The logout request, like all other authenticated requests, must include the authorization header, as shown in
“Example: Logging Out,” on page 44.

Prerequisites
Verify that you are logged in.

Procedure
u Make a DELETE request specifying the href of the current Session object.

Example: Logging Out

This example deletes the current user's Session, which logs the user out.

44 VMware, Inc.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow

Request:

DELETE [Link]
x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM=

Response:

204 No Content

VMware, Inc. 45
vCloud API Programming Guide for Service Providers

46 VMware, Inc.
Exploring a Cloud 3
You can use HTTP GET requests to browse containers such as organizations, catalogs, and VDCs in a cloud.

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 process is sometimes called
serial discovery, because the contents of one response provides links to locations where you can look for
more information. The hierarchical structure of vCloud API container objects lends itself to graphical
representation as a folder hierarchy or tree view of vCloud API objects, and enables clients to use the same
set of objects and operations to implement a breadth-first or depth-first approach to browsing.

The list of entry points from which you can begin browsing is contained in the Session element that is
returned in response to a successful login. The contents of this list is based on your role and privileges.

This chapter includes the following topics:

n “Create a vCloud API Session,” on page 47

n “Retrieve a List of Organizations Accessible to You,” on page 54

n “Retrieve an Administrative View of a Cloud,” on page 56

n “Retrieve a List of vSphere Platform Operations and Objects for a Cloud,” on page 58

Create a vCloud API Session

The vCloud API login mechanism authenticates a user and creates a Session object that contains the URLs
from which that user can begin browsing objects in an organization. Users must submit their credentials in
the form required by the identity provider that their organization specifies.

The vCloud API does not have a login request. To begin using the API, you request the system to create a
Session object, supplying your credentials in an Authorization header of the form prescribed by the identity
provider that your organization uses. The response includes a re-usable authorization token and a Session
element whose Link elements reference the vCloud API objects to which you have access rights.
vCloud Director supports several forms of authentication to the vCloud API.
n OAuth authentication, as defined in RFC 6749 ([Link] Users defined in an
OAuth identity provider must acquire an OAuth token from that identity provider and include it in the
request to create a vCloud API Session.

n SAML (Security Assertion Markup Language) authentication, as defined in RFC 6595

([Link] Users defined in a SAML identity provider must acquire and
process a security assertion from that identity provider and include the processed assertion and other
attributes in the request to create a vCloud API Session.

VMware, Inc. 47
vCloud API Programming Guide for Service Providers

n Basic HTTP authentication, as specified in RFC 2617 ([Link] LDAP users

and local users are defined by the vCloud Director integrated identity provider, and must include
credentials in the form required by Basic HTTP authentication in the request to create a vCloud API
Session.

All organizations are created with implicit support for the vCloud Director integrated identity provider.
Organizations can be updated to add support for a SAML identity provider.

A Session object can be deleted by its owner or an administrator. After your Session expires or is deleted,
you are not authenticated.

A Session object expires after a configurable interval of client inactivity. To change the length of this client
inactivity timeout, a system administrator can change the value of SessionTimeoutMinutes in the system's
GeneralSettings. See “Retrieve or Update System Settings,” on page 268.

All requests to create a login session include a similar set of steps.

Procedure
1 Make an API versions request to retrieve the list of supported API versions and the login URL for each
version.

The request has this form:

GET [Link]

You do not need to be authenticated to make a versions request.

2 POST a request to the login URL, supplying your credentials in the request's Authorization header.

These requests have the following form:

POST [Link]
Authorization: auth-type credentials
Accept: application/*;version=api-version

The value of auth-type specifies the authentication protocol you are using. Each authentication protocol
has its own requirements for credentials and other attributes.

Basic Specifies Basic HTTP authentication. Requires your user name,

organization name, and password in a MIME Base64 encoding.

Bearer Specifies OAuth authentication. Requires an OAuth token and your

organization name.

Sign Specifies SAML authentication. Requires a compressed, encoded SAML

assertion and other attributes.

3 Examine the response to retrieve the authorization token and links to objects that you have rights to
access.

A successful request returns a Session element, which includes an x-vcloud-authorization header. You
must include the x-vcloud-authorization header in each subsequent vCloud API request.

Create a Session Using OAuth Authentication

Users defined in an organization that specifies an OAuth identity provider must acquire an OAuth token
from the identity provider and include it in the request to create a Session.

Prerequisites
n Verify that you know the API login URL. See “Example: Retrieve the Login URL and List of Supported
API Versions,” on page 24

48 VMware, Inc.
Chapter 3 Exploring a Cloud

n Verify that you are logging in as a user whose identity is managed by the OAuth identity provider
defined by your organization.

Procedure
1 Acquire the OAuth token from your identity provider.
2 Use the login URL to authenticate to the vCloud API.

POST a request to this URL. The request must include an Authorization header that specifies Bearer as
the authorization method, includes an OAuth token retrieved from your identity provider, and has the
following attributes:

Table 3‑1. OAuth Authorization Header Attributes and Values

Attribute Name Attribute Value

org The name of your vCloud Director organization.

See “Example: OAuth Login Request and Response,” on page 49.

3 Examine the response.

The response code indicates whether the request succeeded, or how it failed.
n If the request is successful, the server returns HTTP response code 200 (OK) and headers that
include a header of the form:

x-vcloud-authorization: token

This header, including the token, must be included in each subsequent vCloud API request.

n If the Authorization header is missing from the request, the server returns HTTP response code
403.

n If the credentials supplied in the Authorization header are invalid, the server returns HTTP
response code 401.

A valid request returns a Session element. See “Example: OAuth Login Request and Response,” on page 49

Example: OAuth Login Request and Response

This example shows an OAuth login request and response for a user logging in to the Finance organization
of a cloud whose API login URL is [Link]

The following credentials are required:

OAuth-token The token returned by your OAuth identity provider.

org The name of your organization.

Request:

POST [Link]
Authorization: Bearer OAuth-token; org=Finance
Accept: application/*;version=9.0

Response:

200 OK
x-vcloud-authorization: cn9uYmd...
...
<Session
xmlns="[Link]
userUrn="urn:vcloud:user:fe50b0b5-..."
user="bob"
org="Finance"

VMware, Inc. 49
vCloud API Programming Guide for Service Providers

... >
<Link
rel="down"
type="application/[Link]+xml"
name="System"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="entityResolver"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down:extensibility"
type="application/[Link]+xml"
href="[Link] />
</Session>

The response includes the re-usable x-vcloud-authorization header and these Link types:

org A link to your organization. See “Retrieve a List of Organizations Accessible

to You,” on page 54.

queryList A link to the set of typed queries the user can run. See Chapter 10, “Using the
Query Service,” on page 365.

entity A link to the entity resolver. See “Retrieve an Object as an Entity,” on

page 444.

extensibility A link to the extensibility framework entry point. See “vCloud Director
Extension Services,” on page 409.

Create a Session Using SAML Authentication

Users defined in an organization that specifies a SAML identity provider must acquire and process a
security assertion from that identity provider and include the processed assertion and other attributes in the
request to create a vCloud API Session.
The vCloud API login mechanism supports SAML authentication using two types of security assertions:

n Bearer assertions, which make no guarantees about message integrity and claimed client identity.

n Holder-of-key assertions, which guarantee subject identity by including a signature generated with the
subject's private key.

Prerequisites
n Verify that you know the API login URL. See “Example: Retrieve the Login URL and List of Supported
API Versions,” on page 24

n Verify that you are logging in as a user whose identity is managed by the SAML identity provider
defined by your organization.

Procedure
1 Acquire the SAML assertion from your organization's identity provider.

2 Compress the assertion using GZIP.

50 VMware, Inc.
Chapter 3 Exploring a Cloud

3 Encode the compressed assertion using a MIME Base64 encoding, as specified in RFC 1421.

4 Use the login URL to authenticate to the vCloud API.

POST a request to this URL. The request must include an Authorization header that specifies Sign as
the authorization method and has the following attributes:

Table 3‑2. SAML Authorization Header Attributes and Values

Attribute Name Attribute Value

token The compressed, encoded identity assertion from your

SAML identity provider.

signature Base64 encoded signature of the token XML (the

uncompressed identity assertion from your SAML
identity provider) generated using the client's private
key. Required when using holder-of-key subject
confirmation.

signature_alg The algorithm used to generate the signature,

expressed as one of the values listed in
[Link]
curity/[Link]#Signature. Required if
signature is present.

org The name of your vCloud Director organization.

Defaults to org="system" if not specified.

See “Example: Create a Login Session Using a SAML Identity Provider,” on page 51.

5 Examine the response.

The response code indicates whether the request succeeded, or how it failed.

n If the request is successful, the server returns HTTP response code 200 (OK) and headers that
include a header of the form:

x-vcloud-authorization: token

This header, including the token, must be included in each subsequent vCloud API request.

n If the Authorization header is missing from the request, the server returns HTTP response code
403.

n If the credentials supplied in the Authorization header are invalid, the server returns HTTP
response code 401.

A valid request returns a Session element. See “Example: Create a Login Session Using a SAML Identity
Provider,” on page 51

Example: Create a Login Session Using a SAML Identity Provider

This example shows a SAML login request and response for a user logging in to the Finance organization of
a cloud whose API login URL is [Link] This example shows two
varieties of the request.

Request (bearer token):

POST [Link]
Authorization: Sign token="compressed-encoded-credentials",
org="Finance"
Accept: application/*;version=9.0

When using a SAML assertion that provides holder-of-key (HOK) subject confirmation, the request header
must include signature and signature_alg attributes, as shown in this example, which assumes a signature
created with a SHA encoding and RSA encryption algorithms:

VMware, Inc. 51
vCloud API Programming Guide for Service Providers

Request (holder-of-key token):

POST [Link]
Authorization: Sign token="compressed-encoded-credentials",
org="Finance",
signature="encoded-signature"
signature_alg="SHA1withRSA"
Accept: application/*;version=9.0

The response is the same in both cases.

Response:

200 OK
x-vcloud-authorization: cn9uYmd...
...
<Session
xmlns="[Link]
userUrn="urn:vcloud:user:fe50b0b5-..."
user="bob"
org="Finance"
... >
<Link
rel="down"
type="application/[Link]+xml"
name="System"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="entityResolver"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down:extensibility"
type="application/[Link]+xml"
href="[Link] />
</Session>

The response includes the re-usable x-vcloud-authorization header and these Link types:

org A link to your organization. See “Retrieve a List of Organizations Accessible

to You,” on page 54.

queryList A link to the set of typed queries the user can run. See Chapter 10, “Using the
Query Service,” on page 365.

entity A link to the entity resolver. See “Retrieve an Object as an Entity,” on

page 444.

extensibility A link to the extensibility framework entry point. See “vCloud Director
Extension Services,” on page 409.

52 VMware, Inc.
Chapter 3 Exploring a Cloud

Create a Session Using Basic Authentication

LDAP users and local users are defined by the vCloud Director integrated identity provider, and must
include credentials in the form required by Basic HTTP authentication when making a the request to create
a vCloud API Session.

Prerequisites
n Verify that you know the API login URL. See “Example: Retrieve the Login URL and List of Supported
API Versions,” on page 24.

n Verify that you are logging in as a user whose identity is managed by the vCloud Director integrated
identity provider.

Procedure
1 Use the login URL to authenticate to the vCloud API.

POST a request to this URL. The request must include your username, organization name, and
password in a MIME Base64 encoding. See “Example: Create a Login Session Using the Integrated
Identity Provider,” on page 53.

2 Examine the response.

The response code indicates whether the request succeeded, or how it failed.

n If the request is successful, the server returns HTTP response code 200 (OK) and headers that
include a header of the form:

x-vcloud-authorization: token

This header, including the token, must be included in each subsequent vCloud API request.

n If the Authorization header is missing from the request, the server returns HTTP response code
403.

n If the credentials supplied in the Authorization header are invalid, the server returns HTTP
response code 401.

A valid request returns a Session element. See “Example: Create a Login Session Using the Integrated
Identity Provider,” on page 53.

Example: Create a Login Session Using the Integrated Identity Provider

A request to create a login session using the Integrated Identity provider must supply the user's credentials
in the following form:

user@organization:password

n user is the user's login name.

n organization is the name of the user's organization.

n password is the user's password.

These credentials must be supplied in a MIME Base64 encoding, as specified in RFC 1421.

This example shows a Basic HTTP authentication login request and response for a user logging in to the
Finance organization of a cloud whose API login URL is [Link]

Request:

POST [Link]
Authorization: Basic encoded-credentials
Accept: application/*;version=9.0

VMware, Inc. 53
vCloud API Programming Guide for Service Providers

Response:

200 OK
x-vcloud-authorization: cn9uYmd...
...
<Session
xmlns="[Link]
userUrn="urn:vcloud:user:fe50b0b5-..."
user="bob"
org="Finance"
... >
<Link
rel="down"
type="application/[Link]+xml"
name="System"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="entityResolver"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down:extensibility"
type="application/[Link]+xml"
href="[Link] />
</Session>

The response includes the re-usable x-vcloud-authorization header and these Link types:

org A link to your organization. See “Retrieve a List of Organizations Accessible

to You,” on page 54.

queryList A link to the set of typed queries the user can run. See Chapter 10, “Using the
Query Service,” on page 365.

entity A link to the entity resolver. See “Retrieve an Object as an Entity,” on

page 444.

extensibility A link to the extensibility framework entry point. See “vCloud Director
Extension Services,” on page 409.

Retrieve a List of Organizations Accessible to You

A successful login request returns a Session element, which contains Link elements that reference the
organizations that you are permitted to access.

Every authenticated user has an associated Session object that contains one or more Link elements. The set
of Link elements in your Session is based on your role and privileges. Each of these elements includes a
URL that you can use with a GET request to explore a subset of objects in the cloud.

All Session elements include a link that you can use to retrieve an OrgList element. Unless you are the
system administrator, this list includes just the organization to which you logged in. For a system
administrator, the list includes all organizations in the cloud.

54 VMware, Inc.
Chapter 3 Exploring a Cloud

Prerequisites
Create a login session. See “Create a Session Using Basic Authentication,” on page 53.

Procedure
1 Retrieve the XML representation of your Session object.

Use a request like this one:

GET [Link]

2 Examine the contents of the Session element to locate the link to the organization list.

This link has the following form:

<Link
rel="down"
type="application/[Link]+xml"
href="[Link]

3 Retrieve the list of organizations by making a GET request to the href value of the Link.

See “Example: Retrieve an Organization List,” on page 55.

Example: Retrieve an Organization List

Request:

GET [Link]

The request returns an OrgList element similar to the one shown here. Additional Org elements are returned
only when a system administrator makes the request.

Response:

200 OK
Content-Type: application/[Link]+xml
...
<OrgList
xmlns="[Link]
type="application/[Link]+xml"
href="[Link]
<Org
type="application/[Link]+xml"
name="ExampleOrg"
href="[Link] />
<Org ... />
<Org ... />
</OrgList>

VMware, Inc. 55
vCloud API Programming Guide for Service Providers

Retrieve an Administrative View of a Cloud

A successful login by an organization or system administrator returns a Session element that contains a link
that you can use to retrieve a VCloud element. The VCloud element provides access to a cloud-wide
namespace of objects that an organization administrator can view and, in most cases, modify.

The primary administrative objects in a cloud include organizations, provider VDCs, rights, roles, and
external networks. Each object type is represented in a VCloud element by zero or more references. The
vCloud API defines several objects that are used only in administrative operations. Some, like User, Group,
and Role, are unique to administrative operations. Others extend common vCloud API objects to add
elements and attributes that only administrators can view or modify. An AdminOrg, for example, provides an
administrative view of an Org, and an AdminVdc does the same thing for a Vdc.

A system administrator can obtain more information about any of these objects by making a GET request to
its URL, which is the value of its href attribute.

The vCloud element includes links that enable a system administrator to add organizations and roles.
Subordinate objects such as users, catalogs, and VDCs are contained by individual organizations and not
listed at this level.

Prerequisites
Use the credentials of an organization administrator or system administrator to create a login session. See
“Create a Session Using Basic Authentication,” on page 53.

Procedure
1 Retrieve the XML representation of your Session object.

Use a request like this one:

GET [Link]

2 Examine the contents of the Session element to locate the link to the VCloud object.

This link has the following form:

<Link
rel="down"
type="application/[Link]+xml"
href="[Link]

3 Retrieve the VCloud element by making a GET request to the href value of the Link described in Step 2.

See “Example: Retrieve an Administrative View of a Cloud,” on page 56

Example: Retrieve an Administrative View of a Cloud

Request:

GET [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<VCloud
xmlns="[Link]
name="vCloud"
href="[Link]
<Link

56 VMware, Inc.
Chapter 3 Exploring a Cloud

rel="add"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="add"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
name="System"
href="[Link] />
<Link ... />
...
<Description>Example Corporation’s vCloud</Description>
<OrganizationReferences>
<OrganizationReference
type="application/[Link]+xml"
name="Engineering"
href="[Link]
<OrganizationReference
type="application/[Link]+xml"
name="Engineering"
href="[Link]
<OrganizationReference ... />
...
</OrganizationReferences>
<ProviderVdcReferences>
<ProviderVdcReference
type="application/[Link]+xml"
name="Main Provider"
href="[Link] />
<ProviderVdcReference ... />
...
</ProviderVdcReferences>
<RightReferences>
<RightReference
href="[Link]
name="Catalog: Add vApp from My Cloud"
type="application/[Link]+xml"/>
<RightReference
href="[Link]
name="Catalog: Change Owner"
type="application/[Link]+xml"/>
...
<RightReference
href="[Link]
name="VDC Template: View"
type="application/[Link]+xml"/>
</RightReferences>
<RoleReferences>
<RoleReference
href="[Link]
name="System Administrator"
type="application/[Link]+xml"/>

VMware, Inc. 57
vCloud API Programming Guide for Service Providers

...
</RoleReferences>
<Networks>
<Network
type="application/[Link]+xml"
name="ExternalNetwork-VC1"
href="[Link] />
<Network
type="application/[Link]+xml"
name="ExternalNetwork-VC2"
href="[Link] />
</Networks>
</VCloud>

Retrieve a List of vSphere Platform Operations and Objects for a

Cloud
A successful login by a system administrator returns a Session element that contains a link that you can use
to retrieve a VMWExtension element.

Every vCloud Director installation depends on vSphere platform resources such as vCenter servers and
hosts, vShield Manager, portgroups, virtual switches, and so on. The VMWExtension element provides access
to a cloud-wide namespace of vSphere platform objects that are registered for use by the system, and links
that allow you to add vSphere servers and related resources to your cloud. Objects in the admin/extension
XML namespace provide a system administrator with programmatic access to these resources.

Prerequisites
Use the credentials of a system administrator to create a login session. See “Create a Session Using Basic
Authentication,” on page 53.

Procedure
1 Retrieve the XML representation of your Session object.

Use a request like this one:

GET [Link]

2 Examine the contents of the Session element to locate the link to the VMWExtension object.
This link has the following form:

<Link
rel="down"
type="application/[Link]+xml"
href="[Link]

3 Retrieve the list of organizations by making a GET request to the href value of the Link described in
Step 2.

The request returns a VMWExtension element, as shown in “Example: Retrieve a List of vSphere Platform
Operations and Objects for a Cloud,” on page 58.

Example: Retrieve a List of vSphere Platform Operations and Objects for a

Cloud
Request:

GET [Link]

58 VMware, Inc.
Chapter 3 Exploring a Cloud

The response is a VMWExtension element containing a number of Link elements. This example shows only a
subset of VMWExtension contents.

Response:

200 OK
Content-Type: application/[Link]+xml
...
<vmext:VMWExtension
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
type="application/[Link]+xml">
<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link ... />
...
<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
</vmext:VMWExtension>

VMware, Inc. 59
vCloud API Programming Guide for Service Providers

60 VMware, Inc.
Provisioning an Organization 4
The vCloud API provides several ways for you to make vApp templates, vApps, media images, and
independent disks available to users in a vCloud Director organization.

The vCloud API allows you to upload and download OVF packages and ISO-format media images.
Operations are characterized as uploads when they transfer content from a vCloud API client system to a
target catalog in a vCloud Director organization, and as downloads when a vCloud API client requests the
transfer of content from vCloud Director. A POST request initiates an upload, and a GET request initiates a
download. The vCloud Director transfer service facilitates uploads and downloads and provides temporary
storage for files. Uploaded vApp templates and media images are made available as catalog items in the
target catalog.

In addition to uploading, you can use the following operations to provision an organization with vApp
templates, vApps, and media images:

Cloning The vCloud API cloneVApp operation creates a copy of a vApp in a specified
VDC. You can specify whether to delete the source vApp after the operation
completes. Deleting the source vApp after cloning it moves or renames it.

Capturing The vCloud API captureVApp operation creates a vApp template from a
vApp and places the template in a specified catalog.

Importing A system administrator can import a virtual machine from a vCenter server
that is registered to the cloud. You can import the virtual machine as a vApp
or as a vApp template. You can add an imported template to a catalog or
download it as an OVF package.

Adopting In the default configuration, the system automatically discovers vCenter

VMs contained by in any resource pool that backs an organization VDC. A
system administrator can also can configure an organization VDC to adopt
existing vCenter resource pools and the VMs they contain. The system
administrator can make these discovered VMs available for adoption by
organization members.

Subscribing Organizations that have the appropriate permissions can create catalogs with
external subscriptions. These contents of these catalogs are downloaded from
a catalog hosted on another instance of vCloud Director, or any Web site that
implements the VMware Content Subscription Protocol. See “Create a
Catalog With an External Subscription,” on page 225.

You can also create independent disks that are contained by an organization VDC and can be connected to
any virtual machine in that VDC.

VMware, Inc. 61
vCloud API Programming Guide for Service Providers

This chapter includes the following topics:

n “Upload an OVF Package to Create a vApp Template,” on page 62

n “Download a vApp or vApp Template as OVF,” on page 72

n “Upload a Media Image,” on page 76

n “Download a Media Image,” on page 78

n “Capturing and Importing vApps,” on page 79

n “Discovering and Adopting vApps,” on page 80

n “Managing Catalog Items,” on page 81

n “Creating and Using Independent Disks,” on page 85

n “View or Change the Owner of an Object,” on page 90

n “Controlling Access to vApps and Catalogs,” on page 91

Upload an OVF Package to Create a vApp Template

A vCloud API client that has access to an OVF package can use a standard workflow to upload the package
and create a vApp template.

The initial configuration of a vApp is established in the OVF package on which its source template is based.
In the vCloud API, vApp templates are based OVF 1.0, an open standard format. For more information
about OVF and how the vCloud API uses it, see “About OVF,” on page 95.

An OVF package includes several 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 certificate You can use this file to certify the authenticity of the package.

An optional manifest Contains a SHA-1 digest of each of the files in the package.

Upload Workflow
The upload workflow for OVF packages uses a combination of vCloud API requests and standard HTTP file
transfer requests.

1 The client makes a POST request to the catalog chosen to hold the template derived form the uploaded
OVF. The request body specifies a name, description, and other parameters used when creating the
template.

2 The server returns a CatalogItem that references a vApp template.

3 The client makes a GET request to the entity reference in the CatalogItem to retrieve the VAppTemplate,
which includes an upload URL for the OVF descriptor. Because the template is not yet complete, the
VAppTemplate element has status="0".

4 The client makes a PUT request to the upload URL and supplies the OVF descriptor in the request body.

5 The server processes the descriptor and modifies the vAppTemplate to include an upload URL for each
file listed in the References section of the descriptor. While the server is modifying the vAppTemplate,
the client makes periodic requests for it and examines the response for additional upload URLs. When
the response contains additional upload URLs that were not present in the initial response, template
construction is complete.

62 VMware, Inc.
Chapter 4 Provisioning an Organization

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

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

Both monolithic and ranged, or chunked, PUT requests are supported. After starting an upload, a client can
make periodic requests to assess its progress. After all of the files are uploaded (and validated if a manifest
is present), the server processes them and updates the vApp template. When processing is complete, the
server sets the value of the template's status attribute to 8, indicating that it 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 “Object Creation Status,” on
page 443.

Note If you have an OVF package that you want to deploy immediately as a vApp, without creating a
vApp template and corresponding catalog item, make an instantiateOvf request. See “Create a vApp From
an OVF Package,” on page 120.

Restrictions on Uploaded Content

The vCloud Director transfer service imposes the following restrictions on uploaded OVF content:

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

n Upload or download of packages that include OVF ExtraConfig elements typically require the user to
have additional rights specific to the ExtraConfig key attribute. See“Using Metadata to Control Virtual
Machine Placement,” on page 129.

n You cannot upload a compressed OVF package.

n 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 that VirtualSystem in the vAppTemplate
that the upload creates is rewritten as the first 13 characters of the ovf:id attribute followed by three
digits. For example, NewVirtualMachine1 and NewVirtualMachine2 become NewVirtualMac001 and
NewVirtualMac002.

1 Initiating the OVF Upload on page 64

To initiate the OVF upload, a client makes a POST request to an action/upload link in the target
catalog. The type of this link is application/[Link]+xml. The
request body is an UploadVAppTemplateParams element.

2 Retrieving the Upload URL for the OVF Descriptor on page 66

After the vApp template and corresponding catalog item have been created, you must retrieve the
template to get the upload URL for the OVF descriptor.

3 Uploading the OVF Descriptor on page 67

You upload the OVF descriptor by making a PUT request to the upload URL created for it in the
VAppTemplate. The request body is the descriptor's Envelope element. If the request is valid, the server
responds with a 200 OK status.

4 Retrieving Additional Upload URLs on page 68

After an OVF descriptor is uploaded, the server validates it and, if it is valid, updates the
corresponding template with upload URLs for each of the files referenced in the descriptor. You must
retrieve the template to see these URLs.

5 Uploading Referenced Files on page 70

You can use a PUT request to upload each file that the vApp template references.

VMware, Inc. 63
vCloud API Programming Guide for Service Providers

Initiating the OVF Upload

To initiate the OVF upload, a client makes a POST request to an action/upload link in the target catalog. The
type of this link is application/[Link]+xml. The request body is an
UploadVAppTemplateParams element.

The first step in uploading an OVF package is to request vCloud Director to create a catalog item in the
target catalog and a corresponding vAppTemplate object to represent the template that will be constructed
from the upload.

Prerequisites
Verify that the following are true:

n You have an OVF package to upload.

n You are logged in as a user who has permission to upload OVF packages and create vApp templates.

n You know the URL of the target catalog that will receive the upload. Retrieve the XML representation of
your organization to see a list of the catalogs that it contains.

Procedure
1 Find the action/upload link for vApp templates in the target catalog.
Retrieve the XML representation of the catalog using a request like the one shown in the request portion
of “Example: Deployment Information in a VDC,” on page 34. The response contains an action/upload
link, which has the following form:

<Link
rel="add"
type="application/[Link]+xml"
href="[Link] />

2 Create an UploadVAppTemplateParams element that specifies the parameters for the vApp template that
this request creates.

See the request portion of “Example: Initiating the Upload,” on page 65.

3 (Optional) If the OVF package includes a manifest, include a manifestRequired="true" attribute in the
UploadVAppTemplateParams element.

Some OVF packages include a manifest document, which provides a checksum for each file in the
package. When the UploadVAppTemplateParams element includes a manifestRequired="true" attribute,
the set of File elements returned after you upload the OVF descriptor includes one for the manifest
itself.

4 Make an HTTP POST request to the upload link that you retrieved in Step 1, supplying the
UploadVAppTemplateParams element in the request body.

See the request portion of “Example: Initiating the Upload,” on page 65.

5 Examine the response.

The response, a CatalogITem element, contains an Entity element that contains a reference to the vApp
template that will be constructed from the uploaded OVF. See the response portion of
“Example: Initiating the Upload,” on page 65.

The server creates a VAppTemplate object and a corresponding CatalogItem in the target catalog, and returns
an XML representation of the CatalogItem. See the response portion of “Example: Initiating the Upload,” on
page 65.

64 VMware, Inc.
Chapter 4 Provisioning an Organization

Example: Initiating the Upload

This example assumes an OVF package that has no manifest.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<UploadVAppTemplateParams
name="Ubuntu Template"
xmlns="[Link]
xmlns:ovf="[Link]
<Description>Ubuntu vApp Template</Description>
</UploadVAppTemplateParams>

Response:

201 Created
Content-Type: application/[Link]+xml
...
<CatalogItem
xmlns="[Link]
name="Ubuntu Template"
id="urn:vcloud:catalogitem:221"
href="[Link] ... >
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="remove"
href="[Link] />
<Description>Approved template for public FTP sites</Description>
<Entity
href="[Link]
type="application/[Link]+xml"
name="Ubuntu vApp Template"/>
</CatalogItem>

VMware, Inc. 65
vCloud API Programming Guide for Service Providers

Retrieving the Upload URL for the OVF Descriptor

After the vApp template and corresponding catalog item have been created, you must retrieve the template
to get the upload URL for the OVF descriptor.

Procedure
1 Examine the CatalogItem returned by the upload request to find the reference to the new vApp
template.

The reference is the value of the href attribute of the Entity element, as shown here.

<Entity
href="[Link]
type="application/[Link]+xml"
name="Ubuntu vApp Template" />

2 Retrieve the VAppTemplate.

See the request portion of “Example: OVF Descriptor Upload URL in a vAppTemplate,” on page 66.

3 Examine the template to find the upload URL for the OVF descriptor.

These URLs are contained in Link elements where rel="upload:default".

Example: OVF Descriptor Upload URL in a vAppTemplate

This request uses the vApp template URL referenced in the Entity element shown in the response portion of
“Example: Initiating the Upload,” on page 65.

Request:

GET [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<VAppTemplate
xmlns="[Link]
xmlns:ovf="[Link]
ovfDescriptorUploaded="true"
goldMaster="false"
status="0"
name="Ubuntu Template"
id="urn:vcloud:vapptemplate:111"
href="[Link]
type="application/[Link]+xml">
<Link
rel="up"
type="application/[Link]+xml"
href="[Link]
<Link
rel="remove"
href="[Link] />
<Description>Ubuntu vApp Template</Description>
<Files>
<File
name="[Link]"

66 VMware, Inc.
Chapter 4 Provisioning an Organization

bytesTransferred="0">
<Link
rel="upload:default"
href="[Link] />
</File>
</Files>
<Owner>
...
</Owner>
<Children />
<LeaseSettingsSection>
...
</LeaseSettingsSection>
<CustomizationSection>
...
</CustomizationSection>
</VAppTemplate>

The response body includes the following attributes:

n An ovfDescriptorUploaded attribute with a value of false, indicating that the OVF descriptor file is not
uploaded.

n A status attribute with a value of 0, indicating that the file references in the descriptor are not
uploaded. (A VAppTemplate with a status of 0 is said to be unresolved.)

n A goldMaster attribute, initially set to false.

n An id attribute. See “Objects, References, and Representations,” on page 12.

The response body also includes a File element with an upload URL (rel="upload:default") for the OVF
descriptor. The server creates the name attribute of this File element, which specifies a container that the
server creates to receive the contents of the descriptor. The name attribute has no relation to the file name of
the descriptor in the client’s file system.

In addition to the File element, the response includes Owner, Children, LeaseSettingsSection, and
CustomizationSection elements that the server creates and sets to their default contents. For more
information about these elements, see the schema reference.

Uploading the OVF Descriptor

You upload the OVF descriptor by making a PUT request to the upload URL created for it in the
VAppTemplate. The request body is the descriptor's Envelope element. If the request is valid, the server
responds with a 200 OK status.

Prerequisites
Verify that you have an upload URL for the OVF descriptor. See “Retrieving the Upload URL for the OVF
Descriptor,” on page 66.

Procedure
1 Upload the OVF descriptor.

Make a PUT request to the upload URL in the VAppTemplate. The upload URL for the OVF descriptor is
in a Link element with the following form:

<Link
rel="upload:default"
href="[Link] />

Supply the OVF descriptor as the request body. The OVF descriptor contains a single Envelope element.

VMware, Inc. 67
vCloud API Programming Guide for Service Providers

2 Verify that the request succeeded.

A response of the following form indicates that the request was valid and is being processed:

200 OK

Example: Uploading the OVF Descriptor

Request:

PUT [Link]
Content-Type text/xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Envelope
xmlns="[Link]
... >
...
</Envelope>

Response:

200 OK

Retrieving Additional Upload URLs

After an OVF descriptor is uploaded, the server validates it and, if it is valid, updates the corresponding
template with upload URLs for each of the files referenced in the descriptor. You must retrieve the template
to see these URLs.

Procedure
1 Retrieve the VAppTemplate to verify that the OVF descriptor is uploaded.

See the request portion of “Example: Upload URLs in a vAppTemplate,” on page 68.

2 Verify that the value of the template's ovfDescriptorUploaded attribute is true.

3 Examine the template to find the upload URLs for the files referenced in the OVF descriptor.

These URLs are contained in Link elements where rel="upload:default".

Example: Upload URLs in a vAppTemplate

This request uses the vApp template URL returned in “Retrieving the Upload URL for the OVF Descriptor,”
on page 66.

Request:

GET [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<VAppTemplate
xmlns="[Link]
xmlns:ovf="[Link]
ovfDescriptorUploaded="true"
goldMaster="false"
status="0"
name="Ubuntu Template"

68 VMware, Inc.
Chapter 4 Provisioning an Organization

id="urn:vcloud:vapptemplate:111"
href="[Link]
type="application/[Link]+xml">
...
<Description>Ubuntu vApp Template</Description>
<Files>
<File
size="3940"
bytesTransferred="3940"
name="[Link]">
<Link
rel="upload:default"
href="[Link]
</File>
<File
size="1024"
bytesTransferred="0"
name="[Link]">
<Link
rel="upload:default"
href="[Link]
</File>
<File
size="1950489088"
bytesTransferred="0"
name="[Link]">
<Link
rel="upload:default"
href="[Link]
</File>
</Files>
...
</VAppTemplate>

In this example, which omits most of the additional elements shown in “Example: Initiating the Upload,” on
page 65, the ovfDescriptorUploaded attribute has a value of true and the status attribute has a value of 0. If
the descriptor fails validation, 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 where 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 begun. In the File element
that references the OVF descriptor, the value of the bytesTransferred
attribute is equal to the value of the size attribute, indicating that all the
bytes in the descriptor were transferred.

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

Note Upload URLs remain valid while a transfer session is in progress, and for a maximum of 60 minutes
of transfer session idle time. A system administrator can change this default value. See “Retrieve or Update
System Settings,” on page 268.

VMware, Inc. 69
vCloud API Programming Guide for Service Providers

Uploading Referenced Files

You can use a PUT request to upload each file that the vApp template references.

Prerequisites
n Verify that you uploaded the OVF descriptor. See “Uploading the OVF Descriptor,” on page 67.

n Retrieve the upload URLs for all files in the package. See “Retrieving Additional Upload URLs,” on
page 68.

Procedure
1 Find the upload:default URL for the file you want to upload.

2 Use the upload:default URL to construct a PUT request for the file.

The request specifies an upload URL and a content length in bytes. See “Example: Uploading File
Data,” on page 70.

After all the files are uploaded, the vApp template is complete, and has a status attribute value of 8. If the
upload included a manifest file, the server checks each file in the upload to verify that its checksum matches
the one stated in the manifest. If a checksum does 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.

Example: Uploading File Data

This example shows an upload request for one of the files that an OVF package requires. The upload request
is a Content-Length header followed by the serialized file content.

Request:

PUT [Link]
Content-length: 1950489088
...serialized contents of file [Link]...

EOF

Response:

200 OK

Monitoring the Progress of an Upload

After you initiate the upload of a file referenced by a vApp template, you can monitor the progress of the
upload by periodically retrieving the vApp template and checking the value of the file's bytesTransferred
attribute.

To monitor the progress of an upload, you can watch the bytesTransferred attribute of the file. Each File
element in the template includes a bytesTransferred attribute whose value indicates the number of bytes
that the server received.

Prerequisites
Verify that you initiated the upload of a file referenced by the vApp template.

Procedure
1 Make a GET request specifying the URL of the vApp template.

See the request portion of “Example: Monitoring the Progress of an Upload,” on page 71.

70 VMware, Inc.
Chapter 4 Provisioning an Organization

2 Compare the values of the size and the bytesTransferred attributes of each File element.

When these two values are equal, the file transfer is complete.

After all the files are uploaded, the response includes final values for the bytesTransferred attribute of each
File, and a Task that tracks the events leading up to resolution of the template with the uploaded files, as
shown in “Example: Monitoring the Progress of an Upload,” on page 71.

Example: Monitoring the Progress of an Upload

Request:

GET [Link]

The complete VAppTemplate body is returned. This example omits most of it for clarity.

Response:

200 OK
Content-Type: application/[Link]+xml
...
<VAppTemplate
...
name="Ubuntu Template"
id="urn:vcloud:vapptemplate:111"
href="[Link]
type="application/[Link]+xml" ... >
...
<Files>
...
<File
size="1950489088"
bytesTransferred="500000000"
name="[Link]">
<Link
rel="upload:default"
href="[Link]
</File>
</Files>
...
</VAppTemplate>

Using Ranged PUT requests to Complete a Partial Upload

You typically need ranged PUT requests for very large uploads, especially when network bandwidth or
latency might cause the operation to time out.

If the response to an upload progress request indicates that the upload terminated before it was complete,
you can use the size and bytesTransferred values from the response to construct a ranged PUT request of
the remaining contents, as shown in “Example: Ranged PUT Request to Complete a Partial Upload,” on
page 72.

Procedure
1 Retrieve the VAppTemplate and find the File element that references the partially uploaded file.

VMware, Inc. 71
vCloud API Programming Guide for Service Providers

2 Make a PUT request that specifies a Content-Range and Content-Length and includes the serialized
contents of the range.

For the bytes attribute of the Content-Range, specify the value of the File element's bytesTransferred
attribute for the low end of the range and the value of its size attribute for the high end of the range.
For Content-Length, subtract the value of the File element's bytesTransferred attribute from the value
of its size attribute.

Example: Ranged PUT Request to Complete a Partial Upload

The following request completes the upload of the file [Link] shown in this fragment of a VAppTemplate.

<VAppTemplate
... >
...
<Files>
...
<File
size="1950489088"
bytesTransferred="500000000"
name="[Link]">
...
</File>
</Files>
...
</VAppTemplate>

Request:

PUT [Link]
Content-Range: bytes 500000000-1950489087/1950489088
Content-Length: 1450489088
...serialized contents of specified range...
EOF

Response:

200 OK

Download a vApp or vApp Template as OVF

You can download a vApp or vApp template object as an OVF package. After you enable the object for
download, you can download the OVF descriptor, then download all of the files referenced by the
descriptor. A vApp must powered off and undeployed before you can enable it for download.

When you enable a vApp or vApp template for download, the server performs several operations to create
an OVF package and make it available to the transfer service.

1 The server reconstructs the OVF descriptor using information in the vApp or vApp template. The
server excludes any deployment-specific information that the object contains, and populates the
descriptor's References element with references to files, such as .vmdk files, that are part of the package.

2 The server copies the reconstructed OVF descriptor to transfer service storage, along with all files that
the descriptor references.

3 The server updates the corresponding VApp or VAppTemplate element with a link that contains a URL
from which you can retrieve the OVF descriptor.

4 After you retrieve the descriptor, you can examine it to discover the download URLs for the files it
references.

You can download any file referenced in the descriptor by making a GET request to its download URL.

72 VMware, Inc.
Chapter 4 Provisioning an Organization

1 Enable a vApp or vApp Template for Download on page 73

Before you can download a vApp or vApp template, an administrator or privileged user must
explicitly enable the object for download.

2 Download the OVF Descriptor of a vApp or vApp Template on page 74

To download the OVF descriptor, make a GET request to the download:default or download:identity
URL in the download-enabled VApp or VAppTemplate element.

3 Download a Referenced File on page 75

After you download the OVF descriptor of a vApp or vApp template, you can examine the contents of
the descriptor to discover download URLs for .vmdk and other files in the package.

Enable a vApp or vApp Template for Download

Before you can download a vApp or vApp template, an administrator or privileged user must explicitly
enable the object for download.

Prerequisites
n Verify that you are logged in as a user who has privileges to enable a vApp or vApp template for
download.

n Verify that any vApp you plan to enable for download is powered off and undeployed. See “Undeploy,
Power Off, and Delete the vApp,” on page 43.

Procedure
1 Retrieve the XML representation of the VApp or VAppTemplate object.

2 Examine the representation to find its action/enableDownload link.

Every VAppTemplate element includes a link of the following form, where id is the id of the template:

<Link
rel="enable"
href="[Link]

Every vApp element includes a similar link:

<Link
rel="enable"
href="[Link]

3 Enable the object for download.

Make a POST request to the action/enableDownload URL, which you retrieved in Step 2. The response is
a Task that tracks the completion of the enablement operation.

4 When the task completes, retrieve the representation of the object, which now contains download URLs
for the OVF descriptor.

Download URLs remain valid while a transfer session is in progress, and for a maximum of 60 minutes
of transfer session idle time. A system administrator can change this default value. See “Retrieve or
Update System Settings,” on page 268.

Example: vApp Template with Download URLs for OVF Descriptor

Request:

GET [Link]

VMware, Inc. 73
vCloud API Programming Guide for Service Providers

Response:

200 OK
Content-Type: application/[Link]+xml
...
<VAppTemplate
ovfDescriptorUploaded="true"
status="8"
name="Ubuntu Template"
... >
...
<Link type="text/xml"
rel="download:default"
href="[Link]
<Link type="text/xml"
rel="download:identity"
href="[Link]
...
</VAppTemplate>

Download the OVF Descriptor of a vApp or vApp Template

To download the OVF descriptor, make a GET request to the download:default or download:identity URL
in the download-enabled VApp or VAppTemplate element.

You can download an OVF descriptor with or without identity information such as lease settings and
network connection details. Identity information is typically not portable to another deployment
environment.

Prerequisites
n This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

n Verify that you have a vApp or vApp template that is enabled for download. See “Enable a vApp or
vApp Template for Download,” on page 73.

Procedure
1 Retrieve the XML representation of the VApp or VAppTemplate object.

2 Examine the representation to find the download URLs for the OVF descriptor.

The download URLs are contained in Link elements, each with a different value for the rel attribute.

Option Description
Retrieve a descriptor that does not Use the download:default URL
include identity information
Retrieve a descriptor that includes Use the download:identity URL
identity information.

3 Make a GET request to the URL that retrieves the descriptor you want.

See “Example: Downloading the OVF Descriptor,” on page 74.

Example: Downloading the OVF Descriptor

This example downloads the OVF descriptor from the download:default URL shown in the href value of the
Link shown in “Example: vApp Template with Download URLs for OVF Descriptor,” on page 73. The
response includes the entire Envelope element, only part of which appears here.

74 VMware, Inc.
Chapter 4 Provisioning an Organization

Request:

GET [Link]

Response:

200 OK
Content-Type text/xml
...
<Envelope
xmlns="[Link]
... >
...
</Envelope>

Download a Referenced File

After you download the OVF descriptor of a vApp or vApp template, you can examine the contents of the
descriptor to discover download URLs for .vmdk and other files in the package.

The OVF descriptor includes an href value for each file that the descriptor references. To retrieve one of
these files, you must create a download URL for it by combining this href value with a URL derived from
the download URL that you used to retrieve the descriptor. You must retrieve all of the referenced files to
create a valid OVF package.

Prerequisites
n This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

n Retrieve the OVF descriptor of a vApp or vApp template that has been enabled for download.

Procedure
1 For each File element in the References element of the descriptor, construct a download URL.

a Start with the URL that you used to download the descriptor.

This URL is the href value of the download:default link that the template contains.

b Replace the final component of that URL with the value of the href attribute of the File element.

2 Use the constructed URLs to download each file.

See “Example: Downloading a Referenced File,” on page 75.

Example: Downloading a Referenced File

The request URL shown in this example combines the URL used in the request portion of
“Example: Downloading the OVF Descriptor,” on page 74 with the file name shown in this File element:

<File
ovf:href="[Link]"
ovf:id="file1"
ovf:size="1950489088"/>

Request:

GET [Link]

VMware, Inc. 75
vCloud API Programming Guide for Service Providers

Response:

200 OK
...
...serialized contents of file [Link]...

EOF

Note The downloaded package is valid only if the descriptor and all of its referenced files maintain the
same relationship in the local file system that they had on the transfer server file system. In this case, the
descriptor and [Link] were both in the same directory, which is the default arrangement.

Upload a Media Image

Uploading an ISO-format media image to a catalog creates a Media object and a corresponding CatalogItem
object.

vCloud Director supports using the vCloud API to upload media images to a catalog.

Note Media images in formats other than ISO can be uploaded, but are given an imageType of other in the
catalog.

The workflow for uploading media images is similar to the one shown in “Upload an OVF Package to
Create a vApp Template,” on page 62.

Prerequisites
Verify that the following conditions are met:

n You have a media image to upload.

n You are logged in as a user who has permission to upload media images.

n You know the URL of the target catalog that will receive the upload. Retrieve the XML representation of
your organization to see a list of the catalogs that it contains.

Procedure
1 Find the add link for media in the target catalog

This link has the following form:

<Link
rel="add"
type="application/[Link]+xml"
href="[Link] />

2 POST an action/upload request to the URL shown in Step 1

The request body is a Media element. See the request portion of “Example: Upload a Media Image,” on
page 77.

The server uses this information to create a CatalogItem and corresponding Media object, then returns
the CatalogItem in its response. See the response portion of “Example: Upload a Media Image,” on
page 77.

3 Use the URL in the Entity element of the CatalogItem to retrieve the Media object.

The Media element includes a File element that contains an upload:default URL.

4 PUT the media file contents to the upload:default link in the response.

The procedure is the same as the one shown in “Uploading Referenced Files,” on page 70.

76 VMware, Inc.
Chapter 4 Provisioning an Organization

Example: Upload a Media Image

There are two steps to uploading a media file. The first step is to make an action/upload request to the
catalog. The request body is a Media element that specifies the size of the ISO file and the name that you
want to apply to the created Media object. The imageType attribute is optional, and must be set to a value of
iso if you supply it.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Media
xmlns="[Link]
name="[Link]"
size="51242131"
imageType="iso">
<Description>ISO database image</Description>
</Media>

Response:

201 Created
Content-Type: application/[Link]+xml
...
<CatalogItem
xmlns="[Link]
name="[Link]"
id="urn:vcloud:catalogitem:221"
href="[Link] ... >
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="remove"
href="[Link] />
<Description>Approved template for public FTP sites</Description>
<Entity
type="application/[Link]+xml"
name="[Link]"
href="[Link] />
</CatalogItem>

Examine the response to the action/upload request, then make a GET request to the URL in the Entity
element of the CatalogItem to retrieve the Media object.

GET [Link]

VMware, Inc. 77
vCloud API Programming Guide for Service Providers

The Media object includes an upload URL for the media file itself.

<Media ... >

...
<Files>
<File
name="[Link]"
bytesTransferred="0">
<Link
rel="upload:default"
href="[Link] />
</File>
</Files>
...
</Media>

PUT the media file contents to the upload:default link in the response. The procedure is the same as the one
shown in “Uploading Referenced Files,” on page 70.

The upload URL remains valid while a transfer session is in progress, and for a maximum of 60 minutes of
transfer session idle time. A system administrator can change this default value. See “Retrieve or Update
System Settings,” on page 268.

Download a Media Image

The vCloud API supports downloading media images from a catalog.

Prerequisites
Verify that the following conditions are met:

n You are logged in as a user who has permission to download media images.

n You know the URL of the catalog item that references the media image.

Procedure
1 Retrieve the XML representation of the catalog and examine the catalog items that it contains.

2 Retrieve the catalog item that represents the media image.

3 Use the URL in the Entity element of the CatalogItem to retrieve the Media object.
The Media element includes a Link element of the following form, where id is the id of the media image:

<Link
rel="enable"
href="[Link]

4 Enable the media image for download.

Make a POST request to the action/enableDownload URL shown in Step 2. The response is a Task
element.

5 When the task completes, retrieve the media item again.

The Media object now includes a download URL for the media file.

6 Make a GET request to the download:default URL.

The media file is downloaded to the current working directory.

78 VMware, Inc.
Chapter 4 Provisioning an Organization

Example: Download a Media Image

When you download a media file, you first enable the file for download.

Request:

POST [Link]

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task
...
operation="Enabling download of Media [Link] (254)" ... >
...
</Task>

The Task in the response tracks the creation of the downloadable image. When the task completes, retrieve
the Media element again.

GET [Link]

The Media object now includes a download URL for the media file.

<Media ... >

...
<Files>
<File
name="[Link]"
bytesTransferred="0">
<Link
rel="download:default"
href="[Link] />
</File>
</Files>
...
</Media>

The download URL remains valid while a transfer session is in progress, and for a maximum of 60 minutes
of transfer session idle time. A system administrator can change this default value. See “Retrieve or Update
System Settings,” on page 268.

Capturing and Importing vApps

You can capture a vApp to create a vApp template from it. If you are a system administrator, you can also
import vApps and vApp templates from vSphere.

As an administrator, catalog author, or vApp author, you can capture an undeployed vApp to create a vApp
template in a catalog. Instantiating this template recreates the vApp from which the template was captured.
Capturing a vApp in this way provides a way to save the results of composing, recomposing, or modifying a
vApp after the vApp is undeployed. In addition, capturing a vApp preserves all vApp reconfiguration in
template form. Although most elements of a vApp template are read-only, you can instantiate a template,
modify the resulting vApp, and capture it to create a modified version of the template. See “Capture a vApp
as a Template,” on page 123

VMware, Inc. 79
vCloud API Programming Guide for Service Providers

Importing vApps or vApp Templates from vSphere

A system administrator can import vApps and vApp templates from vSphere. See “Import a Virtual
Machine from vCenter,” on page 343.

Discovering and Adopting vApps

In the default configuration, an organization VDC automatically discovers vCenter VMs that were created in
any resource pool that backs the VDC. The system constructs a simplified vApp, owned by the system
administrator, to contain each discovered VM. After the system administrator grants you access to a
discovered vApp, you can reference the VM in it when you compose or recompose a vApp, or modify the
vApp to adopt it and import it.

Discovered vApps contain exactly one VM, and are subject to several constraints that do not apply to vApps
created in vCloud Director. Whether or not you adopt them, they can be useful as a source of VMs to use
when composing or recomposing a vApp.

Each discovered vApp is given a name that is derived from the name of the vCenter VM that it contains and
a prefix specified by your organization administrator. When retrieved with a vCloud API request, the
autoNature element in a discovered vApp has a value of true. This value changes to false when the vApp is
adopted.
If you want to discover additional vApps, a system administrator can use the vCloud API to create new
organization VDCs that adopt specified resource pools available from a Provider VDC. vCenter VMs in
these adopted resource pools appear in the new VDC as discovered vApps, and are candidates for adoption.

Enabling VM Discovery
VM discovery is enabled by default. To disable VM discovery for all organizations, a system administrator
must update the value of the VmDiscoveryEnabled setting in the system's GeneralSettings. To disable VM
discovery for all VDCs in an organization, an organization administrator must update the value of the
VmDiscoveryEnabled setting in the GeneralOrgSettings for that organization. To disable VM discovery for an
individual organization VDC, an organization administrator must update the value of the
VmDiscoveryEnabled setting in the AdminVdc that represents the organization VDC.

Using a VM From a Discovered vApp

After the system administrator grants you access to a discovered vApp, you can use its VM in the same way
that you would use a VM that any other vApp or vApp template contains. For example, you can specify it
when you compose or recompose a vApp. You can also clone a discovered vApp. None of these uses adopts
the discovered vApp.

Adopting a Discovered vApp

You can adopt a discovered vApp by invoking an operation that modifies it in any way other than a change
to its name or description. After you have adopted a discovered vApp, the system imports it and treats it as
though it was created in vCloud Director. When an adopted vApp is retrieved with a vCloud API request, it
includes an element named autoNature. This element has a value of false if the discovered vApp was
adopted or was created in vCloud Director. You cannot revert an adopted vApp to a discovered vApp.

If you delete or move the VM that a discovered vApp contains, the system also removes the containing
vApp. This behavior does not apply to adopted vApps.

The vApp created to contain a discovered vCenter VM is similar to the one created when you manually
import a VM as a vApp, but it is simplified in ways that might require you to modify it before you can
deploy it in your VDC. For example, you might have to edit its networking and storage properties, and
make other adjustments specific to the needs of your organization.

80 VMware, Inc.
Chapter 4 Provisioning an Organization

Managing Catalog Items

Catalog items are references to vApp templates and media files. If you have the appropriate rights, you can
copy, move, rename, or delete catalog items in your organization's catalogs. You cannot modify catalog
items in catalogs that have an external subscription.

After you add vApp templates or media files to a catalog, you might need to modify the CatalogItem objects
that represent them. Your rights to manipulate catalog items depend on the source from which the catalog
items were created.

n If you are a catalog author or an administrator, you can copy, move, delete, or rename catalog items that
were uploaded, imported, or captured to a catalog that your organization owns, whether or not the
catalog is published externally. Changes you make to an externally published catalog are replicated to
all of the catalog's subscribers when those subscribers synchronize their copy of the catalog.

n You cannot make changes to catalog items in catalogs that have an external subscription.

Changes to a catalog item increment the version number of the item and its containing catalog. See “Version
Numbers,” on page 220.

In addition to providing storage for locally created vApp templates and media files, catalogs provide a
flexible publication mechanism that supports distribution of content to other organizations and clouds. If
your organization allows it, you can publish a catalog to external consumers. You can also subscribe to
catalogs that external sources publish, although catalog items in such catalogs cannot be managed by
subscribers. See “Catalog Administration,” on page 219.

Copy or Move a Catalog Item

A Catalog object includes links that implement copy and move operations for the catalog items it contains.

To copy or move a catalog item from a source catalog to a target catalog, POST a
CopyOrMoveCatalogItemParams element that contains a reference to the catalog item to move to the copy or
move link of the target catalog.

Prerequisites
n This operation requires the rights included in the predefined Catalog Author role or an equivalent set of
rights.

n Verify that the target catalog does not have an external subscription.

Procedure
1 Retrieve the XML representation of the source catalog.

Use a request like this one:

GET [Link]

2 Examine the Catalog element to find the CatalogItem elements it contains.

Each CatalogItem in the CatalogItems container has name, type, and href attributes. If you need more
information about a catalog item, you can retrieve it with a GET request to the URL in its href attribute.

3 Retrieve the XML representation of the target catalog.

VMware, Inc. 81
vCloud API Programming Guide for Service Providers

4 Examine the Catalog element to find the copy and move links it contains.

These links have the following form:

<Link
rel="copy"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="move"
type="application/[Link]+xml"
href="[Link] />

5 Create a CopyOrMoveCatalogItemParams element that specifies the catalog item in the Source element.

See “Example: Copy a Catalog Item,” on page 82.

6 POST the CopyOrMoveCatalogItemParams to the appropriate link from the target catalog.

Option Description
Copy the Catalog Item POST the CopyOrMoveCatalogItemParams to the rel="copy" link.
Move the Catalog Item POST the CopyOrMoveCatalogItemParams to the rel="move" link.

Example: Copy a Catalog Item

This request copies the catalog item shown in “Example: Retrieve a Catalog Item,” on page 33 to another
catalog. The response is a Task.
Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<CopyOrMoveCatalogItemParams
xmlns="[Link]
name="Ubuntu 10.04 Template">
<Description>Reference copy of Ubuntu FTP Server</Description>
<Source
href="[Link] />
</CopyOrMoveCatalogItemParams>

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... operation="Copying Virtual Application Template Ubuntu 10.04 Template" ...>
...
</Task>

Change the Name or Description of a Catalog Item

Every CatalogItem object includes a rel="edit" link that you can use to modify the name or description of
the catalog item.

Prerequisites
n This operation requires the rights included in the predefined Catalog Author role or an equivalent set of
rights.

82 VMware, Inc.
Chapter 4 Provisioning an Organization

n Verify that the target catalog does not have an external subscription.

Procedure
1 Retrieve the catalog item from the catalog.

2 Locate the rel="edit" link in the CatalogItem element.

3 Modify the retrieved CatalogItem element to change its name, description, or both.

See “Example: Change the Name and Description of a Catalog Item,” on page 83.

4 Make a PUT request to the href value of the rel="edit" link in the CatalogItem, supplying the modified
CatalogItem in the request body.

Example: Change the Name and Description of a Catalog Item

This request changes the name and the description of the catalog item shown in “Example: Retrieve a
Catalog Item,” on page 33. The request body excludes components such as Link elements and id attributes
that were present in the retrieved CatalogItem. These components are ignored if you include them in a
request.

Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<CatalogItem
xmlns="[Link]
name="DEPRECATED Ubuntu Template">
<Description>Deprecated. Use [Link]
instead </Description>
<Entity
href="[Link]
type="application/[Link]+xml"
name="Ubuntu Template with vsftpd" />
</CatalogItem>

The response shows the modified CatalogItem.

Response:

200 OK
Content-Type: application/[Link]+xml
...
<CatalogItem
xmlns="[Link]
name="DEPRECATED Ubuntu Template">
<Description>Deprecated. Use [Link]
instead </Description>
<Entity
href="[Link]
type="application/[Link]+xml"
name="Ubuntu vApp Template" />
</CatalogItem>

VMware, Inc. 83
vCloud API Programming Guide for Service Providers

Remove an Item from a Catalog

An organization administrator or a user with adequate permissions can remove a CatalogItem by making a
DELETE request to its rel="remove" link.

Removing a CatalogItem also removes the referenced vApp template or media image from the catalog's
storage.

Prerequisites
n This operation requires the rights included in the predefined Catalog Author role or an equivalent set of
rights.

n Verify that the target catalog does not have an external subscription.

Procedure
1 Retrieve the catalog item from the catalog.

2 Locate the rel="remove" link in the CatalogItem element.

3 Make a DELETE request to the href value of the rel="remove" link in the CatalogItem.

Example: Remove an Item from a Catalog

This request removes the source catalog item that was copied in “Example: Copy a Catalog Item,” on
page 82.

Request:

DELETE [Link]

Response:

204 No Content

Synchronize a Catalog or Catalog Item

Catalogs that have external subscriptions are synchronized with their external sources by a background
process that the system administrator controls. You can also force synchronization of individual catalog
items or entire catalogs at any time.

Prerequisites
This operation requires the rights included in the predefined Catalog Author role or an equivalent set of
rights.

Procedure
1 Retrieve the XML representation of a catalog that has an external subscription.

Use a request like this one:

GET [Link]

2 Examine the Catalog element to find the CatalogItem elements that it contains.

3 Examine the Catalog and CatalogItem element to find the sync links that they contain.

In catalogs, these links have the following form:

<Link
rel="sync"
href="[Link] />

84 VMware, Inc.
Chapter 4 Provisioning an Organization

In catalog items, these links have the following form:

<Link
rel="sync"
href="[Link] />

4 Synchronize the catalog or catalog item.

Make a POST request to the appropriate action/sync link.

Option Description
Synchronize a Catalog Make a POST request to the action/sync link in the Catalog element.
Synchronize a Catalog Item Make a POST request to the action/sync link in the CatalogItem
element.

Example: Synchronize a Catalog Item

This request synchronizes a single catalog item. The response is a task that tracks the progress of the
synchronization.

Request:

POST [Link]

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... operation="Synchronizing Catalog Item [Link] (102)" ...>
...
</Task>

Creating and Using Independent Disks

Independent disks are stand-alone virtual disks that you create in organization VDCs. Administrators and
users who have adequate rights can create, remove, and update independent disks, and connect them to
virtual machines.
When you create an independent disk, it is associated with an organization VDC but not with a virtual
machine. After the disk has been created in a VDC, the disk owner or an administrator can attach it to any
virtual machine deployed in that VDC, detach it from a virtual machine, and remove it from the VDC.

Create an Independent Disk

To create an independent disk in an organization VDC, POST a DiskCreateParams element to the VDC's disk
link.

To create an independent disk, you must specify its name and size. You can optionally include a description,
and specify a storage profile to be used by the disk. After you have created the disk, you can modify its
name, description, storage profile, and other propeties.

The owner of a disk is initially the user who created it. To change the owner, see “View or Change the
Owner of an Object,” on page 90.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

VMware, Inc. 85
vCloud API Programming Guide for Service Providers

Procedure
1 Choose an organization VDC to contain the disk.

2 Create a DiskCreateParams element.

You must specify the size (in bytes) and name of the independent disk. See the request portion of
“Example: Create an Independent Disk,” on page 86.

3 POST the DiskCreateParams element you created in Step 2 to the URL for adding disks to the
organization VDC.

See the request portion of “Example: Create an Independent Disk,” on page 86.

Example: Create an Independent Disk

This example adds an independent disk to the organization VDC created in “Add a VDC to an
Organization,” on page 304. Because optional attributes busType and busSubType are omitted, a SCSI disk is
created.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<DiskCreateParams
xmlns="[Link]
<Disk
name="500GB-SCSI"
size="500000000000">
<Description>500 GB SCSI Disk</Description>
</Disk>
</DiskCreateParams>

The response, a subset of which appears here, is a Disk element that contains an embedded Task that tracks
creation of the disk. Because the request did not specify a storage profile for the disk, it uses the default
storage profile for the containing organization VDC. The response also includes Link elements that enable
access to disk operations and metadata. While the disk is under construction, its status remains 0.

Response:

200 OK
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Disk
xmlns="[Link]
size="500000000000"
status="0"
name="500GB-SCSI"
id="urn:vcloud:disk:128"
type="application/[Link]+xml"
href="[Link]
... >
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<Link

86 VMware, Inc.
Chapter 4 Provisioning an Organization

rel="remove"
href="[Link] />
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Description>Independent Disk</Description>
<Tasks>
<Task
...
operationName="vdcCreateDisk"
... >
...
</Task>
</Tasks>
<StorageProfile
type="application/[Link]+xml"
name="bronze"
href="[Link] />
<Owner
type="application/[Link]+xml">
<User
type="application/[Link]+xml"
href="[Link] />
</Owner>
</Disk>

Update an Independent Disk

You can update an independent disk to increase its capacity or change the storage profile that the disk uses.

Use this procedure to update an independent disk when it is not attached to a virtual machine.

When an independent disk is attached to a virtual machine, it is listed in the virtual machine's
VirtualHardwareSection along with the other disks that are not independent of the virtual machine. You can
update an attached independent disk by using the reconfigureVm operation. See “Update Multiple Sections
of a Virtual Machine,” on page 157.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

VMware, Inc. 87
vCloud API Programming Guide for Service Providers

Procedure
1 Retrieve a reference to the independent disk.

You can use a query like this one to retrieve references to all independent disks to which you have
access:

GET [Link]

2 Retrieve the XML representation of the independent disk.

Use one of the references returned by the query shown in Step 1, as shown in this example:

Request:

GET [Link]

The response is a Disk element.

Response:

<Disk
...
name="500GB-SCSI"
href="[Link]
...
</Disk>

3 Verify that the disk is not attached to a virtual machine.

Use the query service. A query like this one returns information about the returned in Step 2.

GET [Link]

The response includes an isAttached attribute. If this attribute has a value of false, the disk is not
attached, and you can update it with a PUT request as shown in “Example: Update an Independent
Disk,” on page 88. Otherwise, you can update it by using the reconfigureVm operation to update the
appropriate Item in the VirtualHardwareSection of the virtual machine to which the disk is attached.

4 Modify the Disk element you retrieved in Step 2. See “Example: Update an Independent Disk,” on
page 88.

Request bodies must contain all required elements and attributes, even if you are not changing their
values. Because optional elements and attributes typically revert to default values if they are omitted or
empty, it is a best practice to include optional elements in request bodies that modify existing objects.
Link elements and href attributes from responses do not need to be included in modified sections. Some
elements and attributes are read-only and cannot be modified. See the schema reference for details.

5 Update the Disk with your modifications.

a In the retrieved Disk element, find the Link element where rel="edit".

b Make a PUT request to the URL in that link's href attribute value, and supply the modified section
as the request body.

Example: Update an Independent Disk

This example updates the independent disk created in “Example: Create an Independent Disk,” on page 86
to change the storage profile.

Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>

88 VMware, Inc.
Chapter 4 Provisioning an Organization

<Disk
xmlns="[Link]
size="500000000000"
name="500GB-SCSI">
<Description>Independent Disk</Description>
<StorageProfile
type="application/[Link]+xml"
name="gold"
href="[Link] />
<Owner type="application/[Link]+xml">
<User
type="application/[Link]+xml"
href="[Link] />
</Owner>
</Disk>

The response is a Task element that tracks the update operation. When the task is complete, the object is
updated.

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... operation="Updating Independent disk 500GB-SCSI (128)" ...>
...
</Task>

Remove an Independent Disk

To remove an independent disk, verify that no powered-on virtual machine is attached to it, then use a
DELETE request to delete it.

A Disk element includes a link of the following form, which you can GET to return a list of virtual machines
to which the disk is attached.

<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />

There are also two queries that you can use to return a list of virtual machines, the disks connected to them,
and the VDC that contains them:

vmDiskRelation Lists this information for Vm and Disk objects that you own.

AdminvmDiskRelation Lists this information for all Vm and Disk objects in a cloud (system
administrators only).

Note An independent disk can be attached to at most one virtual machine.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Verify that the independent disk is not connected to any virtual machine.

VMware, Inc. 89
vCloud API Programming Guide for Service Providers

2 Delete the independent disk.

Make a DELETE request to the URL in the rel="remove" link in the Disk.

The server starts a task to manage the events that lead up to the removal of the object, and returns a Task
element that you can use to track the progress of the task.

Example: Remove an Independent Disk

Request:

DELETE [Link]

Response:

202 Accepted
...
<Task
...
operation="Deleting Disk (128)"
... >
</Task>

View or Change the Owner of an Object

You can view the owner of a VApp, VAppTemplate, Disk, or Media object by making a GET request to the
object's owner link. If you have adequate rights, you can change the owner of a Disk or VApp object, but not
that of a VAppTemplate or Media object. An administrator can view or change the owner of any object.

The initial owner of a VApp, VAppTemplate, Catalog, Disk, or Media object is the user who created it.
Ownership is expressed in an Owner element that the object representation contains. This element includes a
User element that references the owner. Object-specific rights to change ownership are included in several
predefined roles. See “Predefined Roles and Their Rights,” on page 257.

Prerequisites
To change the owner of a Disk, VApp, or Catalog object, you must be an organization administrator or the
system administrator.

Procedure
1 Retrieve the Owner element from the object.
This element includes a reference to the current owner and an edit URL you can use to change the
owner. This request retrieves the owner of a vApp.

GET [Link]

2 Modify the Owner element to specify a different User.

The user must be a member of the organization that contains the object.

Note You cannot modify the Owner of a Media or VAppTemplate object.

3 To change the owner, make a PUT request to the Owner element's rel="edit" URL and supply an Owner
element in the request body.

The User element in the Owner element references the new owner. See “Example: Change the Owner of
a vApp,” on page 91.

90 VMware, Inc.
Chapter 4 Provisioning an Organization

Example: Change the Owner of a vApp

Request:

PUT [Link]
Content-type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Owner
xmlns="[Link]
<User
type="application/[Link]+xml"
href="[Link] />
</Owner>

Response:

204 No Content

Controlling Access to vApps and Catalogs

Upon creation, catalogs and vApps grant full access to their owners and no access to other users. The
vCloud API access control mechanism enables object owners to retrieve or update these access controls as
needed.

To retrieve or update the access controls on a vApp or catalog, use controlAccess links. The controlAccess
links for catalogs are included when you retrieve the containing AdminOrg. The controlAccess links for a
vApp are included in the VApp element itself.

vCloud Director defines three levels of access:

ReadOnly The ReadOnly access level grants rights to read or use the object.

Change The Change access level includes all rights granted by ReadOnly access and
grants additional rights to modify the object and its properties.

FullControl The FullControl access level includes all rights granted by Change access and
grants additional rights to change the owner of the object, share it, or delete
it.

See “Access Rights to vCloud Director Objects,” on page 93 for detailed information about the rights
granted by each access level.

Access Control for vApps

An administrator or vApp owner can control access to a vApp.

Each VApp element includes two types of access control links:

n Links where rel="down".

<Link
rel="down"
type="application/[Link]+xml"
href="[Link]

Use this kind of link to retrieve the access control settings for the vApp identified in the href value.

VMware, Inc. 91
vCloud API Programming Guide for Service Providers

n Links where rel="controlAccess".

<Link
rel="controlAccess"
type="application/[Link]+xml"
href="[Link]

Use this kind of link to specify new access control settings for the vApp identified in the href value. You
specify the new access control settings in a ControlAccessParams element that you post to the URL that
the href value of this link specifies. See “Update vApp Access Controls,” on page 125 for an example.

Access Control for Catalogs

An administrator can control access to a catalog. Each Catalog element includes two types of access control
links:

n Links where rel="down".

<Link
rel="down"
type="application/[Link]+xml"
href="[Link]

Use this kind of link to retrieve the access control settings for the catalog identified in the href value.

n Links where rel="controlAccess".

<Link
rel="controlAccess"
type="application/[Link]+xml"
href="[Link]

Use this kind of link to specify new access control settings for the catalog identified in the href value.
You specify the new access control settings in a ControlAccessParams element that you post to the URL
that the href value of this link specifies.

Important These controlAccess links for catalogs are also returned in an Org element but their appearance
in that context has been deprecated. They might be removed from Org elements in a future version of the
vCloud API .

Granting Access to All Members of an Organization

To specify access controls that apply to all members of an organization, an administrator can set
IsSharedToEveryone to true and specify an access level in the EveryoneAccessLevel element.

The following ControlAccessParams element grants read access to all members of the organization.

<ControlAccessParams
xmlns="[Link]
<IsSharedToEveryone>true</IsSharedToEveryone>
<EveryoneAccessLevel>ReadOnly</EveryoneAccessLevel>
</ControlAccessParams>

Granting Access to Individual Members of an Organization

To specify access controls that apply to specific users, an organization administrator can set
IsSharedToEveryone to false and specify an access level in an AccessSettings element that the
ControlAccessParams request contains.

92 VMware, Inc.
Chapter 4 Provisioning an Organization

An AccessSettings element is populated with one or more AccessSetting elements, each of which assigns
an access level to the user identified in the Subject element. The following ControlAccessParams element
grants full control to one user and read-only access to another user.

<ControlAccessParams
xmlns="[Link]
<IsSharedToEveryone>false</IsSharedToEveryone>
<AccessSettings>
<AccessSetting>
<Subject
type="application/[Link]+xml"
href="[Link]
<AccessLevel>FullControl</AccessLevel>
</AccessSetting>
<AccessSetting>
<Subject
type="application/[Link]+xml"
href="[Link]
<AccessLevel>ReadOnly</AccessLevel>
</AccessSetting>
</AccessSettings>
</ControlAccessParams>

Viewing or Changing the Owner of a vApp or Catalog

Ownership of a VApp or Catalog object is expressed in an Owner element that you can retrieve from the object.
This element contains a User element that identifies the owner with a reference to a specific user. The initial
owner of an object is the user who created it.

A system administrator can view or change the owner of a VApp or Catalog object using the procedure
documented in “View or Change the Owner of an Object,” on page 90.

Access Rights to vCloud Director Objects

Each access level supported by vCloud Director grants one or more users a specific set of rights to an object.

vCloud Director access levels are similar to roles in that they give a name to a set of rights. When you apply
an access control to an object, you grant one or more users in your organization a set of rights to the object.
Access rights are additive. You can make an object more accessible to users who have limited rights, but you
cannot to restrict the rights that a user may already have. For example, an organization administrator retains
full control of an object even if you apply ReadOnlyaccess rights to it for all organization members.

Table 4‑1. Access Levels and the Rights They Grant

FullControl Change ReadOnly

Catalog: Add vApp from X X

My Cloud

Catalog: Change Owner X

Catalog: VCSP Publish X X

Subscribe

Catalog: Edit Properties X X

Catalog: Publish X X

Catalog: View Private and X X X

Shared Catalogs

Catalog: View Published X X X

Catalogs

VMware, Inc. 93
vCloud API Programming Guide for Service Providers

Table 4‑1. Access Levels and the Rights They Grant (Continued)
FullControl Change ReadOnly

vApp Template or Media: X X X

Copy

vApp Template or Media: X X

Create or Upload

vApp Template or Media: X X

Edit

vApp Template or Media: X X X

View

vApp Template: Checkout X X X

(Add to My Cloud)

vApp Template: Download X X X

vApp: Change Owner X

vApp: Copy X X X

vApp: Create or Reconfigure X

vApp: Delete X

vApp: Edit Properties X X

vApp: Edit VM CPU X X

vApp: Edit VM Hard Disk X X

vApp: Edit VM Memory X X

vApp: Edit VM Network X X

vApp: Edit VM Properties X X

vApp: Manage VM X
Password Settings

vApp: Power Operations X X

vApp: Sharing X

vApp: Use Console X X X

94 VMware, Inc.
Deploying and Operating vApps and
Virtual Machines 5
A vApp object contains one or more virtual machines, and provides detailed specifications of those virtual
machines and the networks to which they connect. The vCloud API supports programmatic access to a
range of self-service datacenter operations that allow users to create, configure, deploy, and operate vApps.

The initial configuration of a vApp and the virtual machines it contains is established in the OVF package on
which its source template is based. In the vCloud API, vApp templates are based on 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.

After a vApp has been created, using any of the methods described in “About Instantiation,” on page 98,
you can make further changes to its configuration using procedures like the ones shown in Chapter 6,
“Reconfiguring vApps and Virtual Machines,” on page 151. All configuration changes you make during
instantiation or reconfiguration are discarded when the vApp is deleted, but you can preserve them by
capturing the vApp as a template. See “Capture a vApp as a Template,” on page 123.

About OVF
OVF is a widely accepted standard format that applies to many virtualization technologies.

n Virtual machines and appliances are distributed as OVF packages by many vendors.

n Many vendors, including VMware, offer tools that simplify creating and customizing OVF, support
converting virtual machines on existing virtualization platforms to OVF, or both.

n OVF can express the complex relationships between virtual appliances in enterprise applications. The
author of the appliance can handle most of the complexity, rather than the user who deploys it.

n 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.
Administrators and advanced users should become familiar with the details of the OVF standard before
developing applications with the vCloud API. The complete OVF specification document is available at
[Link] An informative white paper on
OVF is available at [Link]

A 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. The vCloud API does not support uploading or
downloading OVA files.

VMware, Inc. 95
vCloud API Programming Guide for Service Providers

About DMTF, CIM, and RASD

Virtual hardware in OVF packages elements is defined using an open standard framework established by
the Distributed Management Task Force (DMTF). This framework, called the Common Information Model
(CIM), defines virtual hardware resources using the ResourceAllocationSettingData (RASD) schema. In this
schema, each class of virtual hardware is represented as an Item element with a specific ResourceType. Many
vCloud API operations that deploy and configure vApps and virtual machines require you to understand
and sometimes modify RASD Item elements.

You can download the RASD schema files and related information from
[Link]

vApp Life Cycle

A 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 that it contains. The
vApp lifecycle includes several distinct states:

n An OVF package, the form in which vApps are typically distributed.

n A vApp template, created when a client uploads an OVF package to a catalog.

n An undeployed vApp, created when a vApp template is instantiated without also being deployed, or a
deployed vApp is undeployed.

n A deployed vApp, ready to be powered on and operated. Instantiation can include deployment, power-
on, or both.

96 VMware, Inc.
Chapter 5 Deploying and Operating vApps and Virtual Machines

Figure 5‑1. vApp State Transitions

OVF package

[Link]

[Link]

upload

vApp
template
<VApp Template...status=”8”
href=”[Link] Template-3”>
...
...
</VApp Template>

instantiate
vApp
<VApp...status=”8” deployed=“false”
href=”[Link]
...
<Link rel=”deploy”...>
...
</VApp>

deploy
vApp
<VApp...status=”8” deployed=“true”
href=”[Link]
...
<Link rel=”power:powerOn”...>
...
</VApp>

This chapter includes the following topics:

n “About Instantiation,” on page 98

n “Create a vApp From a Template,” on page 105

n “Modify Virtual Machine Hardware and Other Properties During vApp Template Instantiation,” on
page 108

n “Compose a vApp From Existing Virtual Machines,” on page 111

n “Recompose a vApp to Add, Remove, or Reconfigure Virtual Machines,” on page 114

n “Clone a vApp,” on page 118

n “Create a vApp From an OVF Package,” on page 120

n “Capture a vApp as a Template,” on page 123

n “Update vApp Access Controls,” on page 125

n “Create a VM-VM Affinity Rule,” on page 126

n “Using Metadata to Control Virtual Machine Placement,” on page 129

VMware, Inc. 97
vCloud API Programming Guide for Service Providers

n “Operate a vApp,” on page 133

About Instantiation
Instantiation binds the abstract requirements for resources such as memory, CPU, and networking expressed
in a vApp, VM, or vApp template to concrete instances of appropriate resources in a target VDC.

vApp templates and the vApps and virtual machines created from them include detailed specifications of
virtual hardware, network requirements, and other properties like computer names and descriptions, guest
operating system configurations, storage leases, end user license agreement (EULA) text, and so on. Any
time you create a vApp from a template or include a vApp or virtual machine in a composed vApp, you
have the opportunity to modify those specifications so that the resulting configuration meets the needs of
the workload. Instantiation operations use a POST request and create a vApp with a configuration you
specify in the request body.

Not all configuration details of a vApp or virtual machine can be modified during instantiation. As an
adjunct to instantiation, you can use various reconfiguration operations to update an existing vApp or
virtual machine. See Chapter 6, “Reconfiguring vApps and Virtual Machines,” on page 151.

Instantiation Parameters
The InstantiationParams element is a generic parameter-passing mechanism that can apply to a vApp or
virtual machine.

Table 5‑1. Requests That Allow InstantiationParams

Request Request Body Description

instantiateVAppTemplate InstantiateVAppTemplateParams Creates a vApp from a vApp template.

This simple form of instantiation is
limited to creating a vApp that
includes the set of virtual machines
defined in the template.

composeVApp ComposeVAppParams Creates a vApp composed from any

combination of vApp templates and
virtual machines. Virtual machines
referenced in the request body must be
powered off and cannot have an
independent disk attached. They can
be sourced from any vApp or vApp
template accessible to you. Any vApp
referenced in the request body
contributes all of its virtual machines
to the composed vApp, but its vApp-
level configuration details (such as
vApp networks and lease settings) are
ignored and replaced by the vApp-
level instantiation parameters supplied
in the request body.

98 VMware, Inc.
Chapter 5 Deploying and Operating vApps and Virtual Machines

Table 5‑1. Requests That Allow InstantiationParams (Continued)

Request Request Body Description

recomposeVApp RecomposeVAppParams Edits a vApp to add, remove, or

reconfigure virtual machines. Virtual
machines referenced in the request
body must be powered off and cannot
have an independent disk attached.
They can be sourced from any vApp or
vApp template accessible to you. Any
vApp added contributes all of its
virtual machines to the composed
vApp, but its vApp-level configuration
details (such as vApp networks and
lease settings) are ignored and
replaced by the vApp-level
instantiation parameters supplied in
the request body.

cloneVApp CloneVAppParams Creates a copy of an existing vApp.

You can include vApp-level
instantiation parameters that apply to
the copy. You can also include
SourcedItem elements that apply
instantiation parameters to virtual
machines in the vApp.

instantiateOvf InstantiateOvfParams Creates a vApp or virtual machine

from an OVF upload. This simple form
of instantiation is limited to creating
the vApp or virtual machine defined in
the uploaded OVF package.

The set of elements and attributes that are allowed within an InstantiationParams element depends on
whether the InstantiationParams apply to a vApp template or virtual machine.

Instantiation Parameters for vApps

An instantiateVAppTemplate, composeVApp, or recomposeVApp request can modify certain properties of a
vApp by including an InstantiationParams element at the vApp level. The placement of vApp-level
InstantiationParams depends on the type of request you are making:

n In an instantiateVAppTemplate request, vApp-level instantiation parameters are included at the root

level of the InstantiateVAppTemplateParams request body, preceding the Source element that references
the template you are instantiating. See “Instantiation Parameters for vApps,” on page 99

n In a composeVApp request, vApp-level instantiation parameters are included in the SourcedItem whose
Source element references the vApp template being instantiated or included in the composition.

n In a recomposeVApp request, which specifies a vApp in the request URL, the vApp-level instantiation
parameters are included at the root level of the RecomposeVAppParams request body.

n In an instantiateOvf request, vApp-level instantiation parameters are included at the root level of the
InstantiateOvfParams request body.

VMware, Inc. 99
vCloud API Programming Guide for Service Providers

InstantiationParams for a vApp can include any of the following elements:

LeaseSettingsSection Defines the terms of storage and deployment leases for the vApp. If this
section is omitted, the vApp inherits the default lease settings of the
containing organization.

NetworkConfigSection Defines the properties of the vApp network and specifies how it is connected
to one or more organization VDC networks. Unless you intend to create a
vApp that has no connection to any network, you must include this section
in your InstantiationParams.

StartupSection Defines the order in which the virtual machines in the vApp start up and
shut down. If this section is omitted, the startup and shutdown order of
virtual machines in the vApp is indeterminate.

Instantiation Parameters for Virtual Machines

An instantiateVAppTemplate, composeVApp, or recomposeVApp request can modify certain properties of
individual virtual machines by including InstantiationParams in the SourcedItem whose Source element
references the virtual machine.

InstantiationParams for a virtual machine can include any of the following elements:

VirtualHardwareSection Contains a description of the virtual hardware supported by a virtual

machine. Each hardware resource is defined in an Item element. Instantiation
parameters for a virtual machine can include individual items of the
following types:

n CPU (RASD resource type 3)

n Memory (RASD resource type 4)

n Hard disk (RASD resource type 17)

Important Changes to most Item elements in a VirtualHardwareSection

are ignored by the composeVApp operation.

OperatingSystemSection Specifies the guest operating system installed on the virtual machine.

NetworkConnectionSectio Specifies how the virtual NIC devices on the virtual machine are connected
n to the vApp network.

GuestCustomizationSecti Contains guest customization parameters for the virtual machine.

on

VmCapabilities Allows you to specify virtual machine capabilities such as hot-add of

memory or CPU.

About vApp Networks

Every vApp contains a vApp network. Virtual machines in the vApp connect to this network, which can be
isolated from other networks or connected to an organization VDC network.

A vApp network is a logical network that controls how the virtual machines in a vApp connect to each other
and to organization VDC networks. You create a vApp network when you make an
instantiateVAppTemplate, composeVApp, recomposeVApp, or instantiateOvf request. The network is created
when the vApp is deployed, and deleted when the vApp is undeployed. All nonisolated virtual machines in
the vApp connect to a vApp network, as specified in their NetworkConnectionSection elements.

100 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

Every VApp element includes a link that you can use to retrieve details of its vApp network.

<Link
rel="down"
type="application/[Link]+xml"
name="isoNet1"
href="[Link] />

A GET request to this link returns a read-only VAppNetwork element with the configuration specified in the
InstantiationParams used when the vApp was created or composed. To modify an existing vApp network,
retrieve its NetworkConfigSection and use the edit link it contains, as shown in “Update a vApp Network
Configuration,” on page 161.

vApp Network Configurations

The configuration of a vApp network, represented by a NetworkConfig element contained in the
NetworkConfigSection of your InstantiationParams, includes the following information

n A name for the network, specified in the networkName attribute of the NetworkConfig element. The
instantiation parameters must create a vApp network whose name matches the value of the network
attribute of the NetworkConnection of each Vm element in the template. If this attribute has the value none
or is missing, the Vm can connect to any network. If the template contains Vm elements that specify
different names for their network connections, you must create a vApp network for each.

Note When you create a vApp network where the FenceMode is bridged, the networkName of the vApp
network must match the name of the ParentNetwork. This requirement is enforced by the composeVapp
operation. The instantiateVappTemplate operation automatically corrects a name mismatch by
changing the value of the network attribute in the NetworkConnection element of the VApp.

n A Configuration element that specifies network configuration details.

n For routed and directly connected networks, the ParentNetwork element contains a reference to the
organization VDC network that the vApp network connects to. The FenceMode element controls
how the two networks connect. Specify a FenceMode of bridged for a direct connection to the parent
network, or natRouted to specify a routed connection controlled by network Features such as a
NatService or FirewallService. If you want the organization network to be isolated, with no
external connection, omit the ParentNetwork element and specify the FenceMode as isolated.

n The Features element defines network services, such as DHCP, firewall, network address
translation, and static routing, provided to virtual machines in the vApp.

n Additional modifiable elements like IpScopes and RetainNetInfoAcrossDeployments, and read-only

elements such as SyslogServerSettings and RouterInfo. For more information about the type and
scope of these elements, see the schema reference.

n Network pool resources required by an isolated or natRouted vApp network are allocated by the
system from the pool associated with the VDC in which the vApp is deployed.

Network Services in vApp Networks

The Features element of a vApp NetworkConfigSection defines the network services available to virtual
machines in the vApp.

A vApp network can be configured to provide many of the same kinds of services available in an
organization VDC network. Configuration parameters for these services are similar to those of their
counterparts on an Edge Gateway, but scoped to the needs of a vApp network.

For more information about vCloud Director networks, see “About vCloud Director Networks,” on
page 199. For more information about network services for organization VDC networks, see “Configure
Edge Gateway Services,” on page 201

VMware, Inc. 101

vCloud API Programming Guide for Service Providers

DHCP Service
A DhcpService element defines an IP address range and lease policies for a DHCP service that can be used
by virtual machines in the vApp. Unlike a DHCP service in an Edge Gateway, it can support only a single IP
address range, as shown in this example.

<DhcpService>
<IsEnabled>true</IsEnabled>
<DefaultLeaseTime>3600</DefaultLeaseTime>
<MaxLeaseTime>7200</MaxLeaseTime>
<IpRange>
<StartAddress>[Link]</StartAddress>
<EndAddress>[Link]</EndAddress>
</IpRange>
</DhcpService>

Firewall Service
A FirewallService element defines firewall rules that, when matched, block or allow incoming or outgoing
traffic on the vApp network. A firewall rule in a vApp network can specify the destination as a combination
of address and port, or as a specific virtual NIC in a Vm. This FirewallService allows TCP traffic to ports 21
and 22.

<FirewallService>
<IsEnabled>true</IsEnabled>
<FirewallRule>
<IsEnabled>true</IsEnabled>
<Description>FTP Rule</Description>
<Policy>allow</Policy>
<Protocols>
<Tcp>true</Tcp>
</Protocols>
<DestinationPortRange>21</DestinationPortRange>
<DestinationIp>[Link]</DestinationIp>
<SourcePortRange>any</SourcePortRange>
<SourceIp>any</SourceIp>
<EnableLogging>false</EnableLogging>
</FirewallRule>
<FirewallRule>
<IsEnabled>true</IsEnabled>
<Description>SSH Rule</Description>
<Policy>allow</Policy>
<Protocols>
<Tcp>true</Tcp>
</Protocols>
<DestinationPortRange>22</DestinationPortRange>
<DestinationIp>[Link]</DestinationIp>
<SourcePortRange>any</SourcePortRange>
<SourceIp>any</SourceIp>
<EnableLogging>false</EnableLogging>
</FirewallRule>
</FirewallService>

You can see this example in the context of a vApp NetworkConfigSection in “Example: Update a
NetworkConfigSection,” on page 161

102 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

An alternate implementation of the second FirewallRule in this example includes a DestinationVm element
that specifies the destination as a specific virtual NIC (identified in the VmNicId element) in a specific Vm
(identified in the VAppScopedVmId element. The value of VAppScopedVmId is taken from the VAppScopedLocalId
element of the Vm and the VmNicId value is taken from its PrimaryNetworkConnectionIndex. See
“Example: Configuration Links in a Vm Element,” on page 154. The IpType is set to assigned, indicating that
the NIC retains its assigned IP address. If you set IpType is set to NAT, the IP address of the NIC is its
translated address.

<FirewallRule>
<IsEnabled>true</IsEnabled>
<Description>allow ssh to a specific NIC in a specific Vm</Description>
<Policy>allow</Policy>
<Protocols>
<Tcp>true</Tcp>
</Protocols>
<DestinationPortRange>22</DestinationPortRange>
<DestinationVm>
<VAppScopedVmId>3963994b-5a0a-48fe-b9ae-7f9a2d8e8e5b</VAppScopedVmId>
<VmNicId>0</VmNicId>
<IpType>assigned</IpType>
</DestinationVm>
<SourcePortRange>Any</SourcePortRange>
<SourceIp>Any</SourceIp>
<EnableLogging>false</EnableLogging>
</FirewallRule>

NAT Service
A NatService element defines network address translation services to virtual machines on the network. This
simple NatService defines a single rule that implements an IP translation NAT strategy for a single Vm.

<NatService>
<IsEnabled>true</IsEnabled>
<NatType>ipTranslation</NatType>
<Policy>allowTraffic</Policy>
<NatRule>
<OneToOneVmRule>
<MappingMode>automatic</MappingMode>
<VAppScopedVmId>3963994b-5a0a-48fe-b9ae-7f9a2d8e8e5b</VAppScopedVmId>
<VmNicId>0</VmNicId>
</OneToOneVmRule>
</NatRule>
</NatService>

You can see this example in the context of a vApp NetworkConfigSection in “Example: Update a
NetworkConfigSection,” on page 161

A NatService element like this one configures the service to use port forwarding instead of IP translation.
Instead of using a OneToOneVmRule, which specifies one external IP address to one NIC, it uses a VmRule
element, which enables port forwarding by allowing one external IP address to be forward to different ports
on different virtual machines.

<NatService>
<IsEnabled>true</IsEnabled>
<NatType>portForwarding</NatType>
<Policy>allowTraffic</Policy>
<NatRule>
<VmRule>

VMware, Inc. 103

vCloud API Programming Guide for Service Providers

<ExternalPort>22</ExternalPort>
<VAppScopedVmId>3963994b-5a0a-48fe-b9ae-7f9a2d8e8e5b</VAppScopedVmId>
<VmNicId>0</VmNicId>
<InternalPort>22</InternalPort>
<Protocol>TCP</Protocol>
</VmRule>
</NatRule>
</NatService>

Static Routing Service

A StaticRoutingService specifies static routes to other networks. In addition to creating static routes from
organization VDC networks on an EdgeGateway (see “Example: Static Routes Between Organization VDC
Networks,” on page 207, you can create static routes between vApp networks if they both define the same
ParentNetwork. Assume two vApp networks that have the following properties:

n The Configuration of the vApp network in vApp1 has a RouterInfo element whose ExternalIp value is
[Link].

n The Configuration of the vApp network in vApp2 has a RouterInfo element whose ExternalIp value is
[Link].

n Both vApp networks have the same ParentNetwork, an organization VDC network whose network
specification in CIDR notation is [Link]/24.

You can enable static routing between these two vApp networks by inserting a StaticRoutingService
element in the Features of each vApp network Configuration. This excerpt from the NetworkConfigSection
of vApp1 shows the network's Configuration and Features elements..

<!-- Static route from vApp network 1 to vApp network 2 -->

<Configuration>
...
<Features>
<StaticRoutingService>
<IsEnabled>true</IsEnabled>
<StaticRoute>
<Name>TovAppNet2</Name>
<Network>[Link]/24</Network>
<NextHopIp>[Link]</NextHopIp>
<Interface>External</Interface>
</StaticRoute>
</StaticRoutingService>
</Features>
...
</Configuration>

This is a similar excerpt from the NetworkConfigSection of vApp2.

<!-- Static route from vApp network 2 to vApp network 1 -->

<Configuration>
...
<Features>
<StaticRoutingService>
<IsEnabled>true</IsEnabled>
<StaticRoute>
<Name>TovAppNet1</Name>
<Network>[Link]/24</Network>
<NextHopIp>[Link]</NextHopIp>
<Interface>External</Interface>

104 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

</StaticRoute>
</StaticRoutingService>
</Features>
...
</Configuration>

Create a vApp From a Template

An instantiateVAppTemplate request creates a vApp from a vApp template.

To create a vApp from a vApp template, you must bind the template's 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.

For an example of a simple instantiation request, see “Deploy the vApp,” on page 35. You can also specify
additional parameters as part of instantiation.

Template contents that might influence composition of the request body include the following elements in
the vApp itself:

n A NetworkConfigSection that defines a vApp network to which virtual machines in this vApp can
connect.

n One or more EulaSection elements that specify licensing terms or other conditions that you must accept
before creating the vApp. The InstantiateVAppTemplateParams element can include an
AllEULAsAccepted element whose value indicates whether you accept all EULA terms included in the
template. If a vApp template includes any ovf:EulaSection elements, AllEULAsAccepted must be set to a
value of true. Otherwise, instantiation fails.

n A LeaseSettingsSection. If this section is present and specifies settings that are appropriate for the
vApp, you do not need to modify it. If it is absent or empty, the vApp is created with your
organization’s default lease settings. If you specify new lease settings in a LeaseSettingsSection that
you provide as part of instantiation, those settings replace any existing settings and override your
organization's defaults.

Template contents that might influence composition of the request body include the following elements in
the virtual machines that the template contains.

n A NetworkConnectionSection that specifies network connection details for a virtual machine. Unless you
want to create a vApp in which none of the virtual machines are connected to a network, your
instantiation parameters must include at least one NetworkConfigSection that defines a vApp network,
and that section must include a NetworkConfig element whose networkName attribute value matches the
value of the network attribute of the NetworkConnection of each Vm in the template. If this attribute has
the value none or is missing, the Vm can connect to any network. If the template contains Vm elements that
specify different names for their network connections, you must create a vApp network for each.

Prerequisites
n This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

n Review the current configuration of the vApp and its virtual machines. Configuration parameters in the
VAppTemplate such as its NetworkConfigSection and LeaseSettingsSection affect all virtual machines in
the vApp. Configuration parameters for individual virtual machines are defined in Vm elements in the
VAppTemplate. A virtual machine's network connections are defined in its NetworkConnectionSection,
and its hardware configuration is defined in its VirtualHardwareSection. To view the configuration of a
virtual machine in a vApp template, you can retrieve the template and examine the
VirtualHardwareSection of that Vm, or you can download the OVF descriptor of the vApp template, as
shown in “Download the OVF Descriptor of a vApp or vApp Template,” on page 74.

VMware, Inc. 105

vCloud API Programming Guide for Service Providers

Procedure
1 Retrieve the XML representation of the vApp template.

Make a GET request to the URL provided in the href attribute of the Entity contained by the
CatalogItem that references the template. You can also use the query service to return a list of references
to vApp templates that you can access.

2 Examine the template to determine the set of instantiation parameters that the request must include.

3 Create an InstantiateVAppTemplateParams element.

See “Example: Instantiate a vApp Template and Modify Virtual Machine Name, Description, and
Storage Profile,” on page 106 for guidelines.

4 Make a POST request to the action/instantiateVAppTemplate URL of the VDC.

Supply the InstantiateVAppTemplateParams element as the request body.

The server takes the requested action and returns a VApp element. The element has a status attribute value of
0, meaning it is unresolved because the vApp is still being constructed. It also contains a Task element that
tracks the progress of the request.

Example: Instantiate a vApp Template and Modify Virtual Machine Name,

Description, and Storage Profile
An InstantiateVAppTemplateParams request body includes a root-level InstantiationParams element that
provides instantiation parameters for the vApp. To modify properties of any virtual machine in the template
during instantiation, include a SourcedItem element that references the virtual machine and provides
InstantiationParams for it. Virtual machines referenced from SourcedItem elements in an
InstantiateVAppTemplateParams must be members of the Children collection of the vApp template being
instantiated.

<!-- InstantiateVAppTemplateParams request body prototype -->

<InstantiateVAppTemplateParams>
<InstantiationParams>
<!-- vapp-level params -->
</InstantiationParams>
<Source href="[Link]
<SourcedItem>
<Source href="A Vm in template-111">
<InstantiationParams>
<!-- Vm-level params -->
</InstantiationParams>
</Source>
</SourcedItem>
</InstantiateVAppTemplateParams>

This InstantiateVAppTemplateParams request extends the request shown in “Example: Deploying a vApp,”
on page 36 to include additional elements in its InstantiationParams:

n A LeaseSettingsSection that specifies custom lease settings, overriding the settings that would
otherwise be inherited from the organization.

n An acknowledgement of EulaSection acceptance, supplied in the AllEULAsAccepted element. If the

template does not include EulaSection elements, you can omit this acknowledgement.

106 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

n A SourcedItem element whose Source element references a virtual machine in the template. In this
example, the SourcedItem contains:

n a VmGeneralParams element that specifies a new name and Description for a virtual machine in the
template. If you omit this element, instantiation creates the virtual machine with the name and
Description specified in the template.

n a StorageProfile element that specifies a storage profile to be used for this virtual machine. If you
omit this element, the virtual machine uses the default storage profile defined by the containing
VDC.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<InstantiateVAppTemplateParams
xmlns="[Link]
name="Linux FTP server"
deploy="true"
powerOn="true"
xmlns:xsi="[Link]
xmlns:ovf="[Link]
<Description>Example FTP Server</Description>
<InstantiationParams>
<NetworkConfigSection>
<ovf:Info>Configuration parameters for logical networks</ovf:Info>
<NetworkConfig networkName="vAppNetwork">
<Configuration>
<ParentNetwork href="[Link]
<FenceMode>bridged</FenceMode>
</Configuration>
</NetworkConfig>
</NetworkConfigSection>
<LeaseSettingsSection
type="application/[Link]+xml">
<ovf:Info>Lease Settings</ovf:Info>
<StorageLeaseInSeconds>172800</StorageLeaseInSeconds>
<StorageLeaseExpiration>2014-04-25T[Link].438-07:00</StorageLeaseExpiration>
</LeaseSettingsSection>
</InstantiationParams>
<Source href="[Link]
<SourcedItem>
<Source href="[Link]
<VmGeneralParams>
<Name>ftp1</Name>
<Description>Primary FTP Server Instance</Description>
<NeedsCustomization>true</NeedsCustomization>
</VmGeneralParams>
<StorageProfile href="[Link]
</StorageProfile>
</SourcedItem>
<AllEULAsAccepted>true</AllEULAsAccepted>
</InstantiateVAppTemplateParams>

The response is a sparsely populated VApp element, as shown in the response portion of
“Example: Deploying a vApp,” on page 36.

VMware, Inc. 107

vCloud API Programming Guide for Service Providers

Modify Virtual Machine Hardware and Other Properties During vApp

Template Instantiation
Instantiation parameters for a vApp template can modify the virtual hardware configuration, including
network connections, of the virtual machines defined in the template.

An InstantiateVAppTemplateParams request body that incorporates one or more SourcedItem elements

supports a number of changes to the configuration, including the virtual hardware configuration, of virtual
machines in the template. For example:

n Change the name, Description, and NeedsCustomization properties of the virtual machine.

n Specify a storage profile for the virtual machine.

n Specify a storage profile for any of the virtual machine's hard disks, overriding the virtual machine's
default storage profile.

n Specify how the NICs in the virtual machine connect to vApp networks defined in the
NetworkConfigSection of the vApp.

n Specify virtual machine capabilities.

n Increase the capacity of the virtual machine's SATA or SCSI disks.

n Increase or decrease the size of the virtual machine's memory.

n Increase or decrease the number of CPU cores per virtual socket.

n Add or remove CPUs.

You can also modify any of these configuration settings after the vApp is deployed. See Chapter 6,
“Reconfiguring vApps and Virtual Machines,” on page 151.

Prerequisites
n This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

n Review the current configuration of the vApp and its virtual machines. Configuration parameters in the
VAppTemplate such as its NetworkConfigSection and LeaseSettingsSection affect all virtual machines in
the vApp. Configuration parameters for individual virtual machines are defined in Vm elements in the
VAppTemplate. A virtual machine's network connections are defined in its NetworkConnectionSection,
and its hardware configuration is defined in its VirtualHardwareSection. To view the configuration of a
virtual machine in a vApp template, you can retrieve the template and examine the
VirtualHardwareSection of that Vm, or you can download the OVF descriptor of the vApp template, as
shown in “Download the OVF Descriptor of a vApp or vApp Template,” on page 74.

Procedure
1 To change the name, Description, or NeedsCustomization properties of the virtual machine, add a
VmGeneralParams element to the SourcedItem.

2 Examine the OVF descriptor of the template to determine the values that you can include in the
VirtualHardwareSection of the SourcedItem element.

3 Include the SourcedItem element in an InstantiateVAppTemplateParams element.

4 Make a POST request to the action/instantiateVAppTemplate URL of the VDC.

Supply the InstantiateVAppTemplateParams element as the request body.

108 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

Example: Modify Virtual Machine Hardware During vApp Template Instantiation

This InstantiateVAppTemplateParams request extends the request shown in “Example: Instantiate a vApp
Template and Modify Virtual Machine Name, Description, and Storage Profile,” on page 106 to include a
SourcedItem element that makes several configuration changes in the virtual machine referenced at
[Link]

n Sets the value of NeedsCustomization to true.

n Adds a virtual CPU and changes the value of CoresPerSocket to 2. If you include a CoresPerSocket
element, its value must be an integer multiple of the value of the existing rasd:VirtualQuantity of CPU
items, or of the value you supply in NumberOfCpus. “Example: Modify the CPU Configuration of a
Virtual Machine,” on page 166 shows the original CPU configuration, and how to make this change by
reconfiguring the virtual machine in a deployed vApp.

n Increases the capacity of the hard disk from 1GB to 10GB by including a Disk element that specifies a
Size of 10240 for the disk that has a rasd:InstanceID value of 2000. The value you supply for Size is
interpreted as megabytes. You can see the original disk configuration in “Example: Retrieve the Hard
Disks and Controllers in a Virtual Machine,” on page 172. “Example: Modify the Hard Disk
Configuration of a Virtual Machine,” on page 174 shows how to make the same change by
reconfiguring the virtual machine in a deployed vApp. If you include a Disk element, the value of its
instanceId attribute must match the value in the rasd:InstanceID element of an existing Item that
defines a virtual disk (RASD resource type 17). Disk capacity can be increased, but not decreased, for
disks on SATA and SCSI controllers. The capacity of other disk types cannot be changed. Item elements
that represent SATA disks have a vcloud:busType attribute with the value 20. Those that represent SCSI
disks have a vcloud:busType attribute with the value 6.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<InstantiateVAppTemplateParams
xmlns="[Link]
name="Linux FTP server"
deploy="true"
powerOn="true"
xmlns:xsi="[Link]
xmlns:ovf="[Link]
<Description>Example FTP Server</Description>
<InstantiationParams>
<NetworkConfigSection>
<ovf:Info>Configuration parameters for logical networks</ovf:Info>
<NetworkConfig networkName="vAppNetwork">
<Configuration>
<ParentNetwork href="[Link]
<FenceMode>bridged</FenceMode>
</Configuration>
</NetworkConfig>
</NetworkConfigSection>
<LeaseSettingsSection
type="application/[Link]+xml">
<ovf:Info>Lease Settings</ovf:Info>
<StorageLeaseInSeconds>172800</StorageLeaseInSeconds>
<StorageLeaseExpiration>2014-04-25T[Link].438-07:00</StorageLeaseExpiration>
</LeaseSettingsSection>

VMware, Inc. 109

vCloud API Programming Guide for Service Providers

</InstantiationParams>
<Source href="[Link]
<SourcedItem>
<Source href="[Link]
<VmGeneralParams>
<Name>ftp1</Name>
<Description>Primary FTP Server Instance</Description>
<NeedsCustomization>true</NeedsCustomization>
</VmGeneralParams>
<InstantiationParams>
<ovf:VirtualHardwareSection
xmlns:ovf="[Link]
xmlns:rasd="[Link]
schema/2/CIM_ResourceAllocationSettingData"
xmlns:vmw="[Link]
xmlns:vcloud="[Link]
xmlns:vssd="[Link]
schema/2/CIM_VirtualSystemSettingData"
ovf:transport=""
vcloud:href="[Link]
vcloud:type="application/[Link]+xml">
<ovf:Info>Virtual hardware requirements</ovf:Info>
<ovf:Item>
<rasd:AddressOnParent>0</rasd:AddressOnParent>
<rasd:Description>Hard disk</rasd:Description>
<rasd:ElementName>Hard disk 1</rasd:ElementName>
<rasd:HostResource
xmlns:vcloud="[Link]
vcloud:capacity="10240"
vcloud:busSubType="lsilogicsas"
vcloud:busType="6"></rasd:HostResource>
<rasd:InstanceID>2000</rasd:InstanceID>
<rasd:ResourceType>17</rasd:ResourceType>
</ovf:Item>
<ovf:Item>
<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>41</rasd:InstanceID>
<rasd:Reservation>0</rasd:Reservation>
<rasd:ResourceType>3</rasd:ResourceType>
<rasd:VirtualQuantity>2</rasd:VirtualQuantity>
<rasd:Weight>0</rasd:Weight>
<vmw:CoresPerSocket>2</vmw:CoresPerSocket>
</ovf:Item>
</ovf:VirtualHardwareSection>
</InstantiationParams>
<StorageProfile href="[Link]
</StorageProfile>
</SourcedItem>
<AllEULAsAccepted>true</AllEULAsAccepted>
</InstantiateVAppTemplateParams>

The response is a sparsely populated VApp element, as shown in the response portion of
“Example: Deploying a vApp,” on page 36.

110 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

Compose a vApp From Existing Virtual Machines

With the vCloud API composeVApp operation, you can build a vApp from existing virtual machines to which
you have access.

Every VDC includes a link to a composeVApp operation, which creates a new vApp in it. The
ComposeVappParams request body is a superset of InstantiateVAppTemplateParams, and composeVApp can
generally be used wherever you would use instantiateVAppTemplate. To compose a vApp, POST a
composeVApp request to this link. The request body is a ComposeVAppParams element, which includes the
following information:

n An InstantiationParams element that can include any of the section types listed under “Instantiation
Parameters for vApps,” on page 99. This is where you define the vApp network to which all the virtual
machines in the composed vApp connect, and custom vApp lease settings and startup parameters for
the virtual machines.

n An optional Description of the composed vApp.

n Zero or more SourcedItem elements, each of which must contain a Source element that specifies the href
of a Vm, VApp, or VAppTemplate to include in the composition. If the Source element references a virtual
machine, the SourcedItem can include any of the following elements:

n An InstantiationParams element specific to that virtual machine. This element can include any of
the section types listed under “Instantiation Parameters for Virtual Machines,” on page 100.
Changes to most Item elements in a VirtualHardwareSection are ignored by the composeVApp
operation.

n A NetworkAssignment element that specifies how the network connections in the virtual machine
are mapped to vApp networks defined in the InstantiationParams element that applies to the
composed vApp.

n A VAppScopedLocalId element that provides a unique identifier for the virtual machine in the scope
of the composed vApp.

If the Source element references a vApp or vApp template, all Vm elements from each composition
source become peers in the Children collection of the composed vApp.

n 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 you can use it.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Find the composeVApp link in the target VDC.

The XML representation of the VDC contains a composeVapp link, which has the following form:

<Link
rel="add"
type="application/[Link]+xml"
href="[Link] />

2 Create a ComposeVappParams element that specifies the details of the composition. See
“Example: Compose a vApp,” on page 112

VMware, Inc. 111

vCloud API Programming Guide for Service Providers

3 POST the ComposeVappParams element to the composeVapp link of the target VDC.

See the Request portion of “Example: Compose a vApp,” on page 112.

Example: Compose a vApp

A ComposeVAppParams request body includes a root-level InstantiationParams element that provides
instantiation parameters for the composed vApp. The request body can include an arbitrary number of
SourcedItem elements, each of which can specify a vApp template or a virtual machine. SourcedItem
elements where the Source is a vApp template cannot contain InstantiationParams. If you want to modify
any of the virtual machines during composition or recomposition, specify InstantiationParams for them in
the containing Source element.

<!- ComposeVAppParams/RecomposeVAppParams request body prototype -->

<ComposeVAppParams>
<InstantiationParams>
<!-- vApp-level params -->
</InstantiationParams>
<SourcedItem>
<Source href="[Link]
<!-- InstantiationParams not allowed if Source references a vApp template -->
<!-- vApp-level InstantiationParams apply to the composed vApp -->
</SourcedItem>
<SourcedItem>
<Source href="any Vm">
<InstantiationParams>
<!-- Vm-level params -->
</InstantiationParams>
</Source>
</SourcedItem>
</ComposeVAppParams>

This request composes a vApp from two virtual machines. The two SourcedItem elements each define a
virtual machine (in their Source element) and supply InstantiationParams that modify its
NetworkConnectionSection to connect to the vApp network created for this vApp in the root level
InstantiationParams element.

Note If a virtual machine referenced in a Source element is powered on or has an independent disk
attached, this operation will fail. You can use a query like this one to return a list of references to powered-
off virtual machines that you have access to.

[Link]

See Chapter 10, “Using the Query Service,” on page 365.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<ComposeVAppParams
name="Example Corp’s CRM Appliance"
xmlns="[Link]
xmlns:ovf="[Link]
<Description>Composed CRM Appliance</Description>
<InstantiationParams>
<NetworkConfigSection>

112 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

<ovf:Info>Configuration parameters for logical networks</ovf:Info>

<NetworkConfig networkName="CRMApplianceNetwork">
<Configuration>
<ParentNetwork href="[Link]
<FenceMode>natRouted</FenceMode>
</Configuration>
</NetworkConfig>
</NetworkConfigSection>
</InstantiationParams>
<SourcedItem>
<Source href="[Link]
<InstantiationParams>
<NetworkConnectionSection
xmlns:ovf="[Link]
type="application/[Link]+xml"
href="[Link]
ovf:required="false">
<ovf:Info/>
<PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex>
<NetworkConnection network="CRMApplianceNetwork">
<NetworkConnectionIndex>0</NetworkConnectionIndex>
<IsConnected>true</IsConnected>
<IpAddressAllocationMode>DHCP</IpAddressAllocationMode>
</NetworkConnection>
</NetworkConnectionSection>
</InstantiationParams>
</SourcedItem>
<SourcedItem>
<Source href="[Link]
<InstantiationParams>
<NetworkConnectionSection
xmlns:ovf="[Link]
type="application/[Link]+xml"
href="[Link]
ovf:required="false">
<ovf:Info/>
<PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex>
<NetworkConnection network="CRMApplianceNetwork">
<NetworkConnectionIndex>0</NetworkConnectionIndex>
<IsConnected>true</IsConnected>
<IpAddressAllocationMode>DHCP</IpAddressAllocationMode>
</NetworkConnection>
</NetworkConnectionSection>
</InstantiationParams>
</SourcedItem>
<AllEULAsAccepted>true</AllEULAsAccepted>
</ComposeVAppParams>

The response is a sparsely populated VApp element in the target VDC. When the Task embedded in the
response is complete, the vApp has been composed.

Response:

201 Created
Content-Type: application/[Link]+xml
...
<VApp

VMware, Inc. 113

vCloud API Programming Guide for Service Providers

name="Example Corp’s CRM Appliance"

type="application/[Link]+xml"
status="8"
href="[Link] ...>
<Link
rel="up" type="application/[Link]+xml"
href="[Link]
...
<Description>Composed CRM Appliance</Description>
...
<Tasks>
<Task operation="Composing Virtual Application Example Corp’s CRM Appliance (33)" ...>
...
</Task>
</Tasks>
</VApp>

Recompose a vApp to Add, Remove, or Reconfigure Virtual Machines

The vCloud API supports recomposition of a vApp to add, remove, and reconfigure its virtual machines. To
recompose a vApp, make a recomposeVApp request, supplying a RecomposeVAppParams element as the request
body.

The RecomposeVAppParams element allows an arbitrary number of DeleteItem and ReconfigureItem elements,
but is otherwise identical to ComposeVAppParams.

Unlike a composeVapp request, which operates on a VDC and creates a new vApp, a recomposeVapp request
operates on (and modifies) an existing vApp. The XML representation of a vApp contains a recomposeVApp
link, which has the following form:

<Link
rel="recompose"
type="application/[Link]+xml"
href="[Link] />

To recompose a vApp, POST a recomposeVApp request to this link. The request body is a
RecomposeVAppParams element, which can include all the information allowed in a ComposeVAppParams, as
well as the following additional elements:

n ReconfigureItem elements that reconfigure virtual machines in the vApp. By including ReconfigureItem
elements, you can enable a recomposeVApp request to make the same kinds of virtual machine
configuration changes you can make with a reconfigureVm request. See “Update Multiple Sections of a
Virtual Machine,” on page 157

n DeleteItem elements remove virtual machines from the vApp

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Find the recomposeVApp link in the target vApp.

2 Create a RecomposeVappParams element that specifies the details of the recomposition.

See “Example: Recompose a vApp,” on page 115.

3 POST the RecomposeVappParams element to the recomposeVapp link of the target vApp.

114 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

Example: Recompose a vApp

A RecomposeVAppParams request body prototype is similar to the ComposeVAppParams prototype shown in
“Example: Compose a vApp,” on page 112. Instantiation parameters for the recomposed vApp appear as a
root level InstantiationParams element. Instantiation parameters for added virtual machines appear as
InstantiationParams in SourcedItem elements whose Source element references a virtual machine.

This example uses the recomposeVApp operation to modify this vApp, which contains three virtual machines.
Only a few of the elements in the vApp appear here.

<VApp
name="Example Corp’s CRM Appliance"
type="application/[Link]+xml"
status="8"
href="[Link] ...>
...
<Link
rel="recompose"
type="application/[Link]+xml"
href="[Link] />
...
<Children>
<Vm
status="8"
name="CRM-DB-ORCL"
href="[Link] ...>
...
</Vm>
<Vm
status="8"
name="CRM-CRM"
href="[Link] ...>
...
</Vm>
<Vm
status="8"
name="CRM-HTTP"
href="[Link] ...>
...
</Vm>
</Children>
...
</VApp>

Imagine that you want to replace the database server for this vApp with a new one hosted by a virtual
machine that has the following properties:

<Vm
status="8"
name="CRM-DB-POSTGRES"
href="[Link] ...>
...
</Vm>

To do that, create a request like this one, which removes the old database server (DeleteItem), adds the new
one (SourcedItem, including InstantiationParams that connect it to the vApp network), and modifies the
StartupSection to specify an appropriate start order for the recomposed vApp.

VMware, Inc. 115

vCloud API Programming Guide for Service Providers

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<RecomposeVAppParams
name="Example Corp’s CRM Appliance"
xmlns="[Link]
xmlns:ovf="[Link]
<Description>Composed CRM Appliance</Description>
<InstantiationParams>
<NetworkConfigSection>
<ovf:Info>Configuration parameters for logical networks</ovf:Info>
<NetworkConfig networkName="CRMApplianceNetwork">
<Configuration>
<ParentNetwork href="[Link]
<FenceMode>natRouted</FenceMode>
</Configuration>
</NetworkConfig>
</NetworkConfigSection>
<ovf:StartupSection
xmlns:vcloud="[Link]
vcloud:type="application/[Link]+xml">
<ovf:Info>VApp startup section</ovf:Info>
<ovf:Item
ovf:order="0"
ovf:id="CRM-DB-POSTGRES"/>
<ovf:Item
ovf:order="1"
ovf:id="CRM-CRM"/>
</ovf:StartupSection>
</InstantiationParams>
<SourcedItem>
<Source href="[Link]
<InstantiationParams>
<NetworkConnectionSection
xmlns:ovf="[Link]
type="application/[Link]+xml"
href="[Link]
ovf:required="false">
<ovf:Info/>
<PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex>
<NetworkConnection network="CRMApplianceNetwork">
<NetworkConnectionIndex>0</NetworkConnectionIndex>
<IsConnected>true</IsConnected>
<IpAddressAllocationMode>DHCP</IpAddressAllocationMode>
</NetworkConnection>
</NetworkConnectionSection>
</InstantiationParams>
</SourcedItem>
<AllEULAsAccepted>true</AllEULAsAccepted>
<DeleteItem href="[Link]
</RecomposeVAppParams>

116 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

If the virtual machine referenced in SourceItem element in this example was already included in the vApp
but needed to be reconfigured to adapt to the new vApp network configuration, you could use a
ReconfigureItem element in place of the SourcedItem element.

<?xml version="1.0" encoding="UTF-8"?>

<RecomposeVAppParams
name="Example Corp’s CRM Appliance"
xmlns="[Link]
xmlns:ovf="[Link]
<Description>Composed CRM Appliance</Description>
<InstantiationParams>
...
</InstantiationParams>
<AllEULAsAccepted>true</AllEULAsAccepted>
<DeleteItem href="[Link]
<ReconfigureItem
name="vm-90"
href="[Link]
<ovf:Section
xmlns:xsi="[Link]
xsi:type="NetworkConnectionSectionType">
<ovf:Info>My Network Connection Section Info</ovf:Info>
<PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex>
<NetworkConnection network="CRMApplianceNetwork">
<NetworkConnectionIndex>0</NetworkConnectionIndex>
<IsConnected>true</IsConnected>
<IpAddressAllocationMode>DHCP</IpAddressAllocationMode>
</NetworkConnection>
</ovf:Section>
</ReconfigureItem>
</RecomposeVAppParams>

Note If a virtual machine referenced in a Source element is powered on or has an independent disk
attached, this operation will fail. You can use a query like this one to return a list of references to powered-
off virtual machines that you have access to.

[Link]

See Chapter 10, “Using the Query Service,” on page 365.

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ...
operation="Updating Virtual Application Example Corp’s CRM Appliance (33)" ...>
...
</Task>

VMware, Inc. 117

vCloud API Programming Guide for Service Providers

Clone a vApp
You can make a copy of a vApp by cloning it. If the vApp is deployed when you clone it, the clone
procedure also clones the memory state of the virtual machines in the vApp.

The cloneVApp request makes a copy of the vApp referenced in the Source element of the CloneVappParams
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 to delete the source vApp
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 or renames the vApp.

If the vApp is deployed when you clone it and the target VDC is backed by the same provider VDC as the
source VDC, the clone is created with the following properties:
n Memory state of all virtual machines in the source vApp is preserved in the clone.

n The clone is suspended and connected to an isolated network.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the XML representation of the VDC in which you want to deploy the cloned vApp.

Use a request like this one, where id is the identifier of the VDC:

GET [Link]

You can create the clone in the same VDC that holds the source vApp, or in a different VDC.

2 Examine the response to locate the Link element that contains the URL for cloning a vApp.

This element has a rel attribute value of add and a type attribute value of
application/[Link]+xml, as shown here:

<Link
rel="add"
type="application/[Link]+xml"
href="[Link]

3 Create a CloneVappParams element that references the vApp to clone and specifies details of the clone
operation.

See “Example: Clone a vApp,” on page 118.

4 POST the CloneVappParams element to the action/cloneVApp link of the VDC in which the clone should
be created.

Example: Clone a vApp

This request creates a copy of the vApp created in “Example: Instantiate a vApp Template and Modify
Virtual Machine Name, Description, and Storage Profile,” on page 106 in another VDC. Because the
ParentNetwork in the Source vApp is not available in the VDC specified in the action/cloneVApp request, the
CloneVAppParams request body must include InstantiationParams that specify a new ParentNetwork for the
vApp network, one that is available in the target VDC. The request also includes a SourcedItem specifying a
new storage profile for the virtual machine in the vApp.

Note If the vApp is deployed when you clone it, any network configuration you specify in the
CloneVAppParams is ignored and the clone is created with a connection to an isolated network.

118 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<CloneVAppParams
xmlns="[Link]
xmlns:ovf="[Link]
name="cloned"
deploy="false"
powerOn="false">
<Description>Cloned vApp Example</Description>
<InstantiationParams>
<NetworkConfigSection>
<ovf:Info>Configuration parameters for logical networks</ovf:Info>
<NetworkConfig networkName="vAppNetwork">
<Configuration>
<ParentNetwork href="[Link]
<FenceMode>bridged</FenceMode>
</Configuration>
</NetworkConfig>
</NetworkConfigSection>
</InstantiationParams>
<Source href="[Link]
<IsSourceDelete>false</IsSourceDelete>
<SourcedItem>
<Source href="[Link]
<StorageProfile href="[Link]
</StorageProfile>
</SourcedItem>
</CloneVAppParams>

The response is a sparsely populated VApp element in the target VDC. When the Task embedded in the
response is complete, the vApp has been cloned.

Response:

201 Created
Content-Type: application/[Link]+xml
...
<VApp
xmlns="[Link]
xmlns:ovf="[Link]
deployed="false"
status="0"
name="cloned"
type="application/[Link]+xml"
href="[Link]
...
<Link
rel="up"
type="application/[Link]+xml"
href="[Link]
...
<Description>Cloned vApp Example</Description>
...

VMware, Inc. 119

vCloud API Programming Guide for Service Providers

<Tasks>
<Task
status="running"
operation="Copying Virtual Application cloned (103)"
... >
</Task>
</Tasks>
...
</VApp>

Create a vApp From an OVF Package

An instantiateOvf request uploads an OVF package and then creates a vApp from it. By default, this
operation also deploys the vApp and powers it on.

If you want to deploy an OVF package as a vApp without creating a vApp template and corresponding
catalog item, make an instantiateOvf request. This request initiates a workflow similar to the one shown in
“Upload an OVF Package to Create a vApp Template,” on page 62, but with a few important differences.

n The target of the upload is a VDC, not a catalog.

n The request body is an InstantiateOvfParams element, not an UploadVAppTemplateParams element.

n The response is a VApp element that includes an upload URL for the OVF descriptor.

After you retrieve the VApp element created by the instantiateOvf request, you can upload the descriptor
and the files it references.

Prerequisites
Verify that the following are true:

n You have an OVF package to upload.

n You are logged in as a user who has permission to upload OVF packages and create vApps.

n You know the URL of the target VDC that will receive the upload. Retrieve the XML representation of
your organization to see a list of the VDCs that it contains.

Review the contents of the Envelope element in the descriptor file of your OVF package. Several properties
in this file have implications for the InstantiateOvfParams request body you must construct to initiate the
upload.

Procedure
1 Retrieve the XML representation of the target VDC.

2 Examine the response to locate the Link element that contains the URL for creating a vApp from an
OVF package.

This element has a rel attribute value of add and a type attribute value of
application/[Link]+xml, as shown here:

<Link
rel="add"
type="application/[Link]+xml"
href="[Link] />

3 Create an InstantiateOvfParams request body.

See the request portion of “Example: Create a vApp From an OVF Package,” on page 121.

4 POST the InstantiateOvfParams to the instantiateOvf URL you retrieved in Step 2

See the request portion of “Example: Create a vApp From an OVF Package,” on page 121.

120 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

5 Examine the response.

The response, a VApp element, contains a File element that specifies an upload URL for the OVF
descriptor. See the response portion of “Example: Create a vApp From an OVF Package,” on page 121

6 Upload the OVF descriptor.

Make a PUT request to the upload URL in the VApp. The upload URL for the OVF descriptor is in a Link
element with the following form:

<Link
rel="upload:default"
href="[Link] />

Supply the OVF descriptor as the request body. The OVF descriptor contains a single Envelope element.

7 Retrieve the remaining upload URLs

a Retrieve the VApp.

b Verify that the value of the ovfDescriptorUploaded attribute is true.

c Examine the VApp to find the upload URLs for the files referenced in the OVF descriptor.

These URLs are contained in Link elements where rel="upload:default".

8 Upload the referenced files.

You can follow the progress of the upload by retrieving the vApp and noting the progress of the
embedded Task.

After all of the referenced files are uploaded, the VApp element no longer includes an embedded Task. The
vApp is placed in the power and deployment state that the values of the powerOn and deploy attributes
specify in the request body.

Example: Create a vApp From an OVF Package

This request includes a NetworkMapping element that maps a network name found in the uploaded OVF
descriptor to the name of a network available in the target VDC.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<InstantiateOvfParams
xmlns:ovf="[Link]
xmlns="[Link]
name="W2K8">
<Description>Example vApp</Description>
<InstantiationParams>
<NetworkConfigSection>
<ovf:Info>Configuration parameters for logical networks
</ovf:Info>
<NetworkConfig
networkName="vAppNetwork">
<Configuration>
<ParentNetwork
href="[Link] />
<FenceMode>bridged</FenceMode>
</Configuration>
</NetworkConfig>

VMware, Inc. 121

vCloud API Programming Guide for Service Providers

</NetworkConfigSection>
</InstantiationParams>
<AllEULAsAccepted>true</AllEULAsAccepted>
<NetworkMapping>
<Source>Network 1</Source>
<Target>vAppNetwork</Target>
</NetworkMapping>
<InstantiateVmParams
id="VM-1">
<Name>VM-1</Name>
<NetworkConnectionSection>
<ovf:Info />
<PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex>
<NetworkConnection
network="Network 1">
<NetworkConnectionIndex>0</NetworkConnectionIndex>
<IsConnected>true</IsConnected>
<IpAddressAllocationMode>POOL</IpAddressAllocationMode>
</NetworkConnection>
</NetworkConnectionSection>
<ComputerName>W2K8</ComputerName>
</InstantiateVmParams>
</InstantiateOvfParams>

The response is a sparsely populated VApp element that includes an upload URL for the OVF descriptor. See
“Uploading Referenced Files,” on page 70 for file upload procedures.

Response:

201 Created
Content-Type: application/[Link]+xml
...
<VApp
xmlns="[Link]
xmlns:ovf="[Link]
deployed="false"
status="0"
name="W2K8"
type="application/[Link]+xml"
href="[Link]
<Link
rel="up"
type="application/[Link]+xml"
href="[Link]
<Description>Example vApp</Description>
<Link
rel="remove"
href="[Link] />
<Description>Example vApp</Description>
<Tasks>
<Task
status="running"
operation="Creating Virtual Application W2K8(23)"
... >
...
</Task>
</Tasks>

122 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

<Files>
<File
name="[Link]"
bytesTransferred="0">
<Link
rel="upload:default"
href="[Link] />
</File>
</Files>
<Owner>
...
</Owner>
<InMaintenanceMode>false</InMaintenanceMode>
</VApp>

Capture a vApp as a Template

You can capture a vApp to create a vApp template in a catalog. Instantiating the resulting template recreates
the vApp from which it was captured.

The captureVApp request creates a template based on the vApp referenced in the Source element of the
CaptureVAppParams request body. The request specifies a new name and, optionally, a new description and
storage profile for the template. If you want the new template to overwrite an existing template in the
catalog, you can specify a TargetCatalogItem in the request. Otherwise, the new template is stored in a new
catalog item.

If the vApp is deployed when you capture it, the template is created with the following properties.

n Memory state of all virtual machines in the source vApp is preserved in the template.

n Instantiating the template always creates a suspended vApp connected to an isolated network.

Note If the template is instantiated in a VDC that is not backed by the provider VDC that backed the VDC
in which the vApp was captured, memory state in the template is discarded on instantiation, and the vApp
is created with the network connections defined in the template or instantiation parameters.

Prerequisites
n This operation requires the rights included in the predefined Catalog Author role or an equivalent set of
rights.

n Verify that the target catalog does not have an external subscription.

Procedure
1 Retrieve the XML representation of the catalog to which to add the vApp template that the capture
creates.

Use a request like this one, where id is the identifier of the catalog:

GET [Link]

2 Examine the response to locate the Link element that contains the URL for capturing a vApp.

This element has a rel attribute value of add and a type attribute value of
application/[Link]+xml, as shown here:

<Link
rel="add"
type="application/[Link]+xml"
href="[Link]

VMware, Inc. 123

vCloud API Programming Guide for Service Providers

3 Create a CaptureVAppParams element that references the vApp to capture.

See “Example: Capture a vApp,” on page 124.

4 POST the CaptureVAppParams element to the action/captureVApp link shown in Step 2.

Example: Capture a vApp

This request captures the vApp created in “Example: Compose a vApp,” on page 112. Because the request
does not specify a TargetCatalogItem, a new catalog item is created for the new template.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<CaptureVAppParams
xmlns="[Link]
name="Example Corp’s CRM Appliance">
<Description>Captured CRM Appliance</Description>
<Source
href="[Link] />
</CaptureVAppParams>

The response is a sparsely populated VApp element in the target VDC. It contains a Link to the catalog
specified in the request. When the Task embedded in the response is complete, the vApp has been captured
and a vApp template created in the target catalog.

Response:

200 OK
Content-Type: application/[Link]+xml
...
<VAppTemplate
xmlns="[Link]
xmlns:ovf="[Link]
href="[Link]
...
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
...
<Description>Captured CRM Appliance</Description>
...
<Tasks>
<Task
...
operation="Capturing Virtual Application Template Example Corp’s CRM Appliance (232)"
...
</Task>
</Tasks>
...
</VAppTemplate>

124 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

Update vApp Access Controls

An administrator or the vApp owner can use the controlAccess links in a VApp element to grant or restrict
access to the vApp.

A vApp initially grants full access to its owner and no access to other users. The vCloud API access control
mechanism enables an administrator to retrieve or update vApp access controls to add or remove rights for
all users, or for individual users. For a general discussion of access controls in vCloud Director, see
“Controlling Access to vApps and Catalogs,” on page 91.

Prerequisites
Verify that you are logged in to the vCloud API as an administrator or the object owner.

Procedure
1 Retrieve the XML representation of the vApp.

Use a request like this one:

GET [Link]

2 Examine the VApp element to find the controlAccess links that it contains.

3 Create a ControlAccessParams element request body that specifies the details of the update.

4 POST the ControlAccessParams element to the action/controlAccess link that you retrieved in Step 1.

Example: Update vApp Access Controls

This request updates the access controls of a vApp to grant full control to one user and read-only access to
another user. The request body, a ControlAccessParams element, specifies a value of false for the
IsSharedToEveryone element, and contains an AccessSetting element for each user whose access rights are
being modified. Each user is identified by a reference to a User object. See “User and Group
Administration,” on page 241. The response, a subset of which appears in this example, echoes the request.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<ControlAccessParams
xmlns="[Link]
<IsSharedToEveryone>false</IsSharedToEveryone>
<AccessSettings>
<AccessSetting>
<Subject
type="application/[Link]+xml"
href="[Link]
<AccessLevel>FullControl</AccessLevel>
</AccessSetting>
<AccessSetting>
<Subject
type="application/[Link]+xml"
href="[Link]
<AccessLevel>ReadOnly</AccessLevel>
</AccessSetting>
</AccessSettings>
</ControlAccessParams>

VMware, Inc. 125

vCloud API Programming Guide for Service Providers

Response:

200 OK
Content-Type: application/[Link]+xml
...
<ControlAccessParams
xmlns="[Link]
<IsSharedToEveryone>false</IsSharedToEveryone>
<AccessSettings>
...
</AccessSettings>
</ControlAccessParams>

Create a VM-VM Affinity Rule

A VM-VM affinity rule applies to two or more virtual machines and specifies whether they should be
deployed on the same host or on separate hosts. VM-VM affinity rules are properties of an organization
VDC, and apply to virtual machines deployed on the hosts that back that VDC.

VM-VM affinity rules are user-specified constraints that the system considers during the deployment
process. There are two types, or polarities, of VM-VM affinity rules:

n A rule with a Polarity value of Affinity specifies two or more virtual machines that the system should
deploy on the same host. This kind of rule is commonly applied in cases where virtual machines can
realize performance benefits from being placed on a single host and are running workloads where
failure of that host can be tolerated.

n A rule with a Polarity value of Anti-Affinity specifies two or more virtual machines that the system
should deploy on separate hosts. This kind of rule is commonly applied in cases where virtual
machines are intended to support redundancy, availability, and similar uses that must not be affected by
the failure of one host.

You can make an affinity rule mandatory to provide a hint to the system that the deployment should fail
unless the specified placement objective can be achieved. When a virtual machine is the subject of a
mandatory affinity rule, placement requirements dictated by the rule override any placement changes that
might be initiated by vSphere services such as High Availability and Storage DRS.

When you create a VM-VM affinity rule in an organization VDC, vCloud Director creates a corresponding
rule in the vCenter server that provides resources to that organization VDC. This rule has several differences
compared with a VM-VM affinity rule created directly in vCenter:

n A virtual machine can be referenced in no more than one vCloud Director affinity rule.

n A virtual machine can be referenced in no more than one vCloud Director anti-affinity rule.

When you create a vCloud Director affinity rule, the system validates that it does not reference a virtual
machine that is already referenced by an existing rule of the same polarity. Requests that attempt to create a
rule that would violate this constraint are rejected.

Prerequisites
n This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

n To create an affinity rule, you must be the owner of all virtual machines specified in the rule.

Procedure
1 Retrieve the XML representation of the organization VDC to which you want to add the affinity rule.

This request retrieves the user view of an organization VDC.

GET [Link]

126 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

2 Examine the response to locate the Link element that contains the URL for adding affinity rules to the
VDC.

This element has a rel attribute value of add and a type attribute value of
application/[Link]+xml, as shown here:

<Link
rel="add"
href="[Link]
type="application/[Link]+xml" />

3 Retrieve references to the virtual machines that will be subject to the rule.

The references must be to virtual machines that have been instantiated in the same VDC. You can use a
query like this one to list references to all the virtual machines instantiated in a VDC whose URL is vdc-
reference.

GET [Link]
type=vm&format=references&\
filter=isVAppTemplate==false&vdc==vdc-reference

For example:

GET [Link]
type=vm&format=references&\
filter=isVAppTemplate==false&vdc==[Link]

4 Create a VmAffinityRule request body.

The name element cannot contain more that 40 characters. See “Example: Create a VM-VM Affinity
Rule,” on page 127.

5 POST the VmAffinityRule element you created in Step 4 to the URL for adding affinity rules the
organization VDC.

See the request portion of “Example: Create a VM-VM Affinity Rule,” on page 127.

Example: Create a VM-VM Affinity Rule

This request creates an affinity rule for two virtual machines.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<VmAffinityRule xmlns="[Link]
<Name>example-affinity-rule</Name>
<IsEnabled>true</IsEnabled>
<Polarity>Affinity</Polarity>
<VmReferences>
<VmReference href="[Link] />
<VmReference href="[Link] />
</VmReferences>
</VmAffinityRule>

If either of the referenced virtual machines is already the subject of an affinity rule, the request fails with an
error message indicating the reason for the failure.

The response is a Task. Note the href of the Owner element in the returned Task. This is the ID of the rule.
You must use it when you delete or update the rule.

VMware, Inc. 127

vCloud API Programming Guide for Service Providers

Response:

<?xml version="1.0" encoding="UTF-8"?>

<Task
...
operationName="affinityRuleCreate"
... >
<Owner
href="[Link]
name="example_name"
type="application/[Link]+xml" />
...
</Task>

Note When you create or update an anti-affinity rule, the system might need to create a place-holder
virtual machine to satisfy the vCenter requirement that such rules include at least two virtual machines. This
place-holder is visible to vCenter administrators, but is not visible in vCloud Director. It is never powered
on.

Update or Delete a VM-VM Affinity Rule

To update or remove an affinity rule, use the edit and remove links in the rule.

Prerequisites
n This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

n To update or delete an affinity rule, you must be the owner of all virtual machines specified in the rule.

n To update or remove the rule, you must know the href value of the rule. This value is returned when
you create the rule (see “Example: Create a VM-VM Affinity Rule,” on page 127). You can retrieve a list
of all your affinity rules from a VDC by making a GET request to this link in the VDC.

<Link rel="down" href="[Link]

type="application/[Link]+xml"/>

Procedure
1 Retrieve the XML representation of the rule.

Use a request like this one.

GET [Link]

2 Examine the response to locate the Link elements that contain the URLs for modifying or deleting the
rule.

<VmAffinityRule ...>
...
<Link
rel="edit"
href="[Link]
type="application/[Link]+xml" />
<Link
rel="remove"
href="[Link] />
...
</VmAffinityRule>

128 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

3 Use one of these links to update or delete the rule.

Option Description
To update the rule: Make a PUT request to the rule's edit URL and supply a VmAffinityRule
as the body. See “Example: Update a VM-VM Affinity Rule,” on page 129.
To delete the rule: Make a DELETE request to the rule's remove URL.

Example: Update a VM-VM Affinity Rule

This request updates the an affinity rule created in “Example: Create a VM-VM Affinity Rule,” on page 127
to add a third virtual machine.
Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<VmAffinityRule xmlns="[Link]
<Name>example-affinity-rule</Name>
<IsEnabled>true</IsEnabled>
<Polarity>Affinity</Polarity>
<VmReferences>
<VmReference href="[Link] />
<VmReference href="[Link] />
<VmReference href="[Link] />
</VmReferences>
</VmAffinityRule>

The response is a Task.

Response:

<?xml version="1.0" encoding="UTF-8"?>

<Task
...
operationName="affinityRuleUPdate"
... >
<Owner
href="[Link]
name="example_name"
type="application/[Link]+xml" />
...
</Task>

Using Metadata to Control Virtual Machine Placement

If your system administrator has enabled custom configurations of ESXi hosts in a resource pool that backs a
VDC in your organization, you can apply object metadata in the VCENTER domain to virtual machines
configured to exploit the special properties of those hosts. The system uses that metadata to place the virtual
machines on the appropriate hosts.

You can create virtual machines with workload-specific configurations that require placement on hosts that
have certain characteristics. The technical white paper Best Practices for Performance Tuning of Telco and NFV
Workloads in vSphere
([Link] provides
several examples of virtual machine configurations that require specific host properties.

VMware, Inc. 129

vCloud API Programming Guide for Service Providers

Because members of vCloud Director organizations do not typically have control over ESXi host
configurations, administrators of the vCenter clusters that provide resource pools for organization VDCs
must configure the hosts and apply vSphere custom attributes to indicate how they are configured.
Organization members apply vCloud Director object metadata based on those custom attributes to virtual
machines that require a host with a specific configuration.

Specifying Advanced Virtual Machine Settings with ExtraConfig Elements

OVF ExtraConfig elements provide a flexible way of including key=value pairs in the configuration of a
virtual machine. The keys and values are interpreted by the system when the virtual machine is deployed,
and can be used specify a variety of virtual machine properties. The XML fragment in “Example: Applying
ExtraConfig Values and VCENTER Metadata to a Virtual Machine,” on page 132 shows how you can
include an ExtraConfig element in the VirtualHardwareSection of a Vm.

The vCloud API supports several ExtraConfig key=value pairs that you can use to configure virtual machines
for specific types of workloads. You can use OVFtool to create an OVF package that includes virtual
machines with these ExtraConfig values.

Permission to upload or download a Vm that includes any of these keys requires one or more of the following
rights.

Table 5‑2. ExtraConfig Keys, Values, and Required Rights

Key Values Required Right Description

any key any value vApp: Preserve All A user with this right can
ExtraConfig Elements During upload or download an
OVF Import and Export OVF package that
contains an unlimited set
of ExtraConfig key=value
pairs. The set includes, but
is not limited to, the pairs
listed in this table.

any key that is a value of any value vApp: Allow Matching Extra A user with this right can
the Config upload or download an
[Link] OVF package that
nfig system contains any of the
configuration property ExtraConfig key=value
pairs in which the key is a
value of the
[Link]
nfig system configuration
property. See VMware
Knowledge Base article
[Link]
b/2148573.

[Link] high, normal (default) vApp: Preserve Latency Set to high for virtual
itivity ExtraConfig Elements During machines running latency-
OVF Import and Export sensitive workloads.

[Link] enabled, disabled vApp: Preserve Ethernet- Set to enabled and

cheme (default) Coalescing ExtraConfig specify the virtual NICs
(where n is the number of Elements During OVF Import that must disable
the virtual NIC in the and Export interrupt coalescing.
range 0-9)

[Link] n, ..., where n is a NUMA vApp: Preserve NUMA Node Constrains the set of
node number on the Affinity ExtraConfig NUMA nodes on which a
host. Elements During OVF Import virtual machine's virtual
and Export CPU and memory can be
scheduled.

130 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

For detailed information about the effects of these settings, see Best Practices for Performance Tuning of Telco
and NFV Workloads in vSphere
([Link] For
information about using the vCloud API to add rights to a role, see “Create a Role in Your Organization,” on
page 263.

Using vSphere Custom Attributes to Indicate Host Configurations

Administrators of vCenter clusters that provide resource pools for organization VDCs must apply vSphere
custom attributes to indicate how ESXi hosts in those clusters have been configured. To apply vSphere
custom attributes to a host, you must use the vSphere Client, vSphere API, or vSphere PowerCLI. The
vSphere Web Client does not support viewing or modifying vSphere custom attributes. For more
information about vSphere custom attributes, see
[Link]
[Link].

When used for controlling virtual machine placement in vCloud Director, vSphere custom attribute names
must have the form [Link], where tag is an arbitrary string that the cluster administrator has
chosen. Within this constraint, cluster administrators are free to decide how custom attribute names and
values indicate host capabilities. Cluster administrators must provide vCloud Director administrators with
the following information, which users need to use when configuring virtual machines that must be placed
on specific hosts.

n Which VDCs are configured with resource pools that includes these hosts.

n What vSphere custom attributes have been applied to indicate specific host configurations.

n How custom attributes and their values indicate support for virtual machine ExtraConfig settings. See
“Example: Applying ExtraConfig Values and VCENTER Metadata to a Virtual Machine,” on page 132.

How vCloud Director Object Metadata Affects Virtual Machine Placement

In addition to using ExtraConfig elements to configure a virtual machine for a workload that requires a
specific host configuration, you must apply vCloud Director object metadata in the VCENTER domain to that
virtual machine. When this object metadata matches a vSphere custom attribute and value applied to a host
by a vSphere administrator, the system deploys the virtual machine to that host.

Changing the value of vCloud Director object metadata in the VCENTER domain does not change the value of
any vSphere custom attributes applied to hosts in a resource pool backing your VDC. A virtual machine to
which you have applied vCloud Director object metadata in the VCENTER domain cannot be deployed unless
the metadata key and value match a vSphere custom attribute name and value on at least one host in a
resource pool that backs your VDC. If you change this metadata so that the key and value applied to the
virtual machine do not match a vSphere custom attribute name and value on at least one host in a resource
pool that backs your VDC, the virtual machine can never be powered on. In this case, the best practice is to
delete the virtual machine and recreate it with the correct metadata.

For more information about vCloud Director object metadata and the VCENTER metadata domain, see
Chapter 9, “Working With Object Metadata,” on page 357.

Important When you apply object metadata in the VCENTER domain to a virtual machine that is also a
subject of a vCloud Director affinity rule, make sure that the rule is compatible with the placement
requirements specified by the metadata. For example, if your organization VDC has only a single host with a
specific vSphere custom attribute name and value and you create two virtual machines with object metadata
derived from that name and value, placing those virtual machines in an anti-affinity rule causes a conflict
with the placement advice implied by the metadata.

VMware, Inc. 131

vCloud API Programming Guide for Service Providers

Example: Applying ExtraConfig Values and VCENTER Metadata to a Virtual

Machine
This example assumes that a vSphere administrator has configured one or more hosts to support latency-
sensitive workloads, as described in Best Practices for Performance Tuning of Telco and NFV Workloads in vSphere
([Link] At least
one of the hosts must be in cluster that provides a resource pool that backs a VDC in your organization.

1 As a vSphere administrator, use the vSphere Client, vSphere API, or vSphere PowerCLI to create
vSphere custom attributes and apply them to the ESXi hosts configured to support latency-sensitive
workloads,.

n Define a vSphere custom attribute of type Host that has the name [Link]-HOST-CONFIG.

n Define a vSphere custom attribute of type Vm that has the name [Link]-HOST-CONFIG.

n Set the value of this field to VCD-VM-LATENCY-SENSITIVITY-HIGH on at least one host in a cluster that
provides a resource pool that backs a VDC to be used for metadata-based placement.

2 Use OVFtool to create an OVF package that contains a VirtualHardwareSection with an ExtraConfig
setting like this one:.

<?xml version="1.0" encoding="UTF-8"?>

<Vm ...>
...
<ovf:VirtualHardwareSection
xmlns:vcloud="[Link]
ovf:transport="">
<ovf:Info>Virtual hardware requirements</ovf:Info>
<vmw:ExtraConfig
ovf:required="false"
vmw:key="[Link]"
vmw:value="high" />
...
</ovf:VirtualHardwareSection>
...
</Vm>

3 Log in to vCloud Director as a user whose role includes the right vApp: Preserve Latency ExtraConfig
Elements During OVF Import and Export and upload the OVF package you created in Step 2.

4 Log in to the vCloud API as a user whose role includes the right vApp: Allow metadata mapping domain
to vCenter and make a request like this one to apply metadata to the Vm you defined in Step 2. Use the
name of the custom attribute as the metadata Key, and the value of the custom attribute as the metadata
Value.

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Metadata ... >
<MetadataEntry
...
<Domain
visibility="READWRITE">VCENTER</Domain>
<Key>[Link]-HOST-CONFIG</Key>
<TypedValue
xsi:type="MetadataStringValue">

132 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

<Value>VCD-VM-LATENCY-SENSITIVITY-HIGH</Value>
</TypedValue>
</MetadataEntry>
</Metadata>

Note Object metadata in the VCENTER domain is not displayed in the vCloud Director Web Console.

5 Deploy the virtual machine to a VDC that is backed by a resource pool containing one or more of the
hosts that were configured in Step 1. The system will place the virtual machine on one of those hosts.

To verify that the VDC you are using is backed by a resource pool containing the necessary host
configurations, check with an organization administrator or your system administrator. Your vSphere
administrator can provide the vCenter managed object reference of the cluster that contains the hosts,
as well as the key and value names of the vSphere custom attributes that were applied to these hosts.
Any organization VDC is backed by a Provider VDC that includes one of these resource pools (which
are identified in the vCloud API by the value of a MoRef element) can support metadata-based
placement of a virtual machine.

Operate a vApp
vApp and Vm elements include a number of action links. You can use these links to operate a vApp or one of
its virtual machines by making requests such as power on, suspend, power off, undeploy, and so on.

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. Some requests apply only to
vApps, some apply only to virtual machines (Vm objects), and some apply to both.

n A request made to the power URL of a VApp 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 contained by the Children element). 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.

n A request made to the power URL of a Vm affects only that virtual machine.

Prerequisites
This operation requires the rights included in the predefined vApp User role or an equivalent set of rights.

Procedure
1 Retrieve the XML representation of the vApp to find the action links it contains.

Use a request like this one:

GET [Link]

2 POST a request to the URL that implements the desired action.

Many of these requests do not require a body.

The server takes the requested action and returns a Task element that tracks the progress of the request.

VMware, Inc. 133

vCloud API Programming Guide for Service Providers

vApp Power States

Operations that change the power state of a vApp or any of its VMs can have different results when initiated
from the vCloud API than they do when initiated from the vCloud Director Web Console. Understanding
these state transitions and the operations that cause them can help you manage vApp and VM resource
consumption and readiness.

As seen in the vCloud Director Web Console, a vApp can be Stopped, Running, or Partially Running. A VM
can have any of the following states:

n Powered Off

n Powered On

n Suspended

n Partially Powered On (deployed

n Partially Suspended (deployed)

The vCloud API returns information about VM power state in the Vm object’s status attribute:

Table 5‑3. VM Power States and status Attribute Values

VM Power State Vm Object status attribute value

Powered on 4

Powered off 8

Suspended 3

This simplified diagram covers most of the cases where a vApp contains a single VM. A vApp that contains
multiple VMs can report its power state as Partially Running in the vCloud Director Web Console when
some VMs are powered on and some are not.

134 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

Figure 5‑2. vApp Power State Transitions

Legend:
API-instantiate-vapp-from-catalog UI-add-vapp-from-catalog UI
API
vApp: “Stopped”
VM: “Powered Off”

API-undeploy deployed=false API-vm-deploy

API-shutdown status=8 API-vm-power-off

API-vm-power-on UI-vm- UI-vm-

API-vm-deploy power-on power-off

vApp: “Running” API-vm-suspend

VM: “Powered On”

deployed=true
status=4

UI-vm- API-vm- API-vm-

power-on power-on power-off

vApp: “Partially Running” UI-vm-

VM: “Powered Powered Off” resume

deployed=true
status=8 vApp: “Partially Running”
VM: “Partially Suspended”

API-vm-discard-state deployed=true
status=3
vApp: “Stopped”
VM: “Suspended”
UI-vm-suspend API-vm-power-on
deployed=true
status=3

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 that you can GET to
discover what input is needed.

Prerequisites
This operation requires the rights included in the predefined vApp User role or an equivalent set of rights.

Procedure
1 Find the question link in the target vApp.

This link has the following form:

<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />

2 Make a GET request to the URL in that link's href value.

The response is a VmPendingQuestion response that includes the question and the set of possible
answers.

VMware, Inc. 135

vCloud API Programming Guide for Service Providers

3 Create a VmQuestionAnswer element that supplies the answer.

See “Example: Provide User Input Requested by a Virtual Machine,” on page 136.

4 POST the element to the question/action/answer link included in the VmPendingQuestion response.

Example: Provide User Input Requested by a Virtual Machine

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.

The first step is to use the vmPendingQuestion link, shown in Step 1, to get a VmPendingQuestion response that
includes the question and the set of possible answers.

Request:

GET [Link]

Response:

200 OK
Content-type: application/[Link]+xml
...
<VmPendingQuestion
xmlns="[Link]
<Link
rel="answer"
type="application/[Link]+xml"
href="[Link] />
<Question>[Link]:Parallel port output file
"/vmfs/volumes/d6162a46-58e50cab/linuxftp/[Link]" 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>

To supply the answer, POST a VmQuestionAnswer element to the question/action/answer link of the Vm.

Request:

POST [Link]
Content-type: application/[Link]+xml
<?xml version="1.0" encoding="UTF-8"?>
<VmQuestionAnswer

136 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

xmlns="[Link]
<ChoiceId>2</ChoiceId>
<QuestionId>50</QuestionId>
</VmQuestionAnswer>

Creating and Using vApp Snapshots

You can take a snapshot of all the virtual machines in a vApp. After the snapshots are taken, you can revert
all virtual machines in the vApp to the most recent snapshot, or remove all snapshots.

You can take a snapshot of a vApp whether or not it is powered on. The createSnapshot operation always
creates a snapshot for each virtual machine in the vApp. Snapshots are created in the order specified for
virtual machines in the StartupSection of the VApp element.

vApp snapshots have the following limitations:

n They do not capture the ovf:ProductSection elements in the vApp.

n They do not capture NIC configurations.

n They cannot be created if any virtual machine in the vApp is connected to an independent disk.

Prerequisites
n This operation requires the rights included in the predefined vApp User role or an equivalent set of
rights.

n You must be the owner of the object that this operation affects.

Procedure
1 (Optional) Retrieve information about current vApp snapshots.

When you create a snapshot, it overwrites any existing snapshots without warning. Before creating a
new snapshot, you might want to verify whether there are any existing snapshots. Make a request like
this one:

GET [Link]

The response is a SnapshotSection element containing a link to each of the current snapshots for the
vApp.

2 Create a CreateSnapshotParams request body.

See “Example: Create a vApp Snapshot,” on page 137.

3 POST the CreateSnapshotParams to the action/createSnapshot link of the vApp.

Example: Create a vApp Snapshot

In this example, the memory and quiesce options are not specified, so their values default to true. The name
attribute is optional. If you omit it from the request, the system generates a name for the snapshot.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<CreateSnapshotParams
xmlns="[Link]
name="snap1">
<Description>Demo snapshot</Description>
</CreateSnapshotParams>

VMware, Inc. 137

vCloud API Programming Guide for Service Providers

The response is a Task.

Response:

<?xml version="1.0" encoding="UTF-8"?>

<Task
...
operationName="vappCreateSnapshot"
... />
...
</Task>

After the snapshot is created, you can revert the vApp to the state captured in the snapshot.

POST [Link]

You can also remove all snapshots.

POST [Link]

Neither of these requests has a request body. Both return a Task.

Attach or Detach an Independent Disk

Use the disk/action/attach or disk/action/detach links in a Vm to attach or detach an independent disk.
You must be the owner of the Vm object and the disk.

Every Vm element includes links of the following form:

<Link
rel="disk:attach"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="disk:detach"
type="application/[Link]+xml"
href="[Link] />

You can POST a DiskAttachOrDetachParams element to one of these URLs to attach or detach an independent
disk.

Note An independent disk can be attached to at most one virtual machine.

Prerequisites
n Verify that you are logged in to the vCloud API as an administrator or the object owner.

n Verify that the VDC contains an independent disk. If the VDC does not contain independent disks, you
can create one. See “Create an Independent Disk,” on page 85.

Procedure
1 Retrieve a reference to the independent disk to attach to a virtual machine.

The independent disk and the virtual machine must be contained by the same VDC. You can retrieve
references to independent disks in a VDC in the following ways:

n Use the query service. A query like this one returns references to all Disk objects in the VDC named
MyVdc.

GET [Link]
type=disk&format=references&filter=vdcName==MyVdc

138 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

n Retrieve the VDC and look for ResourceEntity elements whose type attribute has a value of
application/[Link]+xml. The href value of a ResourceEntity that represents a
disk is a reference to that Disk object.

2 Verify that the independent disk is not connected to any virtual machine.

3 Create a DiskAttachOrDetachParams element.

Provide a reference to the independent disk in the href attribute of the Disk element.

4 POST the DiskAttachOrDetachParams to the disk/action/attach link of the Vm.

Example: Attach an Independent Disk to a Virtual Machine

This request attaches the disk created in “Create an Independent Disk,” on page 85 to a virtual machine.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<DiskAttachOrDetachParams
xmlns="[Link]
<Disk
type="application/[Link]+xml"
href="[Link] />
</DiskAttachOrDetachParams>

The response is a Task.

Response:

<Task
href="[Link]
...
status="running"
operationName="vappAttachDisk"
... />
...
</Task>

About Virtual Machine Metrics

Virtual machine metrics provide information about a virtual machine's performance and resource
consumption in several categories.

vCloud Director collects metrics for all running virtual machines. You can retrieve virtual machine metrics
either as an instantaneous reading taken when the request is made, or as a collection of historic readings
taken at regular intervals. Historic metrics are retained for 14 days, and can be retrieved whether or not the
virtual machine is powered on.

The following categories of metrics are collected:

cpu Virtual CPU usage metrics. CPU metrics are an aggregate of all the virtual
machine's cores and sockets.

disk Virtual hard disk capacity and performance metrics. When a virtual machine
has multiple disks, metrics are reported as an aggregate for all disks.

mem Virtual machine memory usage.

VMware, Inc. 139

vCloud API Programming Guide for Service Providers

For historic and current metrics, you can make a GET request to retrieve all categories of metrics from a
virtual machine. A GET request for historic metrics returns only the most recent 24 hours of metric data
samples. You can also make a POST request with a body that constrains the response to a subset of current
or historic metrics in any or all categories. A POST request for historic metrics can specify a time period of
up to 14 days.

Important To support retrieval of historic metrics, vCloud Director must be configured with additional
database software dedicated to historic metrics collection. See the vCloud Director Installation and Upgrade
Guide.

Metrics Links in a Vm Element

When a virtual machine is powered on, the Vm element that represents it includes four links where the value
of the type attribute has the form application/[Link].*[Link].

<Vm ... >

...
<Link
rel="down"
href="[Link]
type="application/[Link]+xml"/>
<Link
rel="down"
href="[Link]
type="application/[Link]+xml"/>
<Link
rel="metrics"
href="[Link]
type="application/[Link]+xml"/>
<Link
rel="metrics"
href="[Link]
type="application/[Link]+xml"/>
...
</Vm>

n Use the links where rel="down" with a GET request to retrieve current or historic metrics in all
categories.

n Use the links where rel="metrics" with a POST request to retrieve a subset of current or historic
metrics.

When a virtual machine is powered off, you cannot retrieve current metrics from it, so
the .../metrics/current links are not returned in the Vm element.

Negative Values for Current Metrics

Current metrics can be returned with negative values if the specific metric being requested does not have a
valid current value. This condition can exist if you make a metrics request before the first collection interval
for that metric elapses. For example, a request for CPU usage metrics made shortly after a virtual machine is
powered on can report negative values.

140 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

Retrieving All Current or Historic Metrics

You can make a GET request to either of the metrics links in a Vm object to retrieve all current or historic
metrics.

Current metrics are instantaneous values collected at the time the request is processed by the server. A GET
request for current metrics retrieves a list of current metric values, one for each category, and returns it as a
single XML document. You can retrieve a subset of current metrics by making a POST request with a
CurrentUsageSpec body.

Historic metrics are collected and stored for 14 days. A GET request for historic metrics retrieves the past 24
hours of metric history and returns it as a single XML document. In the typical case, this document contains
thousands of lines. You can retrieve a subset of historic metrics by making a POST request with a
HistoricUsageSpec body.

Prerequisites
This operation requires the rights included in the predefined vApp User role or an equivalent set of rights.

Procedure
1 Retrieve the XML representation of the virtual machine.

Use a request like this one:

GET [Link]

2 Examine the Vm element to find the metrics links that it contains.

These links have the following form, where id is the virtual machine's unique identifier:

<Link
rel="down"
type="application/[Link]+xml"
href="[Link]
<Link
rel="down"
type="application/[Link]+xml"
href="[Link]

3 Make a GET request to the appropriate link.

Option Request
Retrieve all current metrics GET [Link]
Retrieve all historic metrics for the GET [Link]
past 24 hours

See “Example: Retrieving All Current or Historic Metrics,” on page 141

Example: Retrieving All Current or Historic Metrics

This request retrieves all current metrics from a virtual machine.

Request

GET [Link]

Response

200 OK
Content-Type: application/[Link]+xml
...
<CurrentUsage

VMware, Inc. 141

vCloud API Programming Guide for Service Providers

xmlns="[Link]
... >
<Link
rel="up"
href="[Link]
type="application/[Link]+xml"/>
<Metric
name="[Link]"
unit="PERCENT"
value="33.7"/>
<Metric
name="[Link]"
unit="PERCENT"
value="89.0"/>
<Metric
name="[Link]"
unit="MEGAHERTZ"
value="262.0"/>
<Metric
name="[Link]"
unit="PERCENT"
value="44.0"/>
<Metric
name="[Link]"
unit="KILOBYTE"
value="2190418.0"/>
<Metric
name="[Link]"
unit="KILOBYTES_PER_SECOND"
value="20.0"/>
<Metric
name="[Link]"
unit="KILOBYTE"
value="1633362.0"/>
<Metric
name="[Link].0"
unit="KILOBYTES_PER_SECOND"
value="44.0"/>
<Metric
name="[Link]"
unit="KILOBYTES_PER_SECOND"
value="44.0"/>
</CurrentUsage>

This request retrieves the past 24 hours of metrics from a virtual machine. The typical response contains
thousands of lines, so only a subset appears here.

Request

GET [Link]

Response

200 OK
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<HistoricUsage xmlns="[Link]

142 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

<Link
rel="up"
href="[Link]
type="application/[Link]+xml"/>
<MetricSeries
expectedInterval="1800"
name="[Link]"
unit="KILOBYTE">
<Sample
timestamp="2013-12-02T[Link].000Z"
value="875295.0"/>
<Sample
timestamp="2013-12-02T[Link].000Z"
value="741388.0"/>
</MetricSeries>
<MetricSeries
expectedInterval="300"
name="[Link]"
unit="MEGAHERTZ">
<Sample
timestamp="2013-12-02T[Link].000Z"
value="505.0"/>
<Sample
timestamp="2013-12-02T[Link].000Z"
value="122.93333333333334"/>
<Sample ... />
</MetricSeries>
<MetricSeries
expectedInterval="300"
name="[Link]"
unit="KILOBYTES_PER_SECOND">
<Sample
timestamp="2013-12-02T[Link].000Z"
value="208.7"/>
<Sample
timestamp="2013-12-02T[Link].000Z"
value="0.0"/>
<Sample ... />
</MetricSeries>
<MetricSeries
expectedInterval="300"
name="[Link]"
unit="PERCENT">
<Sample
timestamp="2013-12-02T[Link].000Z"
value="55.26272895119407"/>
<Sample
timestamp="2013-12-02T[Link].000Z"
value="47.19066823323568"/>
<Sample ... />
</MetricSeries>
<MetricSeries
expectedInterval="300"
name="[Link]"
unit="PERCENT">

VMware, Inc. 143

vCloud API Programming Guide for Service Providers

<Sample
timestamp="2013-12-02T[Link].000Z"
value="24.07100028991699"/>
<Sample
timestamp="2013-12-02T[Link].000Z"
value="5.87066666285197"/>
<Sample ... />
</MetricSeries>
<MetricSeries
expectedInterval="1800"
name="[Link]"
unit="KILOBYTE">
<Sample
timestamp="2013-12-02T[Link].000Z"
value="262154.0"/>
<Sample
timestamp="2013-12-02T[Link].000Z"
value="373779.0"/>
</MetricSeries>
<MetricSeries
expectedInterval="300"
name="[Link]"
unit="KILOBYTES_PER_SECOND">
<Sample
timestamp="2013-12-02T[Link].000Z"
value="30.3"/>
<Sample
timestamp="2013-12-02T[Link].000Z"
value="0.5333333333333333"/>
<Sample ... />
</MetricSeries>
<MetricSeries
expectedInterval="300"
name="[Link]"
unit="PERCENT">
<Sample
timestamp="2013-12-02T[Link].000Z"
value="24.07100028991699"/>
<Sample
timestamp="2013-12-02T[Link].000Z"
value="5.87066666285197"/>
<Sample ... />
</MetricSeries>
</HistoricUsage>

Retrieving Metrics Subsets

To retrieve a subset of current or historic metrics, make a POST request to a current or historic metrics URL.
The request body specifies the metrics you want.

The vCloud API defines two request bodies, CurrentUsageSpec and HistoricUsageSpec, that you can use to
constrain a metrics request to a subset of available metrics. With these request bodies, you can specify
metrics by name, or supply a pattern that uses a wildcard to match a set of names. You can also specify a
collection interval for historic metrics. See “Metric Names and Patterns,” on page 148.

144 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

Prerequisites
This operation requires the rights included in the predefined vApp User role or an equivalent set of rights.

Procedure
1 Retrieve the XML representation of the virtual machine.

Use a request like this one:

GET [Link]

2 Examine the Vm element to find the metrics links where rel="metrics".

These links have the following form, where id is the virtual machine's unique identifier:

<Link
rel="metrics"
type="application/[Link]+xml"
href="[Link]
<Link
rel="metrics"
type="application/[Link]+xml"
href="[Link]

3 Create the appropriate request body.

The request body specifies the metrics you want.

Option Request
Retrieve a subset of current metrics Create a CurrentUsageSpec element to use as the request body.
Retrieve a subset of historic metrics Create a HistoricUsageSpec element to use as the request body.

4 POST the request body to the appropriate metrics link.

See “Example: Retrieving a Subset of Current or Historic Metrics,” on page 145

Note If you do not include a request body, the request is processed as though you had made a GET
request.

Example: Retrieving a Subset of Current or Historic Metrics

This example uses a POST request with a CurrentUsageSpec body to request a subset of the current metrics
retrieved in “Example: Retrieving All Current or Historic Metrics,” on page 141. This example also shows
the use of wildcards in a MetricPattern element. See “Metric Patterns,” on page 149.

Request

POST [Link]
Content-type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<CurrentUsageSpec xmlns="[Link]
<MetricPattern>*.average</MetricPattern>
</CurrentUsageSpec>

Response

200 OK
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>

VMware, Inc. 145

vCloud API Programming Guide for Service Providers

<CurrentUsage
xmlns="[Link]
<Link
rel="up"
href="[Link]
type="application/[Link]+xml"/>
<Metric
name="[Link]"
unit="PERCENT"
value="5.36"/>
<Metric
name="[Link]"
unit="MEGAHERTZ"
value="112.0"/>
<Metric
name="[Link]"
unit="PERCENT"
value="2.99"/>
<Metric
name="[Link]"
unit="KILOBYTES_PER_SECOND"
value="0.0"/>
<Metric
name="[Link]"
unit="KILOBYTES_PER_SECOND"
value="0.0"/>
</CurrentUsage>

This example uses a POST request with a HistoricUsageSpec body to request a subset of the historic metrics
retrieved in “Example: Retrieving All Current or Historic Metrics,” on page 141. This example also shows
the use of wildcards and a time specification for the past 8 hours.

Request

POST [Link]
Content-type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<HistoricUsageSpec xmlns="[Link]
<RelativeStartTime
interval="8"
unit="hour"/>
<RelativeEndTime
interval="0"
unit="hour"/>
<MetricPattern>cpu.*</MetricPattern>
<MetricPattern>disk.*</MetricPattern>
</HistoricUsageSpec>

The full response contains several thousand lines, so only a subset appears here.

Response

200 OK
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<HistoricUsage

146 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

xmlns="[Link]
<Link
rel="up"
href="[Link]
type="application/[Link]+xml"/>
<MetricSeries
expectedInterval="1800"
name="[Link]"
unit="KILOBYTE">
<Sample
timestamp="2013-12-02T[Link].000Z"
value="875295.0"/>
<Sample
timestamp="2013-12-02T[Link].000Z"
value="741388.0"/>
</MetricSeries>
<MetricSeries
expectedInterval="300"
name="[Link]"
unit="MEGAHERTZ">
<Sample
timestamp="2013-12-02T[Link].000Z"
value="505.0"/>
<Sample
timestamp="2013-12-02T[Link].000Z"
value="122.93333333333334"/>
<Sample/>
</MetricSeries>
<MetricSeries
expectedInterval="300"
name="[Link]"
unit="KILOBYTES_PER_SECOND">
<Sample
timestamp="2013-12-02T[Link].000Z"
value="208.7"/>
<Sample
timestamp="2013-12-02T[Link].000Z"
value="0.0"/>
<Sample ... />
</MetricSeries>
<MetricSeries
expectedInterval="300"
name="[Link]"
unit="PERCENT">
<Sample
timestamp="2013-12-02T[Link].000Z"
value="55.26272895119407"/>
<Sample
timestamp="2013-12-02T[Link].000Z"
value="47.19066823323568"/>
<Sample ... />
</MetricSeries>
<MetricSeries
expectedInterval="300"
name="[Link]"

VMware, Inc. 147

vCloud API Programming Guide for Service Providers

unit="PERCENT">
<Sample
timestamp="2013-12-02T[Link].000Z"
value="24.07100028991699"/>
<Sample
timestamp="2013-12-02T[Link].000Z"
value="5.87066666285197"/>
<Sample/>
</MetricSeries>
<MetricSeries
expectedInterval="1800"
name="[Link]"
unit="KILOBYTE">
<Sample
timestamp="2013-12-02T[Link].000Z"
value="262154.0"/>
<Sample
timestamp="2013-12-02T[Link].000Z"
value="373779.0"/>
</MetricSeries>
<MetricSeries
expectedInterval="300"
name="[Link]"
unit="KILOBYTES_PER_SECOND">
<Sample
timestamp="2013-12-02T[Link].000Z"
value="30.3"/>
<Sample
timestamp="2013-12-02T[Link].000Z"
value="0.5333333333333333"/>
<Sample... />
</MetricSeries>
<MetricSeries
expectedInterval="300"
name="[Link]"
unit="PERCENT">
<Sample
timestamp="2013-12-02T[Link].000Z"
value="24.07100028991699"/>
<Sample
timestamp="2013-12-02T[Link].000Z"
value="5.87066666285197"/>
<Sample ... />
</MetricSeries>
</HistoricUsage>

Metric Names and Patterns

When you retrieve a subset of current or historic metrics, you can specify the metrics by name, or by using a
pattern that includes a wildcard character.

Metric Names
Metric names are dot-separated strings.

148 VMware, Inc.

Chapter 5 Deploying and Operating vApps and Virtual Machines

Table 5‑4. Metric Names

Metric Name Type Unit Description

[Link] rate percent Host view of this virtual

machine's average actively
used CPU as a percentage of
total available. Includes all
cores in all sockets.

[Link] rate megahertz Host view of this virtual

machine's average actively
used CPU as a raw
measurement . Includes all
cores in all sockets.

[Link] rate percent Host view of this virtual

machine's maximum
actively used CPU as a
percentage of total available.
Includes all cores in all
sockets.

[Link] absolute percent Memory used by this virtual

machine as a percentage of
total configured memory.

[Link] absolute kilobytes Storage space allocated to

this virtual hard disk in the
containing organization
virtual data center.

[Link] absolute kilobytes Storage used by all virtual

hard disks.

[Link] rate kilobytes per second Average read rate for all
virtual hard disks.

[Link] rate kilobytes per second Average write rate for all
virtual hard disks.

Note When a virtual machine has multiple disks, metrics are reported as an aggregate for all disks. CPU
metrics are an aggregate of all cores and sockets.

Metric Patterns
A CurrentUsageSpec or HistoricUsageSpec can include MetricPattern elements that specify multiple metric
names using a wildcard character. To form a metric pattern, replace any component of a metric name with
an asterisk, which is a wildcard that matches all values of the metric name component it replaces. For
example, this MetricPattern matches all metric names that begin with disk.

<MetricPattern>disk.*</MetricPattern>

The response would include these metric names: [Link], [Link],

[Link], and [Link].

A different MetricPattern matches all metric names that begin with disk and end with average.

<MetricPattern>disk.*.average</MetricPattern>

The response would include the metric names [Link] and [Link].

VMware, Inc. 149

vCloud API Programming Guide for Service Providers

Metric Series Expected Intervals and Timestamps

A HistoricUsage element includes zero or more MetricSeries elements, each of which includes a set of
Sample elements. Each MetricSeries has an expectedInterval attribute that specifies the interval, in
milliseconds, at which the samples in the series are reported. Each Sample in the MetricSeries has a
timestamp attribute noting the absolute time at which the sample was taken. You can use the timestamp and
expectedInterval values to aggregate sample data, and to determine when metrics became unavailable
because the virtual machine was powered off or unreachable.

Specifying Collection Start and End Times

A HistoricUsageSpec can include a time specification that constrains the result set to metrics collected
between a start time and an end time. This time specification can be relative or absolute.

In RelativeStartTime and RelativeEndTime elements, start and end times are specified as an interval and a
unit, which are interpreted as interval units ago. For example, this HistoricUsageSpec requests metrics
collected during the past 8 hours.

<HistoricUsageSpec xmlns="[Link]
<RelativeStartTime
interval="8"
unit="hour"/>
<RelativeEndTime
interval="0"
unit="hour"/>
...
</HistoricUsageSpec>

You can also write this specification with no RelativeEndTime element, rather than a RelativeEndTime with
an interval attribute value of 0. Both constructions specify an end time of now.

Alternatively, you can use AbsoluteStartTime and AbsoluteEndTime elements to specify absolute start and
end times in a HistoricUsageSpec, as shown in this example, which returns metrics recorded during a one
hour period:

<HistoricUsageSpec xmlns="[Link]
<AbsoluteStartTime time="2013-11-13T[Link].000Z" />
<AbsoluteEndTime time="2013-11-13T[Link].000Z" />
...
</HistoricUsageSpec>

150 VMware, Inc.

Reconfiguring vApps and Virtual
Machines 6
You establish the initial configuration of a vApp and its virtual machines when you create it. After a vApp
has been created by instantiation, cloning, composition, or recomposition, you can make further changes to
its configuration using PUT requests that update modifiable elements of vApp and virtual machine objects.

Nearly all of the properties that you can specify when you create a vApp using any of the requests listed in
“Instantiation Parameters,” on page 98 can be modified using a common reconfiguration workflow.
Modifiable elements include a Link element where rel="edit". See “Retrieve the Configuration Links for a
vApp,” on page 152 and “Retrieve the Configuration Links for a Virtual Machine,” on page 153.

Reconfiguration Workflow
The workflow for reconfiguring a vApp or virtual machine is the same regardless of the section you are
modifying.

1 Retrieve the vApp or Vm and examine the response to find the section that you want to modify.

2 Retrieve the section by making a GET request to the URL in the section’s href attribute value.

3 Modify the section as needed.

4 Update the section by making a PUT request to the section’s edit link, a Link element in the section
where rel="edit", and supplying the modified section in the request body.

5 To preserve these modification, you can capture the reconfigured vApp to create a new vApp template.
See “Capture a vApp as a Template,” on page 123.

Request bodies must contain all required elements and attributes, even if you are not changing their values.
Because optional elements and attributes typically revert to default values if they are omitted or empty, it is
a best practice to include optional elements in request bodies that modify existing objects. Link elements and
href attributes from responses do not need to be included in modified sections. Some elements and
attributes are read-only and cannot be modified. See the schema reference for details.

Note You cannot make configuration changes to a vApp if it is in maintenance mode. A system
administrator can put a vApp into maintenance mode to prevent metadata changes during administrative
operations such as backup, restore, and upgrade.

This chapter includes the following topics:

n “Retrieve the Configuration Links for a vApp,” on page 152

n “Retrieve the Configuration Links for a Virtual Machine,” on page 153

n “Update Multiple Sections of a Virtual Machine,” on page 157

n “Retrieve or Update a Modifiable Section,” on page 159

n “Update a vApp Network Configuration,” on page 161

VMware, Inc. 151

vCloud API Programming Guide for Service Providers

n “Update the NetworkConnectionSection of a Virtual Machine,” on page 164

n “Retrieve or Modify the CPU Configuration of a Virtual Machine,” on page 165

n “Retrieve or Modify the GuestCustomizationSection of a Virtual Machine,” on page 167

n “Retrieve or Modify ProductSection Elements,” on page 168

n “Retrieve or Modify Groups of Related Sections in a Virtual Machine,” on page 171

n “Retrieve or Modify the Hard Disk Configuration of a Virtual Machine,” on page 173

n “Update the Storage Profile for a Virtual Machine,” on page 175

n “Override the Default Storage Profile for a Hard Disk,” on page 177

n “Specify Hard Disk IOPS,” on page 180

Retrieve the Configuration Links for a vApp

Each modifiable section of a vApp includes a Link element whose rel attribute has the value edit. You
cannot modify sections that do not contain this Link element.

Any ovf:SectionType element can include an arbitrary number of Link elements. Sections that you can
modify include a Link element where rel="edit". To modify one of these sections, retrieve it by making a
GET request to the URL in the section's href attribute. Then make a PUT request to the href attribute value
of the Link where rel="edit" to update the section with your modifications.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the XML representation of the vApp.

Use a GET request as shown in “Example: Configuration Links in a vApp,” on page 152.

2 Examine the response for edit links to modifiable sections.

The response portion of “Example: Configuration Links in a vApp,” on page 152 includes one of these
links for each of the modifiable sections of the vApp. You cannot modify sections that do not contain a
Link element where rel="edit".

Example: Configuration Links in a vApp

In this example, the response was edited to show only the modifiable sections of the VApp element. Each Vm
in the Children element of the VApp includes additional configuration links, shown in
“Example: Configuration Links in a Vm Element,” on page 154.

Request:

GET [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<VApp ... href="[Link]
...
<LeaseSettingsSection ...
href="[Link] ...>
...

152 VMware, Inc.

Chapter 6 Reconfiguring vApps and Virtual Machines

<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
...
</LeaseSettingsSection>
<ovf:StartupSection ...
href="[Link] ... >
...
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
...
</ovf:StartupSection>
<NetworkConfigSection ...
href="[Link] ... />
...
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
...
</NetworkConfigSection>
<Children>
<Vm ...
status="8"
name="ubuntu10-x86"
href="[Link]
...
</Vm>
</Children>
</VApp>

Retrieve the Configuration Links for a Virtual Machine

A virtual machine is represented by a Vm element. Each modifiable section of a Vm element includes a Link
element whose rel attribute has the value edit. You cannot modify sections that do not contain this Link
element.

Any ovf:SectionType element can include an arbitrary number of Link elements. Sections that you can
modify include a Link element where rel="edit". To modify one of these sections, retrieve it by making a
GET request to the URL in the section's href attribute. Then make a PUT request to the href attribute value
of the Link where rel="edit" to update the section with your modifications.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the XML representation of the vApp that contains the virtual machine to reconfigure.

Use a GET request as shown in “Example: Configuration Links in a vApp,” on page 152.

2 In the VApp element's Children element, find the Vm element that represents the virtual machine and
retrieve it.

VMware, Inc. 153

vCloud API Programming Guide for Service Providers

3 Examine the response to find the reconfigureVm link and edit links to modifiable sections.

The response portion of “Example: Configuration Links in a Vm Element,” on page 154 shows the
reconfigureVm link and links for each of the modifiable sections of the Vm. You cannot modify sections
that do not contain a link where rel="edit".

Example: Configuration Links in a Vm Element

This example retrieves a Vm element shown in “Example: Configuration Links in a vApp,” on page 152. It
expands that element to show its configuration links. It also shows the entire NetworkConnectionSection of
that Vm, and additional information that is referenced in other examples. You cannot modify sections that do
not have a Link where rel="edit", so they do not appear in this example. Modifiable sections of the parent
vApp are shown in “Example: Configuration Links in a vApp,” on page 152.

Request:

GET [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Vm
xmlns="[Link]
xmlns:ovf="[Link]
status="8"
name="ubuntu10-x86"
href="[Link]
...
<Link
rel="reconfigureVm"
type="application/[Link]+xml"
name="vm-4"
href="[Link] />
...
<ovf:VirtualHardwareSection>
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />

154 VMware, Inc.

Chapter 6 Reconfiguring vApps and Virtual Machines

<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
</ovf:VirtualHardwareSection>
<ovf:OperatingSystemSection
href="[Link]
ovf:id="1">
<ovf:Info>Specifies the operating system installed
</ovf:Info>
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
</ovf:OperatingSystemSection>
<NetworkConnectionSection>
<ovf:Info>Specifies the available VM network connections</ovf:Info>
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
...
</NetworkConnectionSection>
<GuestCustomizationSection>
<Link
rel="edit"
href="[Link]
type="application/[Link]+xml">
</Link>
...
</GuestCustomizationSection>
<VmCapabilities>
<Link
rel="edit"
href="[Link]
type="application/[Link]+xml" />
<MemoryHotAddEnabled>false</MemoryHotAddEnabled>
<CpuHotAddEnabled>false</CpuHotAddEnabled>
</VmCapabilities>

VMware, Inc. 155

vCloud API Programming Guide for Service Providers

<BootOptions>
<Link
rel="edit"
href="[Link]
type="application/[Link]+xml" />
<BootDelay>0</BootDelay>
<EnterBIOSSetup>false</EnterBIOSSetup>
</BootOptions>
...
</Vm>

vCloud API Custom Attributes

vCloud API custom attributes extend several elements in the ovf and rasd XML namespaces. You can use
these attributes to provide additional detail about virtual NIC and hard disk controller devices, or to specify
the guest operating system type.

With the exception of osType, custom attributes are scoped to ovf:Item elements based on the elements'
RASD resource type. The osType attribute applies to the ovf:OperatingSystemSection element. All of the
elements to which these custom attributes apply are contained in the VirtualHardwareSection of a Vm.

Table 6‑1. vCloud API Custom Attributes for OVF and RASD Elements
RASD
Resource
Element Name Type Attribute Name Attribute Type Description

rasd:Connection 10 ipAddressingMode xs:string IP addressing mode to use for this

(Network connection. One of NONE, MANUAL,
adapters) DHCP, POOL.

rasd:Connection 10 ipAddress xs:string If ipAddressingMode="MANUAL",

(Network set the IP address here
adapters)

rasd:Connection 10 primaryNetworkCon xs:boolean True if this is the primary network

(Network nection connection of the virtual machine
adapters)

rasd:HostResource 17 (Hard capacity xs:string Hard disk capacity in megabytes.

disks) See “Retrieve or Modify the Hard
Disk Configuration of a Virtual
Machine,” on page 173

rasd:HostResource 17 (Hard busType xs:string Bus type. One of:

disks) n 5 (IDE)
n 6 (SCSI)
n 20 (SATA)

rasd:HostResource 17 (Hard busSubType xs:string Hard disk controller type. One of:
disks) n buslogic
n lsilogic
n lsilogicsas
n VirtualSCSI
n [Link]
See “Retrieve or Modify the Hard
Disk Configuration of a Virtual
Machine,” on page 173 for valid
combinations of busType and
busSubType.

156 VMware, Inc.

Chapter 6 Reconfiguring vApps and Virtual Machines

Table 6‑1. vCloud API Custom Attributes for OVF and RASD Elements (Continued)
RASD
Resource
Element Name Type Attribute Name Attribute Type Description

rasd:HostResource 17 (Hard storageProfileOverrid xs:boolean If true, the storage profile specified

disks) eVmDefault in storageProfileHref is always
used for this disk regardless of the
value specified in the virtual
machine's StorageProfile.
.
If false, any storage profile is
specified in storageProfileHref
is ignored and the disk is migrated
to the storage specified in the
virtual machine's StorageProfile.

rasd:HostResource 17 (Hard storageProfileHref xs:string If

disks) storageProfileOverrideVmDefa
ult is true, the value of
storageProfileHref specifies the
storage profile to use for this hard
disk. The storage profile must be
available in the VDC where this
virtual machine is deployed.

rasd:HostResource 17 (Hard disk xs:string Read-only reference to an attached

disks) independent disk.

rasd:HostResource 17 (Hard iops xs:int Requested I/O operations per

disks) second for this hard disk. See
“Specify Hard Disk IOPS,” on
page 180.

ovf:OperatingSystemSec N/A osType xs:string Internal VMware identifier for the

tion guest operating system. See Enum -
VirtualMachineGuestOsIdentifier in
the VMware vSphere API Reference
documentation.

For more information about OVF and RASD (CIM_ResourceAllocationSettingData) elements, see “About
OVF,” on page 95 and “About DMTF, CIM, and RASD,” on page 96.

Update Multiple Sections of a Virtual Machine

You can make a single request that updates the name, Description, and any or all of the
VirtualHardwareSection, OperatingSystemSection, NetworkConnectionSection, GuestCustomizationSection
elements of a virtual machine.

Every Vm element contains a link to a reconfigureVm operation that you can use to update the name,
Description, and multiple sections in a single operation. Sections that you omit from the request body are
not updated.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the Vm element that you want to update.

VMware, Inc. 157

vCloud API Programming Guide for Service Providers

2 Modify the retrieved Vm element.

Modifications can include the name, Description, and any or all of the VirtualHardwareSection,
OperatingSystemSection, NetworkConnectionSection, GuestCustomizationSection elements of the Vm.

Request bodies must contain all required elements and attributes, even if you are not changing their
values. Because optional elements and attributes typically revert to default values if they are omitted or
empty, it is a best practice to include optional elements in request bodies that modify existing objects.
Link elements and href attributes from responses do not need to be included in modified sections. Some
elements and attributes are read-only and cannot be modified. See the schema reference for details.

3 Use the modified Vm as the body of a reconfigureVm request.

The modified Vm replaces the contents of the retrieved Vm. For some section types, modifications take effect
immediately. For others, modifications take effect only after a power or deployment state change.

Example: Update Multiple Sections of a Virtual Machine

This example uses the reconfigureVm operation to accomplish the updates shown in “Example: Update a
NetworkConnectionSection,” on page 164 and “Example: Modify the Guest Customization Section of a
Virtual Machine,” on page 167 in a single operation. It also updates the independent disk attached to this
virtual machine in a way similar to the operation shown in “Example: Update an Independent Disk,” on
page 88
Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Vm ...>
...
<NetworkConnectionSection
type="application/[Link]+xml"
xmlns="[Link]
xmlns:ovf="[Link]
<ovf:Info>Firewall allows access to this address.</ovf:Info>
<PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex>
<NetworkConnection network="vAppNetwork">
<NetworkConnectionIndex>0</NetworkConnectionIndex>
<IpAddress>[Link]</IpAddress>
<IsConnected>true</IsConnected>
<MACAddress>[Link]</MACAddress>
<IpAddressAllocationMode>STATIC</IpAddressAllocationMode>
</NetworkConnection>
</NetworkConnectionSection>
<GuestCustomizationSection
xmlns="[Link]
xmlns:ovf="[Link]
ovf:required="false">
<ovf:Info>Specifies Guest OS Customization Settings</ovf:Info>
<Enabled>true</Enabled>
<ChangeSid>true</ChangeSid>
<VirtualMachineId>12</VirtualMachineId>
<JoinDomainEnabled>false</JoinDomainEnabled>
<UseOrgSettings>false</UseOrgSettings>
<DomainName />
<DomainUserName />

158 VMware, Inc.

Chapter 6 Reconfiguring vApps and Virtual Machines

<DomainUserPassword />
<AdminPasswordEnabled>true</AdminPasswordEnabled>
<AdminPasswordAuto>true</AdminPasswordAuto>
<AdminPassword />
<ResetPasswordRequired>false</ResetPasswordRequired>
<CustomizationScript />
<ComputerName>Win2K3</ComputerName>
</GuestCustomizationSection>
<ovf:VirtualHardwareSection
xmlns:vcloud="[Link]
vcloud:type="application/[Link]+xml">
<ovf:Info>Virtual hardware requirements</ovf:Info>
<ovf:Item>
<rasd:AddressOnParent>0</rasd:AddressOnParent>
<rasd:HostResource
vcloud:storageProfileHref="[Link]
vcloud:disk="[Link] />
<rasd:InstanceID>2000</rasd:InstanceID>
<rasd:Parent>2</rasd:Parent>
<rasd:ResourceType>17</rasd:ResourceType>
</ovf:Item>
</ovf:VirtualHardwareSection>
...
</Vm>

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task
...
operation="Updating Virtual Application Win2K3 (4)"
...>
...
</Task>

Retrieve or Update a Modifiable Section

You can make a GET request to the URL of any modifiable section to retrieve it for modification. After you
modify the section, you can make a PUT request to its edit link to update the section with your
modifications.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the section to modify.

Make a GET request to the URL in the section's href attribute value.

VMware, Inc. 159

vCloud API Programming Guide for Service Providers

2 Modify the retrieved section.

Request bodies must contain all required elements and attributes, even if you are not changing their
values. Because optional elements and attributes typically revert to default values if they are omitted or
empty, it is a best practice to include optional elements in request bodies that modify existing objects.
Link elements and href attributes from responses do not need to be included in modified sections. Some
elements and attributes are read-only and cannot be modified. See the schema reference for details.

3 Update the section with your modifications.

Find the Link element in the section where rel="edit". Make a PUT request to the URL in that link's
href attribute value, and supply the modified section as the request body.

For most section types, the response to this request is a Task element that tracks the update operation.
When the task completes, the section is updated.

The modified section replaces the contents of the original section. For some section types, modifications take
effect immediately. For others, modifications take effect only after a power or deployment state change.

Example: Retrieve a NetworkConfigSection

This example retrieves the NetworkConfigSection of the vApp shown in “Example: Configuration Links in a
vApp,” on page 152.
Request:

GET [Link]

Response:

200 OK
Content-type: application/[Link]+xml
...
<NetworkConfigSection
xmlns="[Link]
xmlns:ovf="[Link]
href="[Link]
ovf:required="false">
<ovf:Info>Configuration parameters for logical networks</ovf:Info>
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<NetworkConfig
networkName="vAppNetwork">
<Configuration>
<IpScopes>
<IpScope>
<IsInherited>true</IsInherited>
<Gateway>[Link]</Gateway>
<Netmask>[Link]</Netmask>
<Dns1>[Link]</Dns1>
<Dns2>[Link]</Dns2>
<DnsSuffix>[Link]</DnsSuffix>
<IpRanges>
<IpRange>
<StartAddress>[Link]</StartAddress>
<EndAddress>[Link]</EndAddress>
</IpRange>

160 VMware, Inc.

Chapter 6 Reconfiguring vApps and Virtual Machines

</IpRanges>
</IpScope>
</IpScopes>
<ParentNetwork
type="application/[Link]+xml"
name="Internet"
href="[Link] />
<FenceMode>bridged</FenceMode>
</Configuration>
<IsDeployed>false</IsDeployed>
</NetworkConfig>
</NetworkConfigSection>

For an example that updates this section, see “Example: Update a NetworkConfigSection,” on page 161 .

Update a vApp Network Configuration

To change the configuration of a vApp network, you retrieve the NetworkConfigSection element of the
vApp, modify it, and use it with a PUT request to update the section.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the vApp's NetworkConfigSection.

2 Modify the returned NetworkConfigSection as needed.

Request bodies must contain all required elements and attributes, even if you are not changing their
values. Because optional elements and attributes typically revert to default values if they are omitted or
empty, it is a best practice to include optional elements in request bodies that modify existing objects.
Link elements and href attributes from responses do not need to be included in modified sections. Some
elements and attributes are read-only and cannot be modified. See the schema reference for details.

3 Update the NetworkConfigSection in the vApp.

Find the Link element in the section where rel="edit". Make a PUT request to the URL in that link's
href attribute value, and supply the modified section as the request body.

Example: Update a NetworkConfigSection

This example modifies the NetworkConfigSection that was retrieved in “Example: Retrieve a
NetworkConfigSection,” on page 160. The modifications change the FenceMode value to natRouted and add a
Features element that defines several network features that are useful to an FTP server that must be
reachable from the public Internet, but only at the FTP and SSH ports. The modifications add the following
items:

n 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 virtual machine that
connects to the vApp network defined in this NetworkConfigSection is given this address.

n 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: Configuration Links in a Vm Element,” on page 154.

VMware, Inc. 161

vCloud API Programming Guide for Service Providers

For more information about these and other network services in vApp networks, see “Network Services in
vApp Networks,” on page 101

This request, like all request bodies derived from a response, omits the Link elements and href attributes
that were part of the retrieved NetworkConfigurationSection. 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. Read-only elements are noted in the schema reference.

Request:

PUT [Link]
Content-type: application/[Link]+xml
...
<NetworkConfigSection
xmlns="[Link]
xmlns:ovf="[Link]
<ovf:Info>Configuration parameters for logical networks</ovf:Info>
<NetworkConfig
networkName="vAppNetwork">
<Configuration>
<IpScopes>
<IpScope>
<IsInherited>false</IsInherited>
<Gateway>[Link]</Gateway>
<Netmask>[Link]</Netmask>
<Dns1>[Link]</Dns1>
<Dns2>[Link]</Dns2>
<DnsSuffix>[Link]</DnsSuffix>
<IpRanges>
<IpRange>
<StartAddress>[Link]</StartAddress>
<EndAddress>[Link]</EndAddress>
</IpRange>
</IpRanges>
</IpScope>
</IpScopes>
<ParentNetwork
type="application/[Link]+xml"
name="Internet"
href="[Link] />
<FenceMode>natRouted</FenceMode>
<Features>
<FirewallService>
<IsEnabled>true</IsEnabled>
<FirewallRule>
<IsEnabled>true</IsEnabled>
<Description>FTP Rule</Description>
<Policy>allow</Policy>
<Protocols>
<Tcp>true</Tcp>
</Protocols>
<DestinationPortRange>21</DestinationPortRange>
<DestinationIp>[Link]</DestinationIp>
<SourcePortRange>any</SourcePortRange>
<SourceIp>any</SourceIp>
<EnableLogging>false</EnableLogging>
</FirewallRule>

162 VMware, Inc.

Chapter 6 Reconfiguring vApps and Virtual Machines

<FirewallRule>
<IsEnabled>true</IsEnabled>
<Description>SSH Rule</Description>
<Policy>allow</Policy>
<Protocols>
<Tcp>true</Tcp>
</Protocols>
<DestinationPortRange>22</DestinationPortRange>
<DestinationIp>[Link]</DestinationIp>
<SourcePortRange>any</SourcePortRange>
<SourceIp>any</SourceIp>
<EnableLogging>false</EnableLogging>
</FirewallRule>
</FirewallService>
<NatService>
<IsEnabled>true</IsEnabled>
<NatType>ipTranslation</NatType>
<Policy>allowTraffic</Policy>
<NatRule>
<OneToOneVmRule>
<MappingMode>automatic</MappingMode>
<VAppScopedVmId>3963994b-5a0a-48fe-b9ae-7f9a2d8e8e5b</VAppScopedVmId>
<VmNicId>0</VmNicId>
</OneToOneVmRule>
</NatRule>
</NatService>
</Features>
</Configuration>
</NetworkConfig>
</NetworkConfigSection>

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... operation="Updating Virtual Application Linux FTP server (7)" ...>
...
</Task>

Important 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 in the vApp.
The vApp in this example contains a single virtual machine. Its NetworkConnection element, shown in
“Example: Configuration Links in a Vm Element,” on page 154, specifies an IP address that will not be
available after the vApp network is reconfigured as shown here. “Example: Update a
NetworkConnectionSection,” on page 164 corrects this problem. This example uses the IpScope element to
restrict the IP addresses available on a vApp network. It is usually more practical to use a wide range of
addresses available on a vApp network and apply any firewall-related IP address restrictions by modifying
the NetworkConnectionSection of the Vm to which the FirewallRules apply, as shown in “Example: Update a
NetworkConnectionSection,” on page 164. A wider range of IP addresses allows you to modify this vApp to
include additional virtual machines, and the IP address restriction applied in “Example: Update a
NetworkConnectionSection,” on page 164 allows the FirewallRules in this example to remain valid.

VMware, Inc. 163

vCloud API Programming Guide for Service Providers

Update the NetworkConnectionSection of a Virtual Machine

Whenever you create a vApp network or update its configuration, you might also need to update the
NetworkConnectionSection elements of the virtual machines in the vApp.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the virtual machine's NetworkConnectionSection.

2 Modify the returned NetworkConnectionSection as needed.

Request bodies must contain all required elements and attributes, even if you are not changing their
values. Because optional elements and attributes typically revert to default values if they are omitted or
empty, it is a best practice to include optional elements in request bodies that modify existing objects.
Link elements and href attributes from responses do not need to be included in modified sections. Some
elements and attributes are read-only and cannot be modified. See the schema reference for details.

3 Update the section with your modifications.

a In the retrieved section, find the Link element where rel="edit".

b Make a PUT request to the URL in that link's href attribute value, and supply the modified section
as the request body.

The response to this request is a Task element that tracks the update operation. When the task is
complete, the section is updated.

Example: Update a NetworkConnectionSection

This example modifies the NetworkConnectionSection shown in “Example: Configuration Links in a Vm
Element,” on page 154 so that this network connection is compatible with the reconfigured vApp network to
which it must connect. See “Example: Update a NetworkConfigSection,” on page 161. The modified
NetworkConnectionSection in the request changes two values:

n The IpAddress now specifies the address to which the vApp network's firewall allows access.

n Because it specifies an IP address, the modified NetworkConnectionSection also changes the value of the
IpAddressAllocationMode from DHCP to STATIC.

Note The ovf:Info element is a required member of NetworkConnectionSection and all other sections that
are derived from ovf:SectionType. The element must be present, even if it has no content. In this example,
we use the content to explain why the connection is configured this way.

Request:

PUT "[Link]
Content-type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<NetworkConnectionSection
type="application/[Link]+xml"
xmlns="[Link]
xmlns:ovf="[Link]
<ovf:Info>Firewall allows access to this address.</ovf:Info>
<PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex>

164 VMware, Inc.

Chapter 6 Reconfiguring vApps and Virtual Machines

<NetworkConnection
network="vAppNetwork">
<NetworkConnectionIndex>0</NetworkConnectionIndex>
<IpAddress>[Link]</IpAddress>
<IsConnected>true</IsConnected>
<MACAddress>[Link]</MACAddress>
<IpAddressAllocationMode>STATIC</IpAddressAllocationMode>
</NetworkConnection>
</NetworkConnectionSection>

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... operation="Updating Virtual Application Linux FTP server (7)" ...>
...
</Task>

Retrieve or Modify the CPU Configuration of a Virtual Machine

The CPU configuration of a virtual machine is represented by an Item in its VirtualHardwareSection
element.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the CPU section to modify.

Make a GET request to the URL in the section's href attribute value:

GET [Link]

2 Modify the retrieved section.

Request bodies must contain all required elements and attributes, even if you are not changing their
values. Because optional elements and attributes typically revert to default values if they are omitted or
empty, it is a best practice to include optional elements in request bodies that modify existing objects.
Link elements and href attributes from responses do not need to be included in modified sections. Some
elements and attributes are read-only and cannot be modified. See the schema reference for details.

3 Update the section with your modifications.

a In the retrieved section, find the Link element where rel="edit".

b Make a PUT request to the URL in that link's href attribute value, and supply the modified section
as the request body.

The response to this request is a Task element that tracks the update operation. When the task is
complete, the section is updated.

The modified section replaces the contents of the original section. For some section types, modifications take
effect immediately. For others, modifications take effect only after a power or deployment state change.

VMware, Inc. 165

vCloud API Programming Guide for Service Providers

Example: Modify the CPU Configuration of a Virtual Machine

The initial configuration for the virtual machine used in this example shows a single CPU and
CoresPerSocket value of 1.

<Item xmlns="[Link]
xmlns:vcloud="[Link]
xmlns:rasd="[Link]
schema/2/CIM_ResourceAllocationSettingData"
xmlns:vmw="[Link]
vcloud:type="application/[Link]+xml">
<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>4</rasd:InstanceID>
<rasd:Reservation>0</rasd:Reservation>
<rasd:ResourceType>3</rasd:ResourceType>
<rasd:VirtualQuantity>1</rasd:VirtualQuantity>
<rasd:Weight>0</rasd:Weight>
<vmw:CoresPerSocket ovf:required="false">1</vmw:CoresPerSocket>
</Item>

This request modifies the CPU section to add a second CPU to the Vm by changing the rasd:VirtualQuantity
value of the Item to 2. It also raises the value of CoresPerSocket to 2.

Request:

PUT [Link]
Content-type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Item xmlns="[Link]
xmlns:vcloud="[Link]
xmlns:rasd="[Link]
schema/2/CIM_ResourceAllocationSettingData"
vcloud:type="application/[Link]+xml">
<rasd:AllocationUnits>hertz * 10^6</rasd:AllocationUnits>
<rasd:Description>Number of Virtual CPUs</rasd:Description>
<rasd:ElementName>2 virtual CPU(s)</rasd:ElementName>
<rasd:InstanceID>4</rasd:InstanceID>
<rasd:Reservation>0</rasd:Reservation>
<rasd:ResourceType>3</rasd:ResourceType>
<rasd:VirtualQuantity>2</rasd:VirtualQuantity>
<rasd:Weight>0</rasd:Weight>
<vmw:CoresPerSocket ovf:required="false">2</vmw:CoresPerSocket>
</Item>

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... operation="Updating Virtual Application Linux FTP server (7)" ...>
...
</Task>

166 VMware, Inc.

Chapter 6 Reconfiguring vApps and Virtual Machines

Retrieve or Modify the GuestCustomizationSection of a Virtual

Machine
The GuestCustomizationSection element includes a customization script and other parameters that are
applied when you customize a virtual machine.

The GuestCustomizationSection includes predefined property names that VMware guest customization
tools recognize. Certain values in this element, if omitted or left empty, are inherited from the
OrgGuestPersonalizationSettings of the organization that owns the virtual machine. See “Retrieve or
Update Organization Settings,” on page 186.

The vCloud API also supports use of the ovf:ProductSection to pass an arbitrary set of key=value pairs to a
vApp or virtual machine through the ovf:Environment element. See “Retrieve or Modify ProductSection
Elements,” on page 168.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the GuestCustomizationSection to modify.

Make a GET request to the URL in the section's href attribute value.

GET [Link]

2 Modify the retrieved section.

Request bodies must contain all required elements and attributes, even if you are not changing their
values. Because optional elements and attributes typically revert to default values if they are omitted or
empty, it is a best practice to include optional elements in request bodies that modify existing objects.
Link elements and href attributes from responses do not need to be included in modified sections. Some
elements and attributes are read-only and cannot be modified. See the schema reference for details.

3 Update the section with your modifications.

a In the retrieved section, find the Link element where rel="edit".

b Make a PUT request to the URL in that link's href attribute value, and supply the modified section
as the request body.

The response to this request is a Task element that tracks the update operation. When the task is
complete, the section is updated.

The modified section replaces the contents of the original section. For some section types, modifications take
effect immediately. For others, modifications take effect only after a power or deployment state change.

Example: Modify the Guest Customization Section of a Virtual Machine

This request specifies guest customization values, including the information required to join the virtual
machine to a Windows domain.

Note If you include a CustomizationScript, it cannot exceed 49,000 characters.

VMware, Inc. 167

vCloud API Programming Guide for Service Providers

Request:

PUT [Link]
Content-type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<GuestCustomizationSection
xmlns="[Link]
xmlns:ovf="[Link]
ovf:required="false">
<ovf:Info>Specifies Guest OS Customization Settings</ovf:Info>
<Enabled>true</Enabled>
<ChangeSid>true</ChangeSid>
<VirtualMachineId>12</VirtualMachineId>
<JoinDomainEnabled>false</JoinDomainEnabled>
<UseOrgSettings>false</UseOrgSettings>
<DomainName>example</DomainName>
<DomainUserName>admin</DomainUserName>
<DomainUserPassword>Pa55w0rd</DomainUserPassword>
<AdminPasswordEnabled>true</AdminPasswordEnabled>
<AdminPasswordAuto>true</AdminPasswordAuto>
<AdminPassword />
<ResetPasswordRequired>false</ResetPasswordRequired>
<CustomizationScript />
<ComputerName>Win2K3</ComputerName>
</GuestCustomizationSection>

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task
...
operation="Updating Virtual Application Win2K3 (12)"
...>
...
</Task>

Retrieve or Modify ProductSection Elements

ProductSection elements allow you to pass runtime information to vApps and virtual machines. The
key=value pairs in this section are made available in the OVF Environment of a powered-on vApp or virtual
machine.

A vApp or virtual machine can get runtime information from its ovf:Environment element. This read-only
element is populated with information from a ProductSection element when the vApp or virtual machine is
powered on. A Vm can use VMware Tools to read these values from its ovf:Environment. A Vm can also read
the values by mounting a special media object. To make a key=value pair available in the ovf:Environment,
add it to the appropriate ProductSection of a vApp template or powered-off vApp or virtual machine.

Note All ProductSection elements in a vApp template, vApp, or virtual machine are returned as members
of a ProductSectionList. You cannot retrieve or update an individual ProductSection. You must retrieve
and modify the ProductSectionList to update the individual ProductSection elements it contains.

168 VMware, Inc.

Chapter 6 Reconfiguring vApps and Virtual Machines

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the ProductSectionList from the vApp or virtual machine.

Use a request like this one, which targets a vApp.

GET [Link]

The response is a ProductSectionList element, which contains all the ProductSection elements in the
vApp, along with a Link element that contains the rel="edit" URL to use when updating the
ProductSectionList. If the vApp contains no ProductSection elements, the response contains only the
Link element.

2 Modify the retrieved ProductSectionList.

You can modify existing ProductSection elements, create new ones, or both. ProductSection has no
required contents. Unlike updates to other sections, updates to a ProductSection merge new and
existing values, subject to the following rules:
n Property elements that are present in the existing ProductSection but not in the update are
removed.

n Property elements that are present in the update but not in the in the existing ProductSection are
added to the ProductSection if they have a corresponding Value element.

n If a Property element that is present in the existing ProductSection has different attributes,
qualifiers, or other details in the update, the Property in the update replaces the existing one.

n If a Property element that is present in the existing ProductSection has no Value in the update, the
existing Property and Value remain unchanged.

3 Update the section with your modifications.

Find the Link element in the ProductSectionList where rel="edit". Make a PUT request to the URL in
that link's href attribute value, and supply the modified ProductSectionList as the request body.

The response to this request is a Task element that tracks the update operation. When the task is
complete, the section is updated.

The modified section replaces the contents of the original section, subject to the rules listed in Step 2.

Example: Update a ProductSection in a vApp

This request creates or updates a ProductSectionList that contains a single ProductSection. The
ProductSection sets three properties. The response is a Task.

Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<ProductSectionList
xmlns="[Link]
xmlns:ovf="[Link]
<ovf:ProductSection
required="true">
<ovf:Info>Information about the installed software</ovf:Info>
<ovf:Property

VMware, Inc. 169

vCloud API Programming Guide for Service Providers

ovf:type="string"
ovf:key="CRM_Database_Host"
ovf:value="[Link]">
<ovf:Label>CRM Database Host</ovf:Label>
</ovf:Property>
<ovf:Property
ovf:type="string"
ovf:key="CRM_Database_Username"
ovf:value="dbuser">
<ovf:Label>CRM Database Usernname</ovf:Label>
</ovf:Property>
<ovf:Property
ovf:type="string"
ovf:key="CRM_Password"
ovf:value="Pa55w0rd">
<ovf:Label>CRM Database User Password</ovf:Label>
</ovf:Property>
</ovf:ProductSection>
</ProductSectionList>

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... operation="Updating Virtual Application ..." ...>
...
</Task>

After the vApp is powered on, a virtual machine can retrieve the ovf:Environment document in the
following ways:

n It can use the default OVF iso transport type. This makes the environment document available as a file
named [Link] on an ISO image that is mounted on the first available CD-ROM device on the
virtual machine. You can use any convenient mechanism to read this file.

[root@example-vm-RHEL ~] cat /media/cdrom/[Link]

<?xml version="1.0" encoding="UTF-8"?>
<Environment ...>
...
<PropertySection>
<Property
oe:key="CRM_Database_Host"
oe:value="[Link]" />
<Property
oe:key="CRM_Database_Username"
oe:value="dbuser" />
<Property
oe:key="CRM_Password"
oe:value="Pa55w0rd" />
</PropertySection>
...
</Environment>

170 VMware, Inc.

Chapter 6 Reconfiguring vApps and Virtual Machines

n If the virtual machine has VMware Tools installed, it can use the vmtoolsd program, as shown here.

[root@example-vm-RHEL ~] /usr/sbin/vmtoolsd --cmd 'info-get [Link]'

<?xml version="1.0" encoding="UTF-8"?>
<Environment ...>
...
<PropertySection>
<Property
oe:key="CRM_Database_Host"
oe:value="[Link]" />
<Property
oe:key="CRM_Database_Username"
oe:value="dbuser" />
<Property
oe:key="CRM_Password"
oe:value="Pa55w0rd" />
</PropertySection>
...
</Environment>

On Windows, the vmtoolsd executable file is typically installed in C:\Program Files\VMware\VMware

Tools\[Link]

Retrieve or Modify Groups of Related Sections in a Virtual Machine

The vCloud API provides links that you can use to retrieve or update groups of sections that define related
hardware items such as disks, media devices, and network cards in a Vm element.

As shown in “Example: Configuration Links in a Vm Element,” on page 154, Link elements for disks, media
devices, and network cards are grouped at the end of the VirtualHardwareSection. These links have content
type application/[Link]+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 approach simplifies retrieval and modification of Item elements
that are typically viewed or modified as a group.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the RasdItemsList from a Vm.

Make a GET request to the URL in the link where

type="application/[Link]+xml" and rel="down". See “Example: Retrieve
the Hard Disks and Controllers in a Virtual Machine,” on page 172.

2 Modify the items in the retrieved list.

Request bodies must contain all required elements and attributes, even if you are not changing their
values. Because optional elements and attributes typically revert to default values if they are omitted or
empty, it is a best practice to include optional elements in request bodies that modify existing objects.
Link elements and href attributes from responses do not need to be included in modified sections. Some
elements and attributes are read-only and cannot be modified. See the schema reference for details.

VMware, Inc. 171

vCloud API Programming Guide for Service Providers

3 Update the sections with your modifications.

Make a PUT request to the URL in the link where

type="application/[Link]+xml" and rel="edit", and supply the modified
section as the request body.
The response to this request is a Task element that tracks the update operation. When the task is
complete, the section is updated.

Example: Retrieve the Hard Disks and Controllers in a Virtual Machine

This example uses the virtualHardwareSection/disks link shown in “Example: Configuration Links in a Vm
Element,” on page 154 to retrieve the list of hard disks and hard disk controllers for a virtual machine.

Request:

GET [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<RasdItemsList
xmlns="[Link]
xmlns:rasd="[Link]
schema/2/CIM_ResourceAllocationSettingData"
type="application/[Link]+xml"
href="[Link] ... >
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Item>
<rasd:Address>0</rasd:Address>
<rasd:Description>SCSI Controller</rasd:Description>
<rasd:ElementName>SCSI Controller 0</rasd:ElementName>
<rasd:InstanceID>2</rasd:InstanceID>
<rasd:ResourceSubType>lsilogic</rasd:ResourceSubType>
<rasd:ResourceType>6</rasd:ResourceType>
</Item>
<Item>
<rasd:AddressOnParent>0</rasd:AddressOnParent>
<rasd:Description>Hard disk</rasd:Description>
<rasd:ElementName>Hard disk 1</rasd:ElementName>
<rasd:HostResource
xmlns:vcloud="[Link]
vcloud:capacity="1024"
vcloud:busSubType="lsilogic"
vcloud:busType="6"></rasd:HostResource>
<rasd:InstanceID>2000</rasd:InstanceID>
<rasd:Parent>2</rasd:Parent>
<rasd:ResourceType>17</rasd:ResourceType>
</Item>
<Item>
<rasd:AddressOnParent>1</rasd:AddressOnParent>
<rasd:Description>Hard disk</rasd:Description>
<rasd:ElementName>Hard disk 2</rasd:ElementName>

172 VMware, Inc.

Chapter 6 Reconfiguring vApps and Virtual Machines

<rasd:HostResource
xmlns:vcloud="[Link]
vcloud:capacity="2048"
vcloud:busSubType="lsilogic"
vcloud:busType="6"></rasd:HostResource>
<rasd:InstanceID>2001</rasd:InstanceID>
<rasd:Parent>2</rasd:Parent>
<rasd:ResourceType>17</rasd:ResourceType>
</Item>
<Item>
<rasd:Address>0</rasd:Address>
<rasd:Description>IDE Controller</rasd:Description>
<rasd:ElementName>IDE Controller 0</rasd:ElementName>
<rasd:InstanceID>3</rasd:InstanceID>
<rasd:ResourceType>5</rasd:ResourceType>
</Item>
</RasdItemsList>

Retrieve or Modify the Hard Disk Configuration of a Virtual Machine

The hard disk configuration of a virtual machine is represented by one or more Item elements in its
VirtualHardwareSection.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the hard disk configuration from the virtual machine.

Make a GET request to the virtual machine's virtualHardwareSection/disks link.

GET [Link]

The response to this kind of request is a RasdItemsList element that contains an Item element for each
of the virtual machine's hard disks and hard disk controllers, as shown in “Example: Retrieve the Hard
Disks and Controllers in a Virtual Machine,” on page 172.

Important If an independent disk is attached to the virtual machine, it is included in this list, but
cannot be modified by this operation. Attached independent disks are distinguished by the appearance
of a vcloud:disk attribute in the containing Item, as shown here:

<rasd:HostResource
...
vcloud:disk="[Link] />

If you need to modify an independent disk while it is attached to a virtual machine, you must use the
reconfigureVm operation. See “Update Multiple Sections of a Virtual Machine,” on page 157.

2 Modify the retrieved section.

Request bodies must contain all required elements and attributes, even if you are not changing their
values. Because optional elements and attributes typically revert to default values if they are omitted or
empty, it is a best practice to include optional elements in request bodies that modify existing objects.
Link elements and href attributes from responses do not need to be included in modified sections. Some
elements and attributes are read-only and cannot be modified. See the schema reference for details.

VMware, Inc. 173

vCloud API Programming Guide for Service Providers

You cannot modify the values of the busType and busSubType attributes after you create a new disk.
When creating a new disk, be sure to set the values of busType and busSubType to a valid combination.

Table 6‑2. Valid Combinations of busType and busSubType

busType busSubType Controller

5 null IDE controller

6 buslogic BusLogic Parallel SCSI controller

6 lsilogic LSI Logic Parallel SCSI controller

6 lsilogicsas LSI Logic SAS SCSI controller

6 VirtualSCSI Paravirtual SCSI controller

20 [Link] SATA controller (hardware version 10 and later)

Note If you remove all the hard disk objects (RASD resource type 17) from the RasdItemsList
container for disks in the VirtualHardwareSection, the system also removes all hard disk controllers
(RASD resource type 5) from that section.

3 Update the section with your modifications.

a In the retrieved section, find the Link element where rel="edit".

b Make a PUT request to the URL in that link's href attribute value, and supply the modified section
as the request body.

The response to this request is a Task element that tracks the update operation. When the task is
complete, the section is updated.

The modified section replaces the contents of the original section. For some section types, modifications take
effect immediately. For others, modifications take effect only after a power or deployment state change.

Example: Modify the Hard Disk Configuration of a Virtual Machine

The following request increases the capacity of the hard disk from 1GB to 10GB by changing the
vcloud:capacity value of the Item that defines the disk. The capacity is raised from 1024 to 10240. The
request body includes the entire RasdItemsList returned by the request shown in Step 1, even though only
one element is changed. Link elements from a response are ignored if you include them in a request, so they
are omitted in this example.

Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<RasdItemsList
xmlns="[Link]
xmlns:rasd="[Link]
schema/2/CIM_ResourceAllocationSettingData"
type="application/[Link]+xml" >
<Item>
<rasd:Address>0</rasd:Address>
<rasd:Description>SCSI Controller</rasd:Description>
<rasd:ElementName>SCSI Controller 0</rasd:ElementName>
<rasd:InstanceID>2</rasd:InstanceID>
<rasd:ResourceSubType>lsilogic</rasd:ResourceSubType>
<rasd:ResourceType>6</rasd:ResourceType>

174 VMware, Inc.

Chapter 6 Reconfiguring vApps and Virtual Machines

</Item>
<Item>
<rasd:AddressOnParent>0</rasd:AddressOnParent>
<rasd:Description>Hard disk</rasd:Description>
<rasd:ElementName>Hard disk 1</rasd:ElementName>
<rasd:HostResource
xmlns:vcloud="[Link]
vcloud:capacity="10240"
vcloud:busSubType="lsilogic"
vcloud:busType="6"></rasd:HostResource>
<rasd:InstanceID>2000</rasd:InstanceID>
<rasd:Parent>2</rasd:Parent>
<rasd:ResourceType>17</rasd:ResourceType>
</Item>
<Item>
<rasd:AddressOnParent>1</rasd:AddressOnParent>
<rasd:Description>Hard disk</rasd:Description>
<rasd:ElementName>Hard disk 2</rasd:ElementName>
<rasd:HostResource
xmlns:vcloud="[Link]
vcloud:capacity="2048"
vcloud:busSubType="lsilogic"
vcloud:busType="6"></rasd:HostResource>
<rasd:InstanceID>2001</rasd:InstanceID>
<rasd:Parent>2</rasd:Parent>
<rasd:ResourceType>17</rasd:ResourceType>
</Item>
<Item>
<rasd:Address>0</rasd:Address>
<rasd:Description>IDE Controller</rasd:Description>
<rasd:ElementName>IDE Controller 0</rasd:ElementName>
<rasd:InstanceID>3</rasd:InstanceID>
<rasd:ResourceType>5</rasd:ResourceType>
</Item>
</RasdItemsList>

The response is a task.

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... operation="Updating Virtual Application Linux FTP server (7)" ...>
...
</Task>

Update the Storage Profile for a Virtual Machine

You can update a Vm to revalidate the storage profile it uses or specify a different storage profile.
Revalidation of a virtual machine's current storage profile is required whenever the datastore that supports
the virtual machine changes.

Every Vm element includes a StorageProfile element whose href attribute value specifies the default storage
profile consumed by the virtual machine. This default is used for all hard diskItems in the
VIrtualHardwareSection that do not specify storageProfileOverrideVmDefault.

VMware, Inc. 175

vCloud API Programming Guide for Service Providers

If you do not specify a StorageProfile during an instantiate, compose, or recompose operation, it is

inherited from the organization VDC in which the virtual machine is deployed. To change the value of an
existing StorageProfile, you must update the entire Vm element that contains it.

Important When the system administrator changes the datastore that stores a virtual machine, you must
update the Vm element as shown in “Example: Update the Storage Profile for a Virtual Machine,” on
page 176.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the Vm element.

Make a GET request to the URL in the value of the href attribute of the Vm.

2 Modify the retrieved Vm to change the StorageProfile reference.

Request bodies must contain all required elements and attributes, even if you are not changing their
values. Because optional elements and attributes typically revert to default values if they are omitted or
empty, it is a best practice to include optional elements in request bodies that modify existing objects.
Link elements and href attributes from responses do not need to be included in modified sections. Some
elements and attributes are read-only and cannot be modified. See the schema reference for details.

3 Update the Vm with your modifications.

a Find the Link element in the Vm where rel="edit".

b Make a PUT request to the URL in that link's href attribute value, and supply the modified Vm as
the request body.

The response to this request is a Task element that tracks the relocation of the virtual machine to a
datastore in the new storage profile. When the task is complete, the virtual machine's StorageProfile
has been updated and the virtual machine has been relocated to the new storage profile.

Example: Update the Storage Profile for a Virtual Machine

This example shows a Vm element containing a StorageProfile. The actual update operation requires the
entire Vm element, including the StorageProfile, in the request body. Only a small part of the element
appears in this example.

Request:

PUT [Link]
Content-type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Vm ...>
...
<StorageProfile
type="application/[Link]+xml"

176 VMware, Inc.

Chapter 6 Reconfiguring vApps and Virtual Machines

name="Gold"
href="[Link] />

</Vm>

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... operation="Updating Virtual Application Linux FTP server (7)" ...>
...
</Task>

Override the Default Storage Profile for a Hard Disk

By default, all hard disks defined in the VirtualHardwareSection of a Vm element use the storage profile
specified for the Vm. You can override this default for any of these disks when you instantiate a vApp
template, compose or recompose a vApp, or reconfigure a virtual machine.

Every Vm element includes a StorageProfile element. The storage profile referenced in this element
normally provides storage for all the hard disk Items in the virtual machine's VirtualHardwareSection. You
can override this default by updating the virtual machine's VirtualHardwareSection to add
storageProfileOverrideVmDefault and storageProfileHref attributes to the Item that defines the hard disk.
You can update a VirtualHardwareSection when you are instantiating a vApp template, composing or
recomposing a vApp, or reconfiguring a virtual machine.

Important You cannot override the default storage profile for any hard disk of a virtual machine that is
deployed in a VDC where fast provisioning is enabled.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Procedure
1 Retrieve the hard disk configuration from the virtual machine.

Make a GET request to the virtual machine's virtualHardwareSection/disks link.

GET [Link]

The response to this kind of request is a RasdItemsList element that contains an Item element for each
of the virtual machine's hard disks and hard disk controllers, as shown in “Example: Retrieve the Hard
Disks and Controllers in a Virtual Machine,” on page 172.

VMware, Inc. 177

vCloud API Programming Guide for Service Providers

2 In the VirtualHardwareSection of the retrieved Vm, modify the rasd:HostResource element of the Item
that defines the disk for which you want to override the default storage profile.

Request bodies must contain all required elements and attributes, even if you are not changing their
values. Because optional elements and attributes typically revert to default values if they are omitted or
empty, it is a best practice to include optional elements in request bodies that modify existing objects.
Link elements and href attributes from responses do not need to be included in modified sections. Some
elements and attributes are read-only and cannot be modified. See the schema reference for details.

a In the VirtualHardwareSection of the Vm, find the Item that represents the hard disk for which you
want to override the default storage profile.

b Add a storageProfileHref to the rasd:HostResource element of the Item and set its value to the
href of the storage profile you want to use for this disk. The storage profile you specify must be
available in the VDC where this virtual machine is deployed.

c Add a storageProfileOverrideVmDefault attribute to the rasd:HostResource element of the Item.

The value of this attribute controls whether changes to the virtual machine's StorageProfile affect
the storage profile that this disk uses.

Table 6‑3. How storageProfileOverrideVmDefault Values Affect Hard Disk Storage Profile
Assignment
Value Result

true (default) The storage profile specified in storageProfileHref is always used

for this disk regardless of the value specified in the virtual machine's
StorageProfile

false Any storage profile that is specified in storageProfileHref is

ignored and the disk is migrated to the storage specified in the virtual
machine's StorageProfile.

If you omit the storageProfileOverrideVmDefault attribute, the storageProfileHref is ignored.

3 Update the section with your modifications.

a In the retrieved section, find the Link element where rel="edit".

b Make a PUT request to the URL in that link's href attribute value, and supply the modified section
as the request body.

The response to this request is a Task element that tracks the update operation. When the task is
complete, the section is updated.

Example: Override the Default Storage Profile for a Hard Disk

This example builds on the ones shown in “Example: Update the Storage Profile for a Virtual Machine,” on
page 176 and “Example: Modify the Hard Disk Configuration of a Virtual Machine,” on page 174. This
virtual machine has the storage profile specified in “Example: Update the Storage Profile for a Virtual
Machine,” on page 176:

<StorageProfile
type="application/[Link]+xml"
name="Gold"
href="[Link] />

To specify a new storage profile for the disk whose capacity was increased in “Example: Modify the Hard
Disk Configuration of a Virtual Machine,” on page 174, you must provide the storageProfileHref for the
new storage profile and also set the storageProfileOverrideVmDefault attribute to true.

178 VMware, Inc.

Chapter 6 Reconfiguring vApps and Virtual Machines

Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<RasdItemsList
xmlns="[Link]
xmlns:rasd="[Link]
schema/2/CIM_ResourceAllocationSettingData"
type="application/[Link]+xml" >
<Item>
<rasd:Address>0</rasd:Address>
<rasd:Description>SCSI Controller</rasd:Description>
<rasd:ElementName>SCSI Controller 0</rasd:ElementName>
<rasd:InstanceID>2</rasd:InstanceID>
<rasd:ResourceSubType>lsilogic</rasd:ResourceSubType>
<rasd:ResourceType>6</rasd:ResourceType>
</Item>
<Item>
<rasd:AddressOnParent>0</rasd:AddressOnParent>
<rasd:Description>Hard disk</rasd:Description>
<rasd:ElementName>Hard disk 1</rasd:ElementName>
<rasd:HostResource
xmlns:vcloud="[Link]
vcloud:capacity="10240"
vcloud:busSubType="lsilogic"
vcloud:busType="6"
vcloud:storageProfileOverrideVmDefault="true"
vcloud:storageProfileHref="[Link]
</rasd:HostResource>
<rasd:InstanceID>2000</rasd:InstanceID>
<rasd:Parent>2</rasd:Parent>
<rasd:ResourceType>17</rasd:ResourceType>
</Item>
<Item>
<rasd:AddressOnParent>1</rasd:AddressOnParent>
<rasd:Description>Hard disk</rasd:Description>
<rasd:ElementName>Hard disk 2</rasd:ElementName>
<rasd:HostResource
xmlns:vcloud="[Link]
vcloud:capacity="2048"
vcloud:busSubType="lsilogic"
vcloud:busType="6"></rasd:HostResource>
<rasd:InstanceID>2001</rasd:InstanceID>
<rasd:Parent>2</rasd:Parent>
<rasd:ResourceType>17</rasd:ResourceType>
</Item>
<Item>
<rasd:Address>0</rasd:Address>
<rasd:Description>IDE Controller</rasd:Description>
<rasd:ElementName>IDE Controller 0</rasd:ElementName>

VMware, Inc. 179

vCloud API Programming Guide for Service Providers

<rasd:InstanceID>3</rasd:InstanceID>
<rasd:ResourceType>5</rasd:ResourceType>
</Item>
</RasdItemsList>

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... operation="Updating Virtual Application Linux FTP server (7)" ...>
...
</Task>

Specify Hard Disk IOPS

You can specify a desired level of read/write performance for a hard disk by including a vcloud:iops
attribute in the OVF Item that represents the disk configuration.

Managed read/write performance in physical storage devices and virtual disks is defined in units called
IOPS, which measure read/write operations per second. When an organization VDC storage profile is
backed by a Provider VDC storage profile that includes storage devices that are capable of IOPS allocation,
you can configure disks that use it to request a specified level of I/O performance. A storage profile
configured with IOPS support delivers its default IOPS value to all disks that use it, even disks that are not
configured to request a specific IOPS value. A hard disk configured to request a specific IOPS value cannot
use a storage profile whose maximum IOPS value is lower than the requested value, or a storage profile that
is not configured with IOPS support.

Note vCloud Director sets an IOPS limit and reservation for every disk that uses an IOPS-enabled storage
profile. vSphere is responsible for allocating the IOPS capacity of the underlying datastore across all virtual
disks that use the storage profile. IOPS management is primarily intended to ensure that no disk can
consume more than its fair share of IOPS. Realized IOPS for a given disk are limited by what the backing
LUN can provide, and can be influenced by factors such as read/write block size. While a given storage
profile can include a mix of datastores that IOPS-enabled and those that are not, such configurations can
interfere with the system's ability to allocate IOPS fairly across all disks that use the storage profile.

Specify hard disk IOPS only when you have a well-defined need for a specific level of disk performance, and
are confident that all storage profiles that the disk is likely to use can provision the desired level of IOPS.
Because requesting a specific IOPS value imposes limitation on the set of storage profiles that a virtual
machine can use, it is a best practice to avoid specifying hard disk IOPS in cases where the disk or virtual
machine is likely to migrate to environments where an appropriate storage profile is not available.

Prerequisites
This operation requires the rights included in the predefined vApp Author role or an equivalent set of
rights.

Verify that the disk can use a storage profile configured to support IOPS. See “Configure Storage I/O Control
Support in an Organization VDC,” on page 313.

Procedure
1 Retrieve the hard disk configuration from the virtual machine.

Make a GET request to the virtual machine's virtualHardwareSection/disks link.

GET [Link]

The response to this kind of request is a RasdItemsList element that contains an Item element for each
of the virtual machine's hard disks and hard disk controllers.

180 VMware, Inc.

Chapter 6 Reconfiguring vApps and Virtual Machines

2 Verify that the hard disk uses a storage profile that is configured with IOPS support.

By default, all hard disks defined in the VirtualHardwareSection element of a virtual machine use the
storage profile specified for the virtual machine. Some or all of the disks in a virtual machine can
override this default and specify their own storage profile.
a Determine whether any of the disks override the virtual machine default storage profile.

All disks that do not use the default storage profile include
vcloud:storageProfileOverrideVmDefault and vcloud:storageProfileHref attributes, as shown in
this example.

<Item>
...
<rasd:HostResource
xmlns:vcloud="[Link]
vcloud:capacity="10240"
vcloud:busSubType="lsilogic"
vcloud:busType="6"
vcloud:storageProfileOverrideVmDefault="true"
vcloud:storageProfileHref="[Link]
...
</Item>

Retrieve the storage profile by making a GET request to the URL in the vcloud:storageProfileHref
attribute.

b Disks that do not override the default storage profile use the one defined by the virtual machine.

Retrieve the Vm and examine the response to find its StorageProfile element. Retrieve the storage
profile by making a GET request to the URL in the href attribute of the StorageProfile element.
A storage profile that is configured with IOPS support includes an IopsSettings element like the one
shown here:

<VdcStorageProfile>
...
<IopsSettings>
<Enabled>true</Enabled>
<DiskIopsMax>4000</DiskIopsMax>
<DiskIopsDefault>1000</DiskIopsDefault>
<StorageProfileIopsLimit>200000</StorageProfileIopsLimit>
<DiskIopsPerGbMax>100</DiskIopsPerGbMax>
</IopsSettings>
</VdcStorageProfile>

3 In the VirtualHardwareSection element that you retrieved in Step 1, modify the rasd:HostResource
element of the Item that defines the disk for which you want to specify IOPS to add a vcloud:iops
attribute.

The value of the vcloud:iops attribute must be between 200 and 4000, and cannot be greater than the
value of DiskIopsMax for the disk's storage profile. See “Example: Specify Hard Disk IOPS,” on
page 182.

Request bodies must contain all required elements and attributes, even if you are not changing their
values. Because optional elements and attributes typically revert to default values if they are omitted or
empty, it is a best practice to include optional elements in request bodies that modify existing objects.
Link elements and href attributes from responses do not need to be included in modified sections. Some
elements and attributes are read-only and cannot be modified. See the schema reference for details.

VMware, Inc. 181

vCloud API Programming Guide for Service Providers

4 Update the section with your modifications.

a In the retrieved section, find the Link element where rel="edit".

b Make a PUT request to the URL in that link's href attribute value, and supply the modified section
as the request body.
The response to this request is a Task element that tracks the update operation. When the task is
complete, the section is updated.

Example: Specify Hard Disk IOPS

This example is similar to the ones shown in “Example: Update the Storage Profile for a Virtual Machine,”
on page 176 and “Example: Modify the Hard Disk Configuration of a Virtual Machine,” on page 174 but
adds a vcloud:iops attribute to the HostResource that defines the disk. For the purpose of this example,
assume that the virtual machine's default storage profile is enabled to provide IOPS support and does not
place a lower limit on disk IOPS than the one requested.

Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<RasdItemsList
xmlns="[Link]
xmlns:rasd="[Link]
schema/2/CIM_ResourceAllocationSettingData"
type="application/[Link]+xml" >
<Item>
<rasd:Address>0</rasd:Address>
<rasd:Description>SCSI Controller</rasd:Description>
<rasd:ElementName>SCSI Controller 0</rasd:ElementName>
<rasd:InstanceID>2</rasd:InstanceID>
<rasd:ResourceSubType>lsilogic</rasd:ResourceSubType>
<rasd:ResourceType>6</rasd:ResourceType>
</Item>
<Item>
<rasd:AddressOnParent>0</rasd:AddressOnParent>
<rasd:Description>Hard disk</rasd:Description>
<rasd:ElementName>Hard disk 1</rasd:ElementName>
<rasd:HostResource
xmlns:vcloud="[Link]
vcloud:capacity="10240"
vcloud:busSubType="lsilogic"
vcloud:busType="6"
vcloud:iops="1500"
</rasd:HostResource>
<rasd:InstanceID>2000</rasd:InstanceID>
<rasd:Parent>2</rasd:Parent>
<rasd:ResourceType>17</rasd:ResourceType>
</Item>
<Item>

182 VMware, Inc.

Chapter 6 Reconfiguring vApps and Virtual Machines

...
</Item>
...
</RasdItemsList>

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... operation="Updating Virtual Application Linux FTP server (7)" ...>
...
</Task>

VMware, Inc. 183

vCloud API Programming Guide for Service Providers

184 VMware, Inc.

Managing an Organization 7
The vCloud API supports objects and operations that an organization administrator can use to automate
tasks associated with managing organizations and the VDCs, networks, catalogs, and users they contain.

A successful login by an organization administrator returns a Session element, which contains a link that
enables the administrator to retrieve a VCloud element. This element provides links to objects in the
administrator's organization and read-only links to system-wide objects such as roles and rights. See
“Retrieve an Administrative View of a Cloud,” on page 56.

This chapter includes the following topics:

n “Administrator Credentials and Privileges,” on page 185

n “Organization Administration,” on page 186

n “VDC Administration,” on page 191

n “Network Administration,” on page 199

n “Catalog Administration,” on page 219

n “User and Group Administration,” on page 241

n “About Federation and Single Sign-On,” on page 251

n “Working With Roles and Rights,” on page 257

Administrator Credentials and Privileges

An administrator's privileges are scoped by the organization to which the administrator authenticates.

The vCloud API defines two levels of administrative privilege:

n Organization administrators, who have administrative privileges in a specific organization.

n System administrators, who have superuser privileges throughout the system. System administrators
are members of the System organization, and can create, read, update, and delete all objects in a cloud.
They have organization administrator rights in all organizations in a cloud, and can operate directly on
vSphere resources to create and modify provider VDCs, external networks, network pools, and similar
system-level objects.

Some administrative operations, and all vSphere platform operations, are restricted to the system
administrator. Before you attempt these operations, log in to the System organization with the user name and
password of the system administrator account that was created when vCloud Director was installed, or the
user name and password of any member of the System organization. For example, a system administrator
whose user name was defined as administrator would log in as administrator@System.

VMware, Inc. 185

vCloud API Programming Guide for Service Providers

The System Organization

The System organization is created automatically when vCloud Director is installed. Unlike the
organizations represented by Org and AdminOrg objects, the System organization cannot contain catalogs,
VDCs, groups, or users who are not system administrators.

The System organization is initially configured with one member, a local user defined as part of the
vCloud Director setup process. Like all organizations, the System organization is created with implicit
support for the vCloud Director integrated identity provider. A system administrator can reconfigure the
System organization to use any of the other identity providers supported by vCloud Director.

Important If you configure the System organization to use a SAML identity provider, you must specify the
vSphere SSO Service as the identity provider.

Example: The System Organization

When a system administrator logs in to the vCloud API, the OrgList in the returned Session element
contains a link to the System organization.

<OrgList ... >

...
<Org
type="application/[Link]+xml"
name="System"
href="[Link]
...
</OrgList>

Organization Administration
System administrators create organizations and organization administrators, and establish certain
organization policies. Organization administrators populate their organization with users and groups,
create and assign roles, and can update most organization policies and properties.

A cloud can contain one or more organizations. Each organization is a unit of administration for a collection
of users, groups, and computing resources. Users authenticate at the organization level, supplying
credentials established when the user was created or imported. User credentials are authenticated by the
organization's identity provider. vCloud Director includes an integrated identity provider. It also supports
several standards-based external identity providers.

Retrieve or Update Organization Settings

Organization settings define organization policies such as default lease settings for vApps and how incorrect
login attempts are handled. They also configure how the organization uses services such as email, LDAP,
and identity providers.

An AdminOrg element contains an OrgSettings element, which contains the following elements, each of
which represents a group of related organization settings. Default settings are inherited from the system.

GeneralOrgSettings Specifies storage and deployment quotas and other behaviors for virtual
machines that members of this organization own. Sets the scope of catalog
publication and subscription in this organization.

VAppLeaseSettings Controls storage and deployment leases for vApps.

VAppTemplateLeaseSettin Controls storage and deployment leases for vApp templates.

gs

186 VMware, Inc.

Chapter 7 Managing an Organization

OrgLdapSettings Defines whether this organization is connected to an LDAP service, and

whether it uses the service defined in the system LdapSettings or a custom
LDAP service. See “Configuring and Managing Federation with LDAP,” on
page 256.

OrgOAuthSettings Defines the OAuth identity provider used by this organization. See
“Configuring and Managing Federation with OAuth,” on
page 252“Configuring and Managing Federation with OAuth,” on page 252.

OrgEmailSettings Defines whether this organization uses the email service defined in the
system EmailSettings or a custom email service.

OrgPasswordPolicySettin Specifies policies to be followed when a user in this organization enters an

gs incorrect password. Initial values are inherited from the system
PasswordPolicySettings.

OrgOperationLimitsSetti Specifies limits to be placed on simultaneous resource-intensive operations

ngs and console sessions for members of this organization.

OrgGuestPersonalization Default values for GuestCustomizationSection elements in virtual machines

Settings created by this organization. See “Retrieve or Modify the
GuestCustomizationSection of a Virtual Machine,” on page 167

OrgFederationSettings Settings related to any SAML identity provider that this organization shares
with other applications or enterprises to enable single sign-on. See
“Configuring and Managing Federation with SAML,” on page 253.

Prerequisites
This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

Procedure
1 Retrieve the list of organization settings elements.

Use a request like this one:

GET [Link]

The response is an OrgSettings element.

2 Examine the OrgSettings element to find the links to the sections to view or modify.
Each section is represented in the OrgSettings element with a link where rel="down". You can use that
link to retrieve the section. The retrieved section includes a link where rel="edit". You can use that link
as the target of a PUT request that modifies the settings that the element represents. The OrgSettings
element itself also has a rel="edit" link, which you can use to update multiple settings sections in one
request.

3 Retrieve the settings element to modify.

Make a GET request to the URL in the element's href attribute value.

4 Modify the retrieved settings element.

Request bodies must contain all required elements and attributes, even if you are not changing their
values. Because optional elements and attributes typically revert to default values if they are omitted or
empty, it is a best practice to include optional elements in request bodies that modify existing objects.
Link elements and href attributes from responses do not need to be included in modified sections. Some
elements and attributes are read-only and cannot be modified. See the schema reference for details.

VMware, Inc. 187

vCloud API Programming Guide for Service Providers

5 Update the settings with your modifications.

Find the Link element in the settings element where rel="edit". Make a PUT request to the URL in that
link's href attribute value, and supply the modified section as the request body. See the request portion
of “Example: Update Organization General Settings,” on page 188.

Example: Update Organization General Settings

This example updates the general settings of the organization created in “Example: Create an Organization,”
on page 280. When you create or retrieve an AdminOrg, these settings are contained in the
OrgGeneralSettings element. To update them, you must use a GeneralOrgSettings element, which has the
same contents as OrgGeneralSettings. This update changes the limits on deployed and stored virtual
machines. The request includes all members of the GeneralOrgSettings element, even those that are not
changing. It is a best practice to include all members of the GeneralOrgSettings element in an update
request. Optional elements that are missing or empty in the request are reset to their default values.

Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<GeneralOrgSettings
xmlns="[Link]
type="application/[Link]+xml">
<CanPublishCatalogs>false</CanPublishCatalogs>
<CanPublishExternally>true</CanPublishExternally>
<CanSubscribe>false</CanSubscribe>
<DeployedVMQuota>10</DeployedVMQuota>
<StoredVmQuota>100</StoredVmQuota>
<UseServerBootSequence>false</UseServerBootSequence>
<DelayAfterPowerOnSeconds>0</DelayAfterPowerOnSeconds>
</GeneralOrgSettings>

The response contains information extracted from the request, and includes a rel="edit" link and other
attributes that the server creates.

Response:

200 OK
Content-Type: application/[Link]+xml
...
<GeneralOrgSettings
type="application/[Link]+xml"
href="[Link]
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<CanPublishCatalogs>false</CanPublishCatalogs>
<CanPublishExternally>true</CanPublishExternally>
<CanSubscribe>false</CanSubscribe>
<DeployedVMQuota>10</DeployedVMQuota>
<StoredVmQuota>100</StoredVmQuota>
<UseServerBootSequence>false</UseServerBootSequence>
<DelayAfterPowerOnSeconds>0</DelayAfterPowerOnSeconds>
</GeneralOrgSettings>

188 VMware, Inc.

Chapter 7 Managing an Organization

When you retrieve the organization after updating its GeneralOrgSettings, you can see the results of the
update in the OrgGeneralSettings element of the AdminOrg.

GET [Link]
...
<AdminOrg ...>
...
<OrgGeneralSettings
type="application/[Link]+xml"
href="[Link]
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<CanPublishCatalogs>false</CanPublishCatalogs>
<CanPublishExternally>true</CanPublishExternally>
<CanSubscribe>false</CanSubscribe>
<DeployedVMQuota>10</DeployedVMQuota>
<StoredVmQuota>100</StoredVmQuota>
<UseServerBootSequence>false</UseServerBootSequence>
<DelayAfterPowerOnSeconds>0</DelayAfterPowerOnSeconds>
</OrgGeneralSettings>
...
</AdminOrg>

Truststore and Keytab Maintenance for Organizations

You can use the vCloud API to upload and manage SSL certificates, keystores, and Kerberos keytabs for
your organization's LDAP service. You can also use the vCloud API to configure SSPI, the Microsoft Security
Support Provider Interface, for use with Active Directory.

The OrgLdapSettings element includes links that enable an organization administrator to maintain
certificates and truststores for the organization's LDAP service.

<AdminOrg ... >

...
<OrgLdapSettings ... >
...
<Link
rel="certificate:update"
type="application/[Link]+xml"

href="[Link]
<Link
rel="certificate:reset"

href="[Link]
<Link
rel="keystore:update"
type="application/[Link]+xml"

href="[Link]
<Link
rel="keystore:reset"

href="[Link]
<Link

VMware, Inc. 189

vCloud API Programming Guide for Service Providers

rel="keytab:update"
type="application/[Link]+xml"

href="[Link]
<Link
rel="keytab:reset"

href="[Link]
...
</OrgLdapSettings>
</AdminOrg>

All of these links implement similar operations. They either upload a new certificate, keytab, or keystore, or
reset or remove an existing one. vCloud Director imposes limits on upload sizes.

Table 7‑1. Truststore, Certificate, and Keytab Upload Limits

Upload Type Maximum Size in Megabytes

LDAP certificate 2

LDAP keystore 2

LDAP SSPI keytab 2

Prerequisites
This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

Procedure
1 Determine whether the request requires a body.

Requests whose rel value includes the string reset do not require a body. For details about other
request bodies, see the schema reference.

2 POST the request to the request URL.

Include the request body if one is required.

3 Take any action required by the response.

The response to an update request includes an uploadLocation parameter whose value is a URL to
which you can upload the certificate, keytab, or keystore with a PUT request. Requests whose rel value
includes the string reset return a No Content response and require no further action.

Example: Upload an SSL Certificate for an Organization LDAP Service

This example uploads an SSL certificate whose size is 892 bytes. The first step obtains an upload URL by
POSTing a CertificateUpdateParams element to the organization's
settings/ldap/action/updateLdapCertificate URL.

Request:

POST: [Link]
Content-type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<CertificateUpdateParams
fileSize="892"
xmlns="[Link]
</CertificateUpdateParams>

190 VMware, Inc.

Chapter 7 Managing an Organization

The response contains an uploadLocation parameter whose value is a URL to which you can upload the
certificate.

Response:

<CertificateUploadSocket
xmlns="[Link]
uploadLocation="[Link]
<Task
...
status="running"
operation="Updating LDAP certificate Organization (7)"
...
</Task>
</CertificateUploadSocket>

To upload the certificate, make a PUT request to the uploadLocation URL and supply the certificate in the
request body.

Request:

PUT [Link]
Content-length: 892
...serialized contents of certificate...

EOF

Response:

200 OK

VDC Administration
A newly created organization has no VDCs in it. A system administrator can use system resources to create
VDCs in an organization. A system administrator can also define VDC templates, share them with
organizations and grant organization members the right to use the templates to create VDCs in their
organization.

An organization virtual datacenter (organization VDC) is a deployment environment for virtual systems
owned by the containing organization, and an allocation mechanism for resources such as networks,
storage, CPU, and memory. In an organization VDC, computing resources are fully virtualized, and can be
allocated based on demand, service level requirements, or a combination of the two.

Create a VDC from a Template

A system administrator can define VDC templates, share them with organizations, and grant organization
members the right to use the templates to create VDCs in their organization.

A VDC template specifies a VDC configuration. If the configuration includes an Edge Gateway, the VDC can
support creation of routed organization VDC networks.

Note If you are a system administrator, you can create a VDC without using a template. See “Add a VDC
to an Organization,” on page 304.

Prerequisites
This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

VMware, Inc. 191

vCloud API Programming Guide for Service Providers

Procedure
1 Retrieve the XML representation of the admin view of your organization.

Use a request like this one:

GET [Link]

2 Examine the response to locate the Link element that contains the URL for retrieving the list of VDC
templates that are available to your organization.

This element has a rel attribute value of down and a type attribute value of
application/[Link]+xml, as shown here:

<Link
rel="down"
href="[Link]
type="application/[Link]+xml"/>

3 Retrieve the list of VDC templates.

Make a GET request to the href value in the link shown in Step 2. The response is a VdcTemplateList
that contains one or more VdcTemplate elements. Each of these elements has an href attribute whose
value is a URL you can GET to retrieve the representation of the template. If there are no VDC
templates in the list, you can ask your system administrator to create a template and share it with your
organization.

4 Retrieve a template from the list.

Each VdcTemplate in the list includes a Description that provides more information about the features
of the VDC that the template creates. For additional information, you can retrieve the
VdcTemplateSpecification from the VdcTemplate. All of these elements are read-only.

5 Instantiate the template to create a VDC in your organization.

Each organization includes an action/instantiate link that you can use with a POST request to add a
VDC to your organization that a template specifies. See “Example: Create a VDC From a Template,” on
page 192. The system administrator can impose limits on the number of VDCs that any organization
can create. If your organization already contains the maximum number of VDCs allowed by the system
administrator, the request fails.

Example: Create a VDC From a Template

This request creates a VDC from a template. If you do not specify the name attribute or include a Description
element, the new VDC is created with the name and Description shown in the template.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<InstantiateVdcTemplateParams
xmlns="[Link]
Name="templateVdc">
<Description>Example VDC from template</Description>
<Source
href="[Link]
</InstantiateVdcTemplateParams>

The response is a Task.

192 VMware, Inc.

Chapter 7 Managing an Organization

Response:

202 Accepted
Content-Type: application/[Link]+xml
<Task
name="task"
status="running"
operation="Creating Virtual Datacenter templateVdc (100)" ...
...
</Task>

Change the Name or Description of an Existing VDC

An administrator can update an existing virtual datacenter to change its name or description.

Prerequisites
n This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

n Retrieve the VDC whose name or description you want to change. If you don't know the URL of the
VDC, you can use a query like this one to retrieve a list of references all VDCs in your organization.

GET [Link]

Procedure
1 Examine the Vdc to find its rel="edit" link.

2 Create a Vdc element that contains the new name and description.

This Vdc element need only specify the new name and Description. See “Example: Change the Name
and Description of an Existing VDC,” on page 193.

3 Make a PUT request to the rel="edit" link to change the name or description of the VDC .

Supply the Vdc element as the request body.

Example: Change the Name and Description of an Existing VDC

This example changes the name and description of the VDC created in “Example: Create a VDC From a
Template,” on page 192.
Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Vdc
xmlns="[Link]
name="NewVdcName"
type="application/[Link]+xml">
<Description>New VDC description</Description>
</Vdc>

The response is a Task.

202 Accepted
Content-Type: application/[Link]+xml
<Task
name="task"

VMware, Inc. 193

vCloud API Programming Guide for Service Providers

status="running"
operation="Updating Virtual Datacenter templateVdc (130)" ...
...
</Task>

Update Organization VDC Storage Profiles

A system administrator can update the storage profiles that are available in an organization VDC. You can
add new storage profiles and remove unused storage profiles.

An organization VDC storage profile allocates a subset of the storage available in a Provider VDC storage
profile for use by vApp templates, virtual machines, and media objects in the organization VDC. For each
organization VDC storage profile you create, you must specify a storage limit, which cannot exceed the
storage available in the Provider VDC storage profile (the value of CapacityTotal–CapacityUsed in the
ProviderVdcStorageProfile). When you update organization VDC storage profiles, you can change the
default storage profile and modify the limits on existing storage profiles.

Note Storage profiles are represented as Storage Policies in the vCloud Director Web console.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the VDC in the admin view.

Use a request like this one:

GET [Link]

2 Examine the AdminVdc element to find the vdcStorageProfiles link, VdcStorageProfiles element, and
ProviderVdcReference element it contains.

The vdcStorageProfiles link has the following form:

<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />

3 Create an UpdateVdcStorageProfiles request body that specifies the details of the update.

To add a storage profile:

a Select a storage profile from the Provider VDC referenced in the ProviderVdcReference element of
the VDC you are updating.

The storage profile must not be listed in the VdcStorageProfiles element of the VDC you are
updating.

b Include an AddStorageProfile element in the UpdateVdcStorageProfiles request body.

The AddStorageProfile element must specify values for Units, Limit, and Default, and must
include a reference to the Provider VDC storage profile on which it is based. You can add multiple
storage profiles in a single request. Only one of them can specify Default as true. If any
AddStorageProfile element specifies Default as true, that storage profile becomes the new default
storage profile for the VDC.

194 VMware, Inc.

Chapter 7 Managing an Organization

To remove a storage profile:

a Examine the VdcStorageProfiles element and find the profile to remove.

b Verify that it is not the default storage profile for the VDC, and that no virtual machines are using
it.
You can use the adminVm query and filter on the storageProfileName attribute to list all storage
profiles that are in use.

c Create an UpdateVdcStorageProfiles element that contains a DeleteStorageProfile element for

each storage profile to remove.

4 POST the UpdateVdcStorageProfiles element to the VDC's vdcStorageProfiles link.

Example: Update VDC Storage Profiles

This request adds a storage profile to the VDC created in “Example: Create an Organization VDC,” on
page 306. The new storage profile is one of the profiles available from the Provider VDC that backs this
organization VDC.

One way to retrieve a list of all the Provider VDC storage profiles available from a specific Provider VDC is
to use the query service. This query applies a filter that selects only those storage profiles available from the
Provider VDC that backs the organization VDC created in “Example: Create an Organization VDC,” on
page 306.

GET [Link]
&filter=providerVdc==[Link]

The response might look something like this:

<?xml version="1.0" encoding="UTF-8"?>

<ProviderVdcStorageProfileReferences .../>
...
<ProviderVdcStorageProfileReference
type="application/[Link]+xml"
name="Gold"
id="urn:vcloud:providervdcstorageprofile:101"
href="[Link] />
<ProviderVdcStorageProfileReference
type="application/[Link]+xml"
name="Silver"
id="urn:vcloud:providervdcstorageprofile:128"
href="[Link] />
...
</ProviderVdcStorageProfileReferences>

You can use the information in the response to construct the AddStorageProfile element in the request body.
This example creates a storage profile that is not a default storage profile, and has a specific value for Limit,
5038 MB. To specify unlimited storage (subject to the capacity of the underlying Provider VDC), set the
value of Limit to 0.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<UpdateVdcStorageProfiles
xmlns="[Link] >
<AddStorageProfile>

VMware, Inc. 195

vCloud API Programming Guide for Service Providers

<Enabled>true</Enabled>
<Units>MB</Units>
<Limit>5038</Limit>
<Default>false</Default>
<ProviderVdcStorageProfile
href="[Link] />
</AddStorageProfile>
</UpdateVdcStorageProfiles>

The response is a Task.

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... >
...
</Task>

Enable, Disable, or Remove a VDC

A system administrator can use links in an AdminVdc element to enable, disable, or remove an organization
VDC.

Prerequisites
n This operation is restricted to system administrators.

n Retrieve the VDC that you want to enable, disable, or remove. If you don't know the URL of the VDC,
you can use a query like this one to retrieve a list of references all VDCs in the system.

GET [Link]

Procedure
n To enable a VDC, POST a request to its action/enable link.

n To disable a VDC, POST a request to its action/disable link.

When you disable an organization VDC, you prevent further use of its compute and storage resources.
Running vApps and powered on virtual machines continue to run, but you cannot create or start
additional vApps or virtual machines.

n To remove a VDC, remove all the objects it contains, then disable and remove it.

a Relocate or remove any vApps that have been deployed in the VDC.

b Remove any organization VDC networks that the VDC contains.

c Remove any Edge Gateways that the VDC contains.

196 VMware, Inc.

Chapter 7 Managing an Organization

d Disable the VDC by making POST a request to its action/disable link.

After the VDC is disabled, its representation includes a rel="remove" link if it no longer contains
any objects.

e Make a DELETE request to the VDC's rel="remove" link.

Note You can make a request like this one, which adds the query string recursive=true to the VDC
href, to remove a VDC that contains one or more objects as long as those objects are in a state that
normally allows removal.

DELETE [Link]

You can use an additional query parameter to force this kind of recursive removal even when the VDC
contains objects that are not in an appropriate state.

DELETE [Link]

The server takes the requested action and returns an HTTP status of 204 No Content.

Apply Access Controls to a VDC

Upon creation, an organization VDC grants full access to all members of the containing organization. An
administrator can use the vCloud API access control mechanism to restrict access to specific users.

Organization VDCs implement a subset of the access control features described in “Controlling Access to
vApps and Catalogs,” on page 91. To restrict access to a VDC, you first apply access controls that deny use
of the VDC to all users. After you do that, you can make exceptions to grant access to up to 128 individual
users. You apply VDC access controls using a controlAccess request and ControlAccessParams request body.
Values of certain elements in the request body have special meanings when applied to a VDC.

IsSharedToEveryone The value of this element specifies whether the VDC imposes any access
controls. If it is set to false, access is denied to all users except the ones
references in the AccessSettings element. If it is set to true, no access
controls apply even if you have defined them in AccessSettings.

AccessLevel A value of ReadOnly grants the subject all rights to use the VDC. In this
release, ReadOnly is the only legal VDC AccessLevel for a user.

Prerequisites
This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

Procedure
1 Retrieve the XML representation of the VDC.

Use a request like this one:

GET [Link]

2 Examine the AdminVdc element to find the controlAccess links that it contains.

3 Create a ControlAccessParams element request body that specifies the details of the update.

See “Example: Apply Access Controls to a VDC,” on page 198.

4 PUT the ControlAccessParams element to the action/controlAccess link that you retrieved in Step 2.

VMware, Inc. 197

vCloud API Programming Guide for Service Providers

Example: Apply Access Controls to a VDC

This request updates the access controls of a VDC to grant access to two external users defined in an OAuth
identity provider.. The request body, a ControlAccessParams element, specifies a value of false for the
IsSharedToEveryone element, which denies access to all users. It also includes an AccessSetting element for
each user to whom access is granted. Each of these users is identified by an ExternalSubject element. An
ExternalSubject identifies a user account defined in a supported OAuth or SAML identity provider. See
“About Federation and Single Sign-On,” on page 251. In this element, the SubjectId is the user name with
which the user logs in to the identity provider whose type is specified in IdpType. The user must be a
member of the organization that owns the VDC.

Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<ControlAccessParams xmlns="[Link]
<IsSharedToEveryone>false</IsSharedToEveryone>
<AccessSettings>
<AccessSetting>
<ExternalSubject>
<SubjectId>user1@[Link]</SubjectId>
<IsUser>true</IsUser>
<IdpType>OAUTH</IdpType>
</ExternalSubject>
<AccessLevel>ReadOnly</AccessLevel>
</AccessSetting>
<AccessSetting>
<ExternalSubject>
<SubjectId>user2@[Link]</SubjectId>
<IsUser>true</IsUser>
<IdpType>OAUTH</IdpType>
</ExternalSubject>
<AccessLevel>ReadOnly</AccessLevel>
</AccessSetting>
</AccessSettings>
</ControlAccessParams>

A user defined in the integrated identity provider is not considered external. To specify users who are
defined by the integrated identity provider, use Subject, not ExternalSubject, as shown in this fragment.

<ControlAccessParams xmlns="[Link]
<IsSharedToEveryone>false</IsSharedToEveryone>
<AccessSettings>
<AccessSetting>
<Subject
type="application/[Link]+xml"
href="[Link]
<AccessLevel>ReadOnly</AccessLevel>
</AccessSetting>
</AccessSettings>
</ControlAccessParams>

The response, a subset of which appears here, echoes the request.

198 VMware, Inc.

Chapter 7 Managing an Organization

Response:

200 OK
Content-Type: application/[Link]+xml
...
<ControlAccessParams
xmlns="[Link]
<IsSharedToEveryone>false</IsSharedToEveryone>
<AccessSettings>
...
</AccessSettings>
</ControlAccessParams>

Network Administration
A newly created organization VDC has no networks in it. After a system administrator has created the
required network infrastructure, an organization administrator can create and manage most types of
organization VDC networks.

An organization VDC can be provisioned with zero or more networks. These organization VDC networks
can be configured to provide direct or routed connections to external networks, or can be isolated from
external networks and other organization VDC networks. Routed connections require an Edge Gateway and
network pool in the VDC. The Edge Gateway provides firewall, network address translation, static routing,
VPN, and load balancing services.

About vCloud Director Networks

There are three categories of vCloud Director networks: external networks, organization VDC networks, and
vApp networks. Additional infrastructure objects such as Edge Gateways and network pools are required
by most categories of networks and must be created by a system administrator.

You must be a system administrator to create an external network, a directly connected organization VDC
network, a network pool, or an Edge Gateway. An organization administrator can create and modify routed
and isolated organization VDC networks, and any user who has vApp Author rights can create and modify
a vApp network.

vApp Networks
A vApp network is a logical network that controls how the virtual machines in a vApp connect to each other
and to organization VDC networks. Users can create and update vApp networks and connect them to
organization VDC networks. See “About vApp Networks,” on page 100.

Organization VDC Networks

An organization VDC network allows virtual machines in the organization VDC to communicate with each
other and to access other networks, including organization VDC networks and external networks, either
directly or through an Edge Gateway that can provide firewall and NAT services.

n A direct organization VDC network connects directly to an eternal network. Only a system
administrator can create a direct organization VDC network.

n A routed organization VDC network connects to an external network through an Edge Gateway. A
routed organization VDC network also requires the containing VDC to include a network pool. After a
system administrator has provisioned an organization VDC with an Edge Gateway and associated it
with a network pool, organization administrator or system administrators can create routed
organization VDC networks in that VDC.

VMware, Inc. 199

vCloud API Programming Guide for Service Providers

n An isolated organization VDC network does not require an Edge Gateway or external network, but
does require the containing VDC to be associated with a network pool. After a system administrator has
created an organization VDC with a network pool, organization administrators or system
administrators can create isolated organization VDC networks in that VDC.

n Most types of organization VDC networks do not provide any network services. Isolated organization
VDC networks can specify a DhcpPoolService, which provides DHCP addresses from several pools of
IP address ranges. All other services, such as NAT, firewall, and load balancing, are configured by a
system administrator on the Edge Gateway to which the network connects.

Table 7‑2. Types of Organization VDC Networks and Their Requirements

Organization VDC
Network Connection Description Requirements

Direct connection to an Provides direct layer 2 connectivity to machines and The cloud must contain an
external network. networks outside of the organization VDC. Machines external network.
outside of this organization VDC can connect directly
to machines within the organization VDC.

Routed connection to an Provides controlled access to machines and networks The VDC must contain an Edge
external network. outside of the organization VDC via an Edge Gateway. Gateway and a network pool.
System administrators and organization
administrators can configure network address
translation (NAT) and firewall settings on the gateway
to make specific virtual machines in the VDC
accessible from an external network.

No connection to an Provides an isolated, private network that machines in The VDC must contain a network
external network. the organization VDC can connect to. This network pool.
provides no incoming or outgoing connectivity to
machines outside this organization VDC.

By default, only virtual machines in the organization VDC that contains the network can use it. When you
create an organization VDC network, you can specify that it is shared. A shared organization VDC network
can be used by all virtual machines in the organization.

Edge Gateways
An Edge Gateway is a virtual router for organization VDC networks. You must be a system administrator to
create an Edge Gateway.

An Edge Gateway can provide any of the following services, defined in the GatewayFeatures element of the
Edge Gateway's Configuration.

FirewallService Specifies firewall rules that, when matched, block or allow incoming or
outgoing network traffic. See “Firewall Service Configurations,” on page 203.

GatewayDhcpService Provides DHCP services to virtual machines on the network. A variant of

this service, DhcpService, is intended to provide DHCP services in vApp
networks. See “Gateway DHCP Service Configurations,” on page 211.

GatewayIpsecVpnService Defines one or more virtual private networks that connect an Edge Gateway
to another network in or outside of the cloud.

LoadBalancerService Distributes incoming requests across a set of servers. See “Load Balancer
Service Configurations,” on page 209.

NatService Provides network address translation services to computers on the network.

StaticRoutingService Specifies static routes to other networks. See “Static Routing Service
Configurations,” on page 207.

200 VMware, Inc.

Chapter 7 Managing an Organization

For an example of adding services to an Edge Gateway, see “Configure Edge Gateway Services,” on
page 201. For more information about any of these services, see the vShield Administration Guide.

External Networks and Network Pools

External networks and network pools are vSphere resources backed by vSphere portgroup, VLAN, or
DVswitch objects. A system administrator must create them, as described in “Create an External Network,”
on page 297 and “Create a Network Pool,” on page 300. As a system administrator, you must supply a
reference to an external network when you create an Edge Gateway. An organization VDC must include a
reference to a network pool or it will not be able to able to contain routed or isolated networks. See “Retrieve
a List of External Networks and Network Pools,” on page 275

Configure Edge Gateway Services

An administrator can configure NAT, firewall, and similar services on an existing Edge Gateway by
updating its EdgeGatewayServiceConfiguration.

The Configuration element of an EdgeGateway includes an EdgeGatewayServiceConfiguration element,

which can contain definitions of any of the services listed in “Edge Gateways,” on page 200. Details of
service configurations vary, but the mechanism is the same for creating or updating any Edge Gateway
service. Note that some services require a reference to one or more Edge Gateway interfaces, and cannot be
configured until those interfaces exist.

Prerequisites
This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

Verify that your organization VDC contains an Edge Gateway. If it does not, a system administrator can
create one.

Verify that the Edge Gateway is not an Advanced Gateway. If the EdgeGateway element that represents this
Edge Gateway has an AdvancedNetworkingEnabled element whose value is true, using the vCloud API to
configure Edge Gateway services can produce unexpected results. Use the vCloud Director API for NSX
instead. See VMware Knowledge Base article [Link]

Procedure
1 Retrieve the XML representation of the Edge Gateway.

2 Examine the response to locate the Link element that contains the URL for configuring services on the
Edge Gateway.

This element has a rel attribute value of add and a type attribute value of
application/[Link]+xml, as the following example
shows:

<Link
href="[Link]
rel="add"
type="application/[Link]+xml"/>

3 Copy the EdgeGatewayServiceConfiguration element from the EdgeGateway you retrieved in Step 1.

The configureServices action replaces the entire contents of the existing

EdgeGatewayServiceConfiguration with the one in the request body. Using the existing
EdgeGatewayServiceConfiguration as the basis for your modifications reduces the chances of
unintentional service changes.

VMware, Inc. 201

vCloud API Programming Guide for Service Providers

4 Modify the EdgeGatewayServiceConfiguration that you copied in Step 3 to add, remove, or change the
services that this Edge Gateway offers.

An EdgeGatewayServiceConfiguration element can contain any of the following elements:

n FirewallService

n GatewayDhcpService

n GatewayIpsecVpnService

n LoadBalancerService

n NatService

n StaticRoutingService

5 POST the modified EdgeGatewayServiceConfiguration element to the URL in the value of the href
attribute of the configureServices link described in Step 2.

The server takes the requested action and returns a Task element that tracks the progress of the request.

When the task completes successfully, the EdgeGatewayServiceConfiguration element you POSTed replaces
the one you copied in Step 3.

Example: Configure Services on an Edge Gateway

This example replaces the default firewall service on the Edge Gateway created in “Create an Edge
Gateway,” on page 316. For details about this FirewallService, see “Firewall Service Configurations,” on
page 203

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<EdgeGatewayServiceConfiguration
xmlns="[Link]
<FirewallService>
<IsEnabled>true</IsEnabled>
<DefaultAction>allow</DefaultAction>
<LogDefaultAction>false</LogDefaultAction>
<FirewallRule>
<IsEnabled>true</IsEnabled>
<Description>allow incoming ssh</Description>
<Policy>allow</Policy>
<Protocols>
<Tcp>true</Tcp>
</Protocols>
<DestinationPortRange>22</DestinationPortRange>
<DestinationIp>Internal</DestinationIp>
<SourcePortRange>Any</SourcePortRange>
<SourceIp>External</SourceIp>
<EnableLogging>true</EnableLogging>
</FirewallRule>
<FirewallRule>
<IsEnabled>true</IsEnabled>
<Description>deny incoming telnet</Description>
<Policy>drop</Policy>
<Protocols>

202 VMware, Inc.

Chapter 7 Managing an Organization

<Tcp>true</Tcp>
</Protocols>
<DestinationPortRange>23</DestinationPortRange>
<DestinationIp>Internal</DestinationIp>
<SourcePortRange>Any</SourcePortRange>
<SourceIp>External</SourceIp>
<EnableLogging>false</EnableLogging>
</FirewallRule>
</FirewallService>
</EdgeGatewayServiceConfiguration>

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task
href="[Link]
...
status="running"
operation="Updating services EdgeGateway theEdge(2000)"
... >
</Task>

Firewall Service Configurations

The default FirewallService in an EdgeGatewayServiceConfiguration is enabled and configured to block all
incoming traffic. You can modify that FirewallService to allow incoming traffic, block outgoing traffic, or
both.

A firewall service configuration includes several important parameters.

Firewall Rules
Each firewall rule specifies a protocol, IP address, and port. Packets that match the criteria in the rule are
subject to an action defined in the Policy element of the rule. The action can forward the packet to the
destination IP address and port, or drop it and optionally log a message describing the packet that was
dropped. Packets that do not match any rule are subject to the policy contained in the DefaultAction
element of the FirewallService.

Firewall Rule Logging

Firewall rule actions can be logged to the system syslog server, and optionally to a syslog server you create
and manage. When you specify a value of true in the EnableLogging element of a FirewallRule, all packets
that trigger the rule are logged to the system syslog server. Logging for all rules is controlled by the value of
the LogDefaultAction element of the FirewallService.

To log firewall rule messages from this Edge Gateway to your own syslog server in addition to the system
syslog server, add a SyslogServerSettings element to its Configuration element and specify your syslog
server's IP address in the SyslogServerIp element of its TenantSyslogServerSettings.

Port and Address Ranges

These elements in a FirewallRule specify source and destination IP ports and addresses to which the rule
applies.

VMware, Inc. 203

vCloud API Programming Guide for Service Providers

Example: Firewall Service Definition with Two Rules

This fragment of an EdgeGatewayServiceConfiguration defines a firewall service with two rules: one that
allows incoming SSH connection, and one that denies incoming Telnet connections. These rules apply to any
virtual machine that connects to a network backed by this Edge Gateway. Each rule is defined in a
FirewallRule element, and can include the following specifications:

Policy The default policy value, allow, causes the firewall to forward packets that
match the rules. Specify drop to drop packets that match the rules.

Protocols By default, a rule applies to both UDP and TCP protocols. You can limit the
rule to one protocol or the other by including Tcp and Udp elements in
Protocols and specifying a value of true or false for each.

SourcePortRange Specify a source IP port or port range, or set to any to match any port.

DestinationPortRange Specify a destination IP port or port range, or set to any to match any port.

SourceIp Specify a source IP address, or use one of these strings.

Table 7‑3. SourceIp and DestinationIp Values

Value Result

Any Matches any IP address

Internal Matches any IP address originating on

an organization VDC network connected
to this EdgeGateway. When used in a
vApp network, matches any IP address
assigned to a virtual machine in the
vApp.

External Matches any IP address originating on

an external network connected to this
EdgeGateway. When used in a vApp
network, matches any IP address except
those assigned to a virtual machine in
the vApp.

DestinationIp Specify a source IP address, or use one of the strings shown in Table 7-3.

EnableLogging Set to true to log all packets that trigger this rule. See “Firewall Rule
Logging,” on page 203.

Rules are applied to packets in the order in which the FirewallRule elements appear in the FirewallService
definition.

Note The system assigns an Id value to each rule you create and uses these values when logging rule
actions.

<FirewallService>
<IsEnabled>true</IsEnabled>
<DefaultAction>allow</DefaultAction>
<LogDefaultAction>false</LogDefaultAction>
<FirewallRule>
<IsEnabled>true</IsEnabled>
<Description>allow incoming ssh</Description>
<Policy>allow</Policy>
<Protocols>
<Tcp>true</Tcp>
</Protocols>
<DestinationPortRange>22</DestinationPortRange>

204 VMware, Inc.

Chapter 7 Managing an Organization

<DestinationIp>Internal</DestinationIp>
<SourcePortRange>Any</SourcePortRange>
<SourceIp>External</SourceIp>
<EnableLogging>false</EnableLogging>
</FirewallRule>
<FirewallRule>
<IsEnabled>true</IsEnabled>
<Description>deny incoming telnet</Description>
<Policy>drop</Policy>
<Protocols>
<Tcp>true</Tcp>
</Protocols>
<DestinationPortRange>23</DestinationPortRange>
<DestinationIp>Internal</DestinationIp>
<SourcePortRange>Any</SourcePortRange>
<SourceIp>External</SourceIp>
<EnableLogging>false</EnableLogging>
</FirewallRule>
</FirewallService>

You can see this fragment in the context of an Edge Gateway configuration in “Example: Configure Services
on an Edge Gateway,” on page 202.

NAT Service Configurations

An Edge Gateway configuration can define a NAT (Network Address Translation) service that translates
source or destination IP addresses and port numbers. In the most common case, you associate a NAT service
with an uplink interface on an Edge Gateway so that addresses on organization VDC networks are not
exposed on the external network.

A NAT service in an EdgeGatewayServiceConfiguration can include one or more rules, each of which is
expressed in a GatewayNatRule element. Each rule translates the original IP address, port, or both, and
applies to a network connected to the Edge Gateway. If the network is an uplink (to an external network),
the network must include an IP sub-allocation pool.

There are two kinds of rules, as expressed in the value of the RuleType element:

SNAT Source network address translation. This kind of rule translates the packet's
source address and, optionally, source IP port to the values you specify.

DNAT Destination network address translation. This kind of rule translates the
packet's destination address and, optionally, destination IP port to the values
you specify.

VMware, Inc. 205

vCloud API Programming Guide for Service Providers

Example: NAT Service

The following fragment of an EdgeGatewayServiceConfiguration defines and enables a NatService that
applies one destination NAT rule and one source NAT rule to the uplink interface defined in
“Example: Create an Edge Gateway,” on page 318. In the DNAT rule, the OriginalIp and OriginalPort
apply to the destination IP address and port of the packet being inspected. In the SNAT rule, the OriginalIp
and OriginalPort apply to the source IP address and port of the packet being inspected. When you create an
SNAT rule, you do not need to specify values for TranslatedPort and OriginalPort, which default to any.

Note The system assigns an Id value to each rule you create and uses these values when logging rule
actions.

<?xml version="1.0" encoding="UTF-8"?>

<NatService>
<IsEnabled>true</IsEnabled>
<NatRule>
<RuleType>DNAT</RuleType>
<IsEnabled>true</IsEnabled>
<GatewayNatRule>
<Interface
href="[Link] />
<OriginalIp>[Link]</OriginalIp>
<OriginalPort>any</OriginalPort>
<TranslatedIp>[Link]</TranslatedIp>
<TranslatedPort>any</TranslatedPort>
<Protocol>any</Protocol>
<IcmpSubType>any</IcmpSubType>
</GatewayNatRule>
</NatRule>
<NatRule>
<RuleType>SNAT</RuleType>
<IsEnabled>true</IsEnabled>
<GatewayNatRule>
<Interface
href="[Link] />
<OriginalIp>[Link]-[Link]</OriginalIp>
<TranslatedIp>[Link]</TranslatedIp>
<Protocol>any</Protocol>
</GatewayNatRule>
</NatRule>
</NatService>

To add this service to an Edge Gateway, include it in an EdgeGatewayServiceConfiguration. See

“Example: Configure Services on an Edge Gateway,” on page 202.

206 VMware, Inc.

Chapter 7 Managing an Organization

Static Routing Service Configurations

An Edge Gateway or routed vApp network configuration can define a static routing service that specifies
one or more static routes.

You can create static routes between two organization VDC networks, or between routed vApp networks
that do not have overlapping IP address spaces. Static routing service details and routes are defined in a
StaticRoutingService element contained by the Features element of a vApp network's Configuration or the
GatewayFeatures element of an Edge Gateway's Configuration. A StaticRoutingService element can
contain zero or more StaticRoute elements. Each StaticRoute specification requires the following elements.

Name Name for the route.

Network Network specification in CIDR notation.

NextHopIp IP address of the next hop on the route. This address is typically the value in
the ExternalIp element of the RouterInfo from the network to which this
static route connects.

Interface Specify internal if NextHopIp contains an IP address in the same network.

Specify external if NextHopIp contains an IP address in a different network.

GatewayInterface Used when configuring a static route in an organization VDC network.

Contains a reference to the organization VDC network for which the static
route is configured.

Example: Static Routes Between Organization VDC Networks

Assume two routed organization VDC networks, as defined in this fragment of an EdgeGateway element.

<GatewayInterface>
<Name>vnic2</Name>
<DisplayName>routed1</DisplayName>
<Network
type="application/[Link]+xml"
name="routed1"
href="[Link] />
<InterfaceType>internal</InterfaceType>
<SubnetParticipation>
<Gateway>[Link]</Gateway>
<Netmask>[Link]</Netmask>
<IpAddress>[Link]</IpAddress>
</SubnetParticipation>
<IpRanges />
<UseForDefaultRoute>false</UseForDefaultRoute>
</GatewayInterface>
<GatewayInterface>
<Name>vnic3</Name>
<DisplayName>routed2</DisplayName>
<Network
type="application/[Link]+xml"
name="routed2"
href="[Link] />
<InterfaceType>internal</InterfaceType>
<SubnetParticipation>
<Gateway>[Link]</Gateway>
<Netmask>[Link]</Netmask>
<IpAddress>[Link]</IpAddress>

VMware, Inc. 207

vCloud API Programming Guide for Service Providers

</SubnetParticipation>
<IpRanges />
<UseForDefaultRoute>false</UseForDefaultRoute>
</GatewayInterface>

n The organization VDC network named routed1 has Gateway address [Link].

n The organization VDC network named routed2 has Gateway address [Link].

n The Configuration of the vApp network in vApp1 has a RouterInfo element whose ExternalIp value is
[Link].

n The Configuration of the vApp network in vApp2 has a RouterInfo element whose ExternalIp value is
[Link].

A StaticRoutingService defined by the following fragment creates a static route to vApp1 from network
routed1, and a static route to vApp2 from network routed2.

<StaticRoutingService>
<IsEnabled>true</IsEnabled>
<StaticRoute>
<Name>TovApp1</Name>
<Network>[Link]/24</Network>
<NextHopIp>[Link]</NextHopIp>
<Interface>Internal</Interface>
<GatewayInterface
type="application/[Link]+xml"
name="routed1"
href="[Link] />
</StaticRoute>
<StaticRoute>
<Name>TovApp2</Name>
<Network>[Link]/24</Network>
<NextHopIp>[Link]</NextHopIp>
<Interface>Internal</Interface>
<GatewayInterface
type="application/[Link]+xml"
name="routed2"
href="[Link] />
</StaticRoute>
</StaticRoutingService>

To add this service to an Edge Gateway, include it in an EdgeGatewayServiceConfiguration. See

“Example: Configure Services on an Edge Gateway,” on page 202.

Static Routes Between vApp Networks

For an example of a static routing service in a vApp network, see “Network Services in vApp Networks,” on
page 101.

208 VMware, Inc.

Chapter 7 Managing an Organization

Load Balancer Service Configurations

An Edge Gateway can provide load-balancing services that allow you to distribute incoming requests to a
specific external IP address across multiple internal IP addresses. Several load-balancing algorithms are
supported.

A load balancer service provides load balancing for TCP, HTTP, and HTTPS traffic. The load balancer
accepts incoming IP requests on an external or internal interface, and uses the algorithm you specify to
distribute requests across a pool of servers.

To add a load-balancer service to an Edge Gateway, include a LoadBalancerService element in the Edge
Gateway's EdgeGatewayServiceConfiguration.

Example: Load Balancer Service

This fragment of an EdgeGatewayServiceConfiguration defines a LoadBalancerService that accepts incoming
requests at external address [Link] and balances them across two servers at internal
addresses [Link] and [Link]. The following elements define a LoadBalancerService:

n A Pool that contains ServicePort and Member elements. A LoadBalancerService must include a Pool that
defines a ServicePort for each protocol on which the load balancer handles incoming requests. You can
define up to three ServicePort elements, one for each supported protocol (HTTP, HTTPS, TCP). This
load balancer handles only HTTPS requests, so it requires only one ServicePort element in its Pool.

You must specify one of the following load-balancing algorithms in the Algorithm element of the
ServicePort.

IP_HASH Selects a server based on a hash of the source and destination IP address
of each packet.

LEAST_CONN Distributes client requests to multiple servers based on the number of

connections already on the server. New connections are sent to the server
with the fewest connections.

ROUND_ROBIN Each server is used in turn according to the weight assigned to it. This is
the smoothest and fairest algorithm when the server's processing time
remains equally distributed.

URI The request URL is hashed and divided by the total weight of the running
servers. (If the request URL includes a query, it is discarded, and only the
fragment of the URL to the left of the ? is considered.) The result
designates which server receives the request, ensuring that a request is
always directed to the same server as long as all servers remain available.

The Pool in this example also defines an optional HealthCheck element that specifies parameters used
for periodic verification that all pool members are responding to requests.

Each Member element in the Pool specifies the IpAddress of a virtual machine that provides the service
being requested. Incoming requests are balanced across all members of the pool. Because the Algorithm
specified for this Pool is ROUND_ROBIN, each Member must be assigned a Weight.

n A VirtualServer element that defines the Interface, an internal or external interface defined by the
containing EdgeGateway, on which requests are accepted. The network referenced in the Interface
element must be configured with an IP sub-allocation.

Note Each Member of a load balancer Pool can contain its own ServicePort element. If this element is
present in a Member, its contents override the ServicePort element of the Pool.

VMware, Inc. 209

vCloud API Programming Guide for Service Providers

For more information about LoadBalancerService elements and attributes, see the schema reference.

<LoadBalancerService>
<IsEnabled>true</IsEnabled>
<Pool>
<Name>HTTPS_pool</Name>
<ServicePort>
<IsEnabled>true</IsEnabled>
<Protocol>HTTPS</Protocol>
<Algorithm>ROUND_ROBIN</Algorithm>
<Port>443</Port>
<HealthCheck>
<Mode>TCP</Mode>
<HealthThreshold>2</HealthThreshold>
<UnhealthThreshold>3</UnhealthThreshold>
<Interval>5</Interval>
<Timeout>15</Timeout>
</HealthCheck>
</ServicePort>
<Member>
<IpAddress>[Link]</IpAddress>
<Weight>1</Weight>
</Member>
<Member>
<IpAddress>[Link]</IpAddress>
<Weight>1</Weight>
</Member>
</Pool>
<VirtualServer>
<IsEnabled>true</IsEnabled>
<Name>Example Virtual Server</Name>
<Description>Incoming LoadBalancerService Requests</Description>
<Interface
type="application/[Link]+xml"
href="[Link] />
<IpAddress>[Link]</IpAddress>
<ServiceProfile>
<IsEnabled>true</IsEnabled>
<Protocol>HTTPS</Protocol>
<Port>443</Port>
<Persistence>
<Method>SSL_SESSION_ID</Method>
</Persistence>
</ServiceProfile>
<Logging>true</Logging>
<Pool>HTTPS_pool</Pool>
</VirtualServer>
</LoadBalancerService>

To add this service to an Edge Gateway, include it in an EdgeGatewayServiceConfiguration. See

“Example: Configure Services on an Edge Gateway,” on page 202.

210 VMware, Inc.

Chapter 7 Managing an Organization

IPsec VPN Service Configurations

An Edge Gateway configuration can define an IPsec virtual private networking (VPN) service to provide
secure virtual private networking within an organization, between organization VDC networks, or between
an organization VDC network and an external IP address.

An EdgeGateway can contain zero or more GatewayIpsecVpnService elements, each of which defines VPN
tunnels and endpoints.

Example: IPsec VPN Service in an Edge Gateway

<GatewayIpsecVpnService>
<IsEnabled>true</IsEnabled>
<Tunnel>
<Name>Example VPN Tunnel</Name>
<Description />
<IpsecVpnLocalPeer>
<Id>3786bb05-dc9a-471b-91cd-554499d45629</Id>
<Name>gw02</Name>
</IpsecVpnLocalPeer>
<PeerIpAddress>[Link]</PeerIpAddress>
<PeerId>C64E127E-5E86-C57C-17ED-EB175A7A1811</PeerId>
<LocalIpAddress>[Link]</LocalIpAddress>
<LocalId>6844BBB4-24E6-7A50-0F29-EB175A7AD899</LocalId>
<LocalSubnet>
<Name>nw01</Name>
<Gateway>[Link]</Gateway>
<Netmask>[Link]</Netmask>
</LocalSubnet>
<PeerSubnet>
<Name>nw02</Name>
<Gateway>[Link]</Gateway>
<Netmask>[Link]</Netmask>
</PeerSubnet>
<SharedSecret>L3hithJa3zH7K4q2tH...</SharedSecret>
<SharedSecretEncrypted>false</SharedSecretEncrypted>
<EncryptionProtocol>AES256</EncryptionProtocol>
<Mtu>1500</Mtu>
<IsEnabled>true</IsEnabled>
</Tunnel>
</GatewayIpsecVpnService>

To add this service to an Edge Gateway, include it in an EdgeGatewayServiceConfiguration. See

“Example: Configure Services on an Edge Gateway,” on page 202.

Gateway DHCP Service Configurations

An Edge Gateway configuration can define a DHCP service that assigns IP addresses to clients on
organization VDC networks. You can configure multiple address pools, each of which defines a range of IP
addresses that are reserved for a specific network.

DHCP services for organization VDC networks are provided by the Edge Gateway to which those network
connect. An EdgeGateway can contain an more GatewayDhcpService element. The service can define a pool of
IP addresses for each organization VDC connected to the Edge Gateway.

Note To provide DHCP services on a vApp network, use the DhcpService element.

VMware, Inc. 211

vCloud API Programming Guide for Service Providers

Example: Gateway DHCP Service

The following fragment of an EdgeGatewayServiceConfiguration defines and enables a GatewayDhcpService
that defines two Pool objects, each of which allocates a range of IP addresses for a single organization VDC
network.

<GatewayDhcpService>
<IsEnabled>true</IsEnabled>
<Pool>
<IsEnabled>true</IsEnabled>
<Network
type="application/[Link]+xml"
href="[Link] />
<DefaultLeaseTime>3600</DefaultLeaseTime>
<MaxLeaseTime>7200</MaxLeaseTime>
<LowIpAddress>[Link]</LowIpAddress>
<HighIpAddress>[Link]</HighIpAddress>
</Pool>
<Pool>
<IsEnabled>true</IsEnabled>
<Network
type="application/[Link]+xml"
href="[Link] />
<DefaultLeaseTime>3600</DefaultLeaseTime>
<MaxLeaseTime>7200</MaxLeaseTime>
<LowIpAddress>[Link]</LowIpAddress>
<HighIpAddress>[Link]</HighIpAddress>
</Pool>
</GatewayDhcpService>

To add this service to an Edge Gateway, include it in an EdgeGatewayServiceConfiguration. See

“Example: Configure Services on an Edge Gateway,” on page 202.

Create an Organization VDC Network

To add a network to an organization VDC, an administrator POSTs an OrgVdcNetwork element to the VDC's
add URL for networks. An organization VDC network with a direct connection to an external network must
be created by a system administrator. All other organization VDC network types can be created by either a
system administrator or an organization administrator.
The contents of the Configuration element of the OrgVdcNetwork define the properties of the network,
including its connections to other networks.

For more information about the types of networks you can create and the resources on which they depend,
see “About vCloud Director Networks,” on page 199.

Prerequisites
This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

Procedure
1 Retrieve the XML representation of the organization VDC to which you want to add the network.

This request retrieves the admin view of an organization VDC.

GET [Link]

212 VMware, Inc.

Chapter 7 Managing an Organization

2 Examine the response to locate the Link element that contains the URL for adding networks to the VDC.

This element has a rel attribute value of add and a type attribute value of
application/[Link]+xml, as shown here:

<Link
rel="add"
type="application/[Link]+xml"
href="[Link] />

3 Create an OrgVdcNetwork element.

4 POST the OrgVdcNetwork element to the URL described in Step 2.

The server takes the requested action and returns a Task element that tracks the progress of the request. The
Owner element of this task includes the href attribute of the new network. When the task completes, you can
use the value of this attribute with a GET request to retrieve the XML representation of the new network.

Create an Organization VDC Network With a Routed Connection

An organization VDC network with a routed connection provides controlled access to machines and
networks outside of the organization VDC. System administrators and organization administrators can
configure network address translation (NAT) and firewall settings on the network's Edge Gateway to make
specific virtual machines in the VDC accessible from an external network.

Prerequisites
n This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

Procedure
1 Retrieve the list of Edge Gateways in the organization VDC in which you plan to create the routed
network.

You can use a query like this one, where href is the value of the href attribute of your organization VDC:

[Link]

If this organization VDC does not contain any Edge Gateways, or does not contain an Edge Gateway
that has the configuration you want, a system administrator can create a new Edge Gateway. See
“Create an Edge Gateway,” on page 316.

2 Choose an Edge Gateway that has interface capacity available.

An Edge Gateway can support a maximum of nine internal and external interfaces. At least one of those
interfaces is typically consumed by a connection to an external network. Creation of a routed
organization VDC network requires the Edge Gateway to have an unused interface available for the
new network. To see how many interfaces each Edge Gateway in your organization VDC is using, you
can run the query shown in Step 1, then add the values of the numberOfExtNetworks and
numberOfOrgNetworks attributes. If the total is less than 9, the Edge Gateway can accommodate a new
routed organization VDC network.

3 Create an OrgVdcNetwork element.

a Specify a value of natRouted in the FenceMode element of the network Configuration.

You can specify additional Configuration parameters, as noted in the schema reference.

b Specify the href of the Edge Gateway you chose in Step 2 in the EdgeGateway element.
See the request portion of “Example: Create an Organization VDC Network With a Routed
Connection,” on page 214.

VMware, Inc. 213

vCloud API Programming Guide for Service Providers

4 POST the OrgVdcNetwork element to the URL for adding networks to the organization VDC.

See the request portion of “Example: Create an Organization VDC Network With a Routed
Connection,” on page 214

The server takes the requested action and returns an XML representation of the partially-created object. This
representation includes an href attribute, properties specified in the creation request, and an embedded Task
element that tracks the creation of the object. When the task completes, the object has been created, and you
can use the value of the href attribute with a GET request to retrieve the XML representation of the object.

See the response portion of “Example: Create an Organization VDC Network With a Routed Connection,”
on page 214.

Example: Create an Organization VDC Network With a Routed Connection

This example adds a routed network to the organization VDC created in “Add a VDC to an Organization,”
on page 304. The network connects through the Edge Gateway created in “Create an Edge Gateway,” on
page 316. Because the creation request sets the value of the IsShared element to true, the new network is
made available in all VDCs in this organization.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<OrgVdcNetwork
name="RoutedOVDCNet"
xmlns="[Link]
<Description>Routed through an Edge Gateway</Description>
<Configuration>
<IpScopes>
<IpScope>
<IsInherited>false</IsInherited>
<Gateway>[Link]</Gateway>
<Netmask>[Link]</Netmask>
<Dns1>[Link]</Dns1>
<DnsSuffix>[Link]</DnsSuffix>
<IpRanges>
<IpRange>
<StartAddress>[Link]</StartAddress>
<EndAddress>[Link]</EndAddress>
</IpRange>
</IpRanges>
</IpScope>
</IpScopes>
<FenceMode>natRouted</FenceMode>
</Configuration>
<EdgeGateway
href="[Link] />
<IsShared>true</IsShared>
</OrgVdcNetwork>

Response:

201 Created
Content-Type: application/[Link]+xml
...
<OrgVdcNetwork

214 VMware, Inc.

Chapter 7 Managing an Organization

xmlns="[Link]
name="RoutedOVDCNet"
type="application/[Link]+xml"
href="[Link] ...>
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="remove"
href="[Link] />
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Description>Routed through an Edge Gateway</Description>
<Tasks>
<Task
status="running"
...
operation="Creating Network RoutedOVDCNet(59)"
...
href="[Link]
</Task>
</Tasks>
<Configuration>
...
<RetainNetInfoAcrossDeployments>false</RetainNetInfoAcrossDeployments>
</Configuration>
<EdgeGateway
type="application/[Link]+xml"
name="theEdge"
href="[Link] />
<IsShared>true</IsShared>
</OrgVdcNetwork>

Note When the Task completes, the new network is represented in the EdgeGateway by a GatewayInterface
whose InterfaceType is Internal. Unlike the Uplink interface that you create when you create an
EdgeGateway, an internal interface cannot be created explicitly. It is created only as a side-effect of creating a
routed organization VDC network.

VMware, Inc. 215

vCloud API Programming Guide for Service Providers

Create an Isolated Organization VDC Network

An isolated organization VDC network provides an isolated, private network that machines in the
organization VDC can connect to. This network provides no connectivity to machines outside this
organization VDC.

Prerequisites
n This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

Procedure
1 Create an OrgNetwork element.

Specify a value of isolated in the FenceMode element of the network Configuration. See the request
portion of “Example: Create an Isolated Organization VDC Network,” on page 216.

2 POST the OrgNetwork element you created in Step 1 to the URL for adding networks to the organization
VDC

See the request portion of “Example: Create an Isolated Organization VDC Network,” on page 216.

The server takes the requested action and returns an XML representation of the partially-created object. This
representation includes an href attribute, properties specified in the creation request, and an embedded Task
element that tracks the creation of the object. When the task completes, the object has been created, and you
can use the value of the href attribute with a GET request to retrieve the XML representation of the object.

See the response portion of “Example: Create an Isolated Organization VDC Network,” on page 216.

Example: Create an Isolated Organization VDC Network

This example adds an isolated network to the organization VDC created in “Add a VDC to an
Organization,” on page 304. It includes a ServiceConfig element that configures a DHCP service for the
network. This type of DHCP service is identical to the DHCP service supported for a vApp network, and
can specify only a single IP address range. No other network services can be created in an isolated
organization VDC network.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<OrgVdcNetwork
name="Isolated"
xmlns="[Link]
<Description>Isolated Organization VDC Network</Description>
<Configuration>
<IpScopes>
<IpScope>
<IsInherited>false</IsInherited>
<Gateway>[Link]</Gateway>
<Netmask>[Link]</Netmask>
<Dns1>[Link]</Dns1>
<DnsSuffix>[Link]</DnsSuffix>
<IpRanges>
<IpRange>
<StartAddress>[Link]</StartAddress>
<EndAddress>[Link]</EndAddress>

216 VMware, Inc.

Chapter 7 Managing an Organization

</IpRange>
</IpRanges>
</IpScope>
</IpScopes>
<FenceMode>isolated</FenceMode>
</Configuration>
<ServiceConfig>
<DhcpService>
<IsEnabled>false</IsEnabled>
<DefaultLeaseTime>3600</DefaultLeaseTime>
<MaxLeaseTime>7200</MaxLeaseTime>
<IpRange>
<StartAddress>[Link]</StartAddress>
<EndAddress>[Link]</EndAddress>
</IpRange>
</DhcpService>
</ServiceConfig>
</OrgVdcNetwork>

Response:

201 Created
Content-Type: application/[Link]+xml
...
<OrgVdcNetwork
xmlns="[Link]
name="Isolated"
type="application/[Link]+xml"
href="[Link]
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="remove"
href="[Link] />
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Description>Isolated Organization Vdc Network</Description>
<Tasks>
<Task
name="task"
status="running"
operation="Creating Network Isolated(60)"
...
</Task>

VMware, Inc. 217

vCloud API Programming Guide for Service Providers

</Tasks>
<Configuration>
...
</Configuration>
<ServiceConfig>
<DhcpService>
<IsEnabled>false</IsEnabled>
<DefaultLeaseTime>3600</DefaultLeaseTime>
<MaxLeaseTime>7200</MaxLeaseTime>
<IpRange>
<StartAddress>[Link]</StartAddress>
<EndAddress>[Link]</EndAddress>
</IpRange>
</DhcpService>
</ServiceConfig>
</OrgVdcNetwork>

Synchronize Syslog Server Settings for an Edge Gateway or vApp Network

When you change the IP addresses of the primary or secondary syslog server for a cloud, you must also
synchronize the syslog server settings for each Edge Gateway or vApp network that includes a
FirewallService for which logging is enabled.

If a system administrator changes the SyslogServerSettings for a cloud, all Edge Gateways and vApp
networks that are configured with a firewall service whose EnableLogging element has a value of true must
be synchronized with the new syslog server settings so that logging to the system syslog server can continue
without interruption.

Note You do not need to synchronize syslog server settings for an Edge Gateway when you change its
TenantSyslogServerSettings.

Prerequisites
n To synchronize syslog server settings for an Edge Gateway, you must be an organization administrator
or system administrator.

n To synchronize syslog server settings for a vApp network, you must be the vApp owner.

Procedure
1 Retrieve the XML representation of the vApp network or Edge Gateway.

2 Examine the response to locate the Link element that contains the URL for the
syncSyslogServerSettings action.

This element has a rel attribute value of syncSyslogSettings and a type attribute value of
application/[Link]+xml, as shown in this excerpt:

<Link
rel="syncSyslogSettings"
type="application/[Link]+xml"

href="[Link]

3 Make a POST request to the href value of the link described in Step 2.

The request does not have a request body. The response is a task.

218 VMware, Inc.

Chapter 7 Managing an Organization

Example: Synchronize Syslog Server Settings for an Edge Gateway

This request synchronizes the syslog server settings for the Edge Gateway created in “Create an Edge
Gateway,” on page 316.

POST [Link]

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ...
status="running"
...
operation="Synchronized syslog settings for EdgeGateway theEdge(2000)>
...>
</Task>

Catalog Administration
A newly created organization has no catalogs in it. After an organization administrator or catalog author
creates a catalog, members of the organization can use it as a destination for uploads or a source of
subscription-based content.

Catalogs contain references to vApp templates and media images. You can configure a catalog in several
different ways:
n as a repository for local content that can remain private to the catalog owner or can be shared with other
users, groups, or organizations in your cloud

n as a source of published content, to which other clouds can subscribe.

n as a local repository for content published by another cloud or any Web site that hosts a VMware
Content Subscription Protocol (VCSP) endpoint.

An organization administrator or catalog owner controls catalog sharing. Organization administrators in

organizations that have permission to publish catalogs control publication and subscription options for
catalogs in their organization. A system administrator can enable background synchronization of catalogs
with external sources and set background synchronization schedules to regulate consumption of network
bandwidth by this activity.

Access to Catalogs
A catalog initially grants full control to its owner and no access to other users. The catalog owner or a user
with organization administrator or catalog author rights can grant catalog access to other members of the
organization, individually or collectively. See “Controlling Access to vApps and Catalogs,” on page 91.
Organization administrators and system administrators can share a catalog with other organizations in the
cloud.

Synchronization
The VMware Content Subscription Protocol (VCSP) is an open standard that can be implemented by any
system that can provide HTTP or HTTPS access. Because vCloud Director implements this protocol,
catalogs can subscribe to content that originates in another instance of vCloud Director or at any remote site
that supports a VCSP endpoint. When content at a remote site changes, you must synchronize the catalog
items that hold local copies of that content. Synchronization keeps a catalog up to date with its external
subscription. A catalog owner can synchronize individual catalog items or entire catalogs at any time. A
system administrator can also schedule background synchronization for catalogs, so that all externally
subscribed catalogs in the system are synchronized on a common schedule.

VMware, Inc. 219

vCloud API Programming Guide for Service Providers

Version Numbers
As part of VCSP support, catalogs and catalog items have version numbers, which are integer values that
increment monotonically. The catalog item version number increases whenever any of the following changes
occur.

n A file in the referenced entity is added, removed, or changed.

n The name or description of the catalog item is changed.

The catalog version number increases whenever any of the following changes occur.

n A catalog item is added to or removed from the catalog.

n The version number of any contained catalog item changes.

n The name or description of the catalog is changed.

A catalog with an external subscription contains the most recent version of each of its catalog items if it has
been synchronized with its external source.

Add a Catalog to an Organization

Every organization has an add URL for catalogs. An administrator or catalog author can create a catalog by
POSTing an AdminCatalog element to this URL

A new Catalog object is an empty container for catalog items, which are references to vApp templates and
media images. There are several options for creating a catalog:

n You can create a catalog to use in your own organization or cloud, to hold content that you create
locally by uploading, importing, or capturing.

n If the system administrator has given your organization permission to publish externally, you can create
a catalog that is published externally or enable external publication of a catalog that you create locally.
See “Create a Catalog For External Publication,” on page 223 and “Publish an Existing Catalog
Externally,” on page 233.

n If the system administrator has given your organization permission to subscribe to an external catalog,
you can create a catalog that downloads its contents from an external source.

Note You cannot use catalogs created from an external subscription to hold catalog items that you
create locally. Catalogs that contain catalog items created locally cannot have an external subscription.
See “Create a Catalog With an External Subscription,” on page 225.

Prerequisites
n This operation requires the rights included in the predefined Catalog Author role or an equivalent set of
rights.

n Verify that at least one VDC exists in your organization. You cannot create a catalog in an organization
that has no VDCs.

Procedure
1 Retrieve the XML representation of the organization to which to add the catalog.

Use a request like this one:

GET [Link]

220 VMware, Inc.

Chapter 7 Managing an Organization

2 Examine the response to locate the Link element that contains the URL for adding catalogs to the
organization.

This element has a rel attribute value of add and a type attribute value of
application/[Link]+xml, as shown here:

<Link
href="[Link]
rel="add"
type="application/[Link]+xml"/>

3 Create an AdminCatalog element.

See the request portion of “Example: Create a Catalog,” on page 221.

4 POST the AdminCatalog element to the organization's add URL for catalogs.

See the request portion of “Example: Create a Catalog,” on page 221.

The server creates an empty catalog and returns its representation in the response. See the response portion
of “Example: Create a Catalog,” on page 221.

Example: Create a Catalog

This example adds a catalog to the organization created in “Example: Create an Organization,” on page 280.
Because the request does not specify a CatalogStorageProfile, the catalog is created on the default storage
profile for the first VDC created in the organization. To create the catalog on a specific storage profile, you
can add a CatalogStorageProfiles element to the request. See “Specify a Storage Profile for a Catalog,” on
page 227.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<AdminCatalog
xmlns="[Link]
name="Example Catalog">
<Description>New Catalog for Example Org</Description>
</AdminCatalog>

The response contains information extracted from the request, and includes these additions that the server
creates:

n A URL, in the value of the href attribute of the response body, that references the new catalog.

n Links that implement operations on the catalog.

n A link to an alternate view of this catalog. All users can access the catalog at this URL.

n An empty CatalogItems element.

n A Task that tracks the creation of the catalog.

n An IsPublished element whose content is the string false, indicating that the catalog is not shared with
other organizations. See “Share a Catalog with All Organizations in a Cloud,” on page 230.

n A VersionNumber element with an initial value of 1. See “Version Numbers,” on page 220.

VMware, Inc. 221

vCloud API Programming Guide for Service Providers

Response:

201 Created
Content-Type: application/[Link]+xml
...
<AdminCatalog
xmlns:vcloud="[Link]
name="Example Catalog"
id="urn:vcloud:catalog:32"
type="application/[Link]+xml"
href="[Link]
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="alternate"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="remove"
href="[Link] />
<Link ... >
...
<Tasks>
<Task
status="running"
...
operation="Creating Catalog Example Catalog (32)"
...>
...
<Task>
<Tasks>
<Description>New Catalog for Example Org</Description>
<CatalogItems/>
<IsPublished>false</IsPublished>
<DateCreated>2013-06-18T[Link].260-07:00</DateCreated>
<VersionNumber>1</VersionNumber>
<CatalogStorageProfiles/>
</AdminCatalog>

222 VMware, Inc.

Chapter 7 Managing an Organization

Create a Catalog For External Publication

An organization administrator in an organization that has permission to publish externally can create a
catalog whose contents, catalog items created locally, are made available to external consumers on a
subscription basis.

Organizations that are permitted to publish externally can enable any of their catalogs for external
publication. A catalog that is enabled for external publication becomes accessible at a URL assigned by the
system, and can be protected by a password. A catalog in another instance of vCloud Director can subscribe
to an externally published catalog and maintain an up-to-date set of catalog items. See “Synchronization,”
on page 219.

You can use this procedure to create a new catalog that is enabled for external publication, or you can use
the procedure shown in “Publish an Existing Catalog Externally,” on page 233 to enable an existing catalog
for external publication. If a catalog has an external subscription, you cannot enable it for external
publication.

Prerequisites
n This operation requires the rights included in the predefined Catalog Author role or an equivalent set of
rights.

n Verify that at least one VDC exists in your organization. You cannot create a catalog in an organization
that has no VDCs.

n Verify that your organization has permission to publish externally.

The OrgGeneralSettings in the AdminOrg element that represents your organization must have a
CanPublishExternally element with a value of true.

<CanPublishExternally>true</CanPublishExternally>

Retrieve the XML representation of the organization to which to add the catalog, and examine the response
to locate the Link element that contains the URL for adding catalogs to the organization. See “Add a Catalog
to an Organization,” on page 220.

Procedure
1 Create an AdminCatalog element that includes PublishExternalCatalogParams.

See the request portion of “Example: Create a Catalog For External Publication,” on page 223.

2 POST the AdminCatalog element to the organization's add URL for catalogs.

See the request portion of “Example: Create a Catalog For External Publication,” on page 223.

The server creates an empty catalog and returns its representation in the response. See the response portion
of “Example: Create a Catalog,” on page 221.

Example: Create a Catalog For External Publication

This request is similar to the one used in “Example: Create a Catalog,” on page 221 but includes a
PublishExternalCatalogParams element that specifies that the catalog is to be published externally. This
request creates the catalog with a content cache, which can improve synchronization performance for
external catalogs that subscribe to this one, but requires enough space on the system's transfer storage to
accommodate all of the items in the catalog. This request also sets the PreserveIdentityInfoFlag element to
false, which prevents values such as the BIOS UUID and MAC address associated with virtual machine
identities from being published. If you omit this element or set its value to true, these values are published
for all catalog items that represent virtual machines.

VMware, Inc. 223

vCloud API Programming Guide for Service Providers

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<AdminCatalog
xmlns="[Link]
name="PublishedExternally">
<Description>Example Catalog for External Publication</Description>
<PublishExternalCatalogParams>
<IsPublishedExternally>true</IsPublishedExternally>
<IsCacheEnabled>true</IsCacheEnabled>
<PreserveIdentityInfoFlag>false</PreserveIdentityInfoFlag>
<Password>Pa55w0rd</Password>
</PublishExternalCatalogParams>
</AdminCatalog>

The response is similar to the one shown in “Example: Create a Catalog,” on page 221, but includes the
PublishExternalCatalogParams element. The embedded Task element tracks the creation of the catalog and
its accompanying Web site. The Password element in the request is never returned.

Response:

201 Created
Content-Type: application/[Link]+xml
...
<AdminCatalog
xmlns:vcloud="[Link]
name="PublishedExternally"
id="urn:vcloud:catalog:33"
type="application/[Link]+xml"
href="[Link]
...
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<Link ... >
...
<Tasks>
<Task
status="running"
...
operation="Creating Catalog PublishedExternally (33)"
...>
...
<Task>
<Tasks>
<Description>Example Catalog for External Publication</Description>
<CatalogItems/>
<IsPublished>false</IsPublished>
<DateCreated>2013-06-18T[Link].131-07:00</DateCreated>
<VersionNumber>1</VersionNumber>
<CatalogStorageProfiles/>
<PublishExternalCatalogParams>
<IsPublishedExternally>true</IsPublishedExternally>

224 VMware, Inc.

Chapter 7 Managing an Organization

<IsCacheEnabled>true</IsCacheEnabled>
<PreserveIdentityInfoFlag>false</PreserveIdentityInfoFlag>
</PublishExternalCatalogParams>
</AdminCatalog>

When the task completes, the PublishExternalCatalogParams includes a URL at which external consumers
can connect to the catalog.

<AdminCatalog ... >

...
<PublishExternalCatalogParams>
<IsPublishedExternally>true</IsPublishedExternally>
<IsCacheEnabled>true</IsCacheEnabled>
<CatalogPublishedUrl>[Link]
</PublishExternalCatalogParams>
</AdminCatalog>

Create a Catalog With an External Subscription

An organization administrator in an organization that has permission to subscribe can create a catalog
whose contents are downloaded from an external source. You cannot use catalogs created this way to hold
catalog items that are created locally.

Organizations that are permitted to subscribe to external sources can create catalogs whose contents are
downloaded from a catalog hosted on another instance of vCloud Director, or any Web site that implements
the VMware Content Subscription Protocol (VCSP) . See “Synchronization,” on page 219.

If a catalog has an external subscription, you cannot enable it for external publication.

Prerequisites
n This operation requires the rights included in the predefined Catalog Author role or an equivalent set of
rights.

n Verify that at least one VDC exists in your organization. You cannot create a catalog in an organization
that has no VDCs.

n Verify that your organization has permission to create catalogs with external subscriptions.

The OrgGeneralSettings in the AdminOrg element that represents your organization must have a
CanSubscribe element with a value of true.

<CanSubscribe>true</CanSubscribe>

n The external source must implement the VMware Content Subscription Protocol. See
“Synchronization,” on page 219.

n You must know the URL of the external source, and the password if one is required.

Retrieve the XML representation of the organization to which you want to add the catalog, and examine the
response to locate the Link element that contains the URL for adding catalogs to the organization. See “Add
a Catalog to an Organization,” on page 220.

Procedure
1 Create an AdminCatalog element that includes ExternalCatalogSubscriptionParams.

See the request portion of “Example: Create a Catalog With an External Subscription,” on page 226.

2 POST the AdminCatalog element to the organization's add URL for catalogs.

See the request portion of “Example: Create a Catalog With an External Subscription,” on page 226.

VMware, Inc. 225

vCloud API Programming Guide for Service Providers

The server creates an empty catalog and returns its representation in the response. See the response portion
of “Example: Create a Catalog,” on page 221.

Example: Create a Catalog With an External Subscription

This request creates a catalog with a subscription to the VCSP URL
[Link] Because the LocalCopy element in
ExternalCatalogSubscriptionParams has a value of false, files that comprise a vApp template or media
image that a catalog item references are not downloaded until a user requests them. If you create a catalog
where LocalCopy has a value of true, these files are downloaded the first time that the catalog subscription is
synchronized, and on each subsequent synchronization where any of the catalog items has a newer version
number. The default value of LocalCopy isfalse.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<AdminCatalog
xmlns="[Link]
name="SubscribedExternally">
<Description>Example Catalog With External Subscription</Description>
<ExternalCatalogSubscriptionParams>
<SubscribeToExternalFeeds>true</SubscribeToExternalFeeds>
<Location>[Link]
<Password>Pa55w0rd</Password>
<LocalCopy>false</LocalCopy>
</ExternalCatalogSubscriptionParams>
</AdminCatalog>

The response is similar to the one shown in “Example: Create a Catalog,” on page 221, but includes the
ExternalCatalogSubscriptionParams element that you supplied in the request. The Password element in the
request is never returned.

Response:

201 Created
Content-Type: application/[Link]+xml
...
<AdminCatalog
xmlns:vcloud="[Link]
name="SubscribedExternally"
id="urn:vcloud:catalog:34"
type="application/[Link]+xml"
href="[Link]
...
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<Link ... >
<Link
rel="sync"
href="[Link]
<Link ... >
...
<Tasks>

226 VMware, Inc.

Chapter 7 Managing an Organization

<Task
status="running"
...
operation="Creating Catalog SubscribedExternally (34)"
...
<Task>
<Tasks>
<Description>Example Catalog With External Subscription</Description>
<CatalogItems/>
<IsPublished>false</IsPublished>
<DateCreated>2013-06-18T[Link].012-07:00</DateCreated>
<VersionNumber>1</VersionNumber>
<CatalogStorageProfiles/>
<ExternalCatalogSubscriptionParams>
<SubscribeToExternalFeeds>true</SubscribeToExternalFeeds>
<Location>[Link]
<LocalCopy>false</LocalCopy>
</ExternalCatalogSubscriptionParams>
</AdminCatalog>

What to do next
Synchronize the catalog with its external source. Any catalog with an external subscription includes a link of
the form:

<Link
rel="sync"
href="[Link]

As a catalog owner or administrator, you can POST a request to the rel="sync" URL to synchronize the
catalog with its external source. See “Synchronize a Catalog or Catalog Item,” on page 84.

Specify a Storage Profile for a Catalog

Any request that creates a catalog can also specify a storage profile for the items in that catalog.

If you do not specify a CatalogStorageProfile when creating a catalog, the catalog is created on the default
storage profile for the first VDC created in the organization. To create the catalog on a specific storage
profile, retrieve the list of available storage profiles in your organization and specify one in the
CatalogStorageProfiles element of the request.

Prerequisites
n This operation requires the rights included in the predefined Catalog Author role or an equivalent set of
rights.

n Verify that at least one VDC exists in your organization. You cannot create a catalog in an organization
that has no VDCs.

Procedure
1 Find the list of storage profiles in your organization.

Use a query like this one.

[Link]

VMware, Inc. 227

vCloud API Programming Guide for Service Providers

The response is a list of references to all the storage profiles used by VDCs in your organization.

<OrgVdcStorageProfileReferences ... >

<OrgVdcStorageProfileReference
type="application/[Link]+xml"
name="*"
id="urn:vcloud:vdcstorageProfile:59"
href="[Link] />
<OrgVdcStorageProfileReference
type="application/[Link]+xml"
name="Silver"
id="urn:vcloud:vdcstorageProfile:84"
href="[Link] />
</OrgVdcStorageProfileReferences>

Note If you are a system administrator, you must filter the response to show only those storage
profiles in the organization where you are creating the catalog.

2 Create an AdminCatalog element that includes a CatalogStorageProfiles element.

You can include a single CatalogStorageProfile in the request. Only the type and href attributes are
required. See the request portion of “Example: Specify a Storage Profile for a Catalog,” on page 228.

3 POST the AdminCatalog element to the organization's add URL for catalogs.

See the request portion of “Example: Specify a Storage Profile for a Catalog,” on page 228.

The server creates an empty catalog on the specified storage profile and returns its representation in the
response. See the response portion of “Example: Create a Catalog,” on page 221.

Example: Specify a Storage Profile for a Catalog

This example modifies the request shown in “Example: Create a Catalog,” on page 221 to add a
CatalogStorageProfiles element..

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<AdminCatalog
xmlns="[Link]
name="Example Catalog">
<Description>New Catalog for Example Org</Description>
<CatalogStorageProfiles>
<VdcStorageProfile
type="application/[Link]+xml"
href="[Link] />
</CatalogStorageProfiles>
</AdminCatalog>

The response is similar to the one shown in “Example: Create a Catalog,” on page 221, and includes a
CatalogStorageProfiles element derived form the one that you specified in the request.

Response:

201 Created
Content-Type: application/[Link]+xml
...
<AdminCatalog

228 VMware, Inc.

Chapter 7 Managing an Organization

xmlns:vcloud="[Link]
name="Example Catalog"
...

<Description>New Catalog for Example Org</Description>

<CatalogItems/>
...
<CatalogStorageProfiles>
<VdcStorageProfile
type="application/[Link]+xml"
name="*"
id="urn:vcloud:vdcstorageProfile:59"
href="[Link] />
</CatalogStorageProfiles>
</AdminCatalog>

Update Catalog Access Controls

If you are an administrator or catalog owner, you can use a catalog's controlAccess links to grant or restrict
access to the catalog.

A catalog initially grants full access to its owner and no access to other users. An administrator or the
catalog owner can use the vCloud API access control mechanism to view or modify catalog access controls.
For a general discussion of access controls in vCloud Director, see “Controlling Access to vApps and
Catalogs,” on page 91.

Procedure
1 Retrieve the XML representation of the catalog.

Use a request like this one:

GET [Link]

2 Examine the Catalog response to find the controlAccess links that it contains.

These links have the following form:

<Link
rel="down"
type="application/[Link]+xml"
href="[Link]
<Link
rel="controlAccess"
type="application/[Link]+xml"
href="[Link]

3 Create a ControlAccessParams element request body that specifies the details of the update.

4 POST the ControlAccessParams element to the action/controlAccess link for the catalog.

Example: Update Catalog Access Controls

This request updates the access controls of a catalog to grant full control to one user and read-only access to
another user. The request body, a ControlAccessParams element, specifies a value of false for the
IsSharedToEveryone element, and contains an AccessSetting element for each user whose access rights are
being modified. Each user is identified by a reference to a User object. See “User and Group
Administration,” on page 241. The response, a subset of which appears in this example, echoes the request.

VMware, Inc. 229

vCloud API Programming Guide for Service Providers

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<ControlAccessParams
xmlns="[Link]
<IsSharedToEveryone>false</IsSharedToEveryone>
<AccessSettings>
<AccessSetting>
<Subject
type="application/[Link]+xml"
href="[Link]
<AccessLevel>FullControl</AccessLevel>
</AccessSetting>
<AccessSetting>
<Subject
type="application/[Link]+xml"
href="[Link]
<AccessLevel>ReadOnly</AccessLevel>
</AccessSetting>
</AccessSettings>
</ControlAccessParams>

Response:

200 OK
Content-Type: application/[Link]+xml
...
<ControlAccessParams
xmlns="[Link]
<IsSharedToEveryone>false</IsSharedToEveryone>
<AccessSettings>
...
</AccessSettings>
</ControlAccessParams>

Share a Catalog with All Organizations in a Cloud

An organization administrator can share a catalog to make it visible to the administrators in all other
organizations in a cloud.

The owner of a catalog can make it available to other users in the containing organization. See “Update
Catalog Access Controls,” on page 229. If you are an organization administrator, you can also share catalogs
with all other organizations in your cloud if your organization's CanPublishCatalogs element has a value of
true. The value of this element is controlled by the system administrator. To share a catalog, make a POST
request to the catalog’s action/publish URL and supply a PublishCatalogParams body that sets the value of
the catalog’s IsPublished element to true.

Prerequisites
This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

230 VMware, Inc.

Chapter 7 Managing an Organization

Procedure
1 Retrieve the XML representation of the catalog to share.

Use a request like this one, where id is the identifier of the catalog:

GET [Link]

2 Examine the response to locate the Link element that contains the URL for publishing the catalog.

This element has a rel attribute value of publish and a type attribute value of
application/[Link]+xml, as this example shows:

<Link
rel="publish"
type="application/[Link]+xml"
href="[Link] />

3 Create a PublishCatalogParams element that contains an IsPublished element with a value of true.

4 POST the PublishCatalogParams body to the catalog's rel="publish" URL.

The catalog is shared and becomes available to members of all other organizations in the cloud.

Example: Share a Catalog With All Organizations in a Cloud

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<PublishCatalogParams
xmlns="[Link]
<IsPublished>true</IsPublished>
</PublishCatalogParams>

Response:

204 No Content

Share a Catalog With Specific Organizations in a Cloud

A system administrator can share a catalog to make it visible to the administrators of specific organizations
in a cloud.

The owner of a catalog can share it to make it available to all organizations in the cloud. When more
selective sharing is required, a system administrator can share a catalog with specific organizations if that
catalog is not already shared to all organizations.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the catalog.

Use a request like this one:

GET [Link]

VMware, Inc. 231

vCloud API Programming Guide for Service Providers

2 Examine the Catalog response to find the controlAccess links that it contains.

These links have the following form:

<Link
rel="down"
type="application/[Link]+xml"
href="[Link]
<Link
rel="controlAccess"
type="application/[Link]+xml"
href="[Link]

3 Create a ControlAccessParams element request body that specifies the details of the update.

4 POST the ControlAccessParams element to the action/controlAccess link for the catalog.

The catalog is shared with administrators of the specified organizations.

Example: Share a Catalog With Specific Organizations in a Cloud

This request updates the access controls of a catalog to share it to a single organization, giving read-only
access to all users in that organization.
Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<ControlAccessParams
xmlns="[Link]
<IsSharedToEveryone>false</IsSharedToEveryone>
<AccessSettings>
<AccessSetting>
<Subject
type="application/[Link]+xml"
href="[Link]
<AccessLevel>ReadOnly</AccessLevel>
</AccessSetting>
</AccessSettings>
</ControlAccessParams>

Response:

200 OK
Content-Type: application/[Link]+xml
...
<ControlAccessParams
xmlns="[Link]
<IsSharedToEveryone>false</IsSharedToEveryone>
<AccessSettings>
<AccessSetting>
<Subject
type="application/[Link]+xml"
href="[Link]

232 VMware, Inc.

Chapter 7 Managing an Organization

<AccessLevel>ReadOnly</AccessLevel>
</AccessSetting>
</AccessSettings>
</ControlAccessParams>

Publish an Existing Catalog Externally

An organization administrator in an organization that has permission to publish externally can update an
existing catalog to make its contents available to external consumers on a subscription basis.

Organizations that are permitted to publish externally can enable any of their local catalogs for external
publication. A catalog that is enabled for external publication becomes accessible at a URL assigned by the
system, and can be protected by a password. A catalog in another instance of vCloud Director can subscribe
to an externally published catalog and maintain an up-to-date set of catalog items. See “Synchronization,”
on page 219.

Prerequisites
n This operation requires the rights included in the predefined Catalog Author role or an equivalent set of
rights.

n Verify that your organization has permission to publish externally.

Verify that the OrgGeneralSettings in the AdminOrg element that represents your organization has a
CanPublishExternally element with a value of true.

<CanPublishExternally>true</CanPublishExternally>

n Verify that the catalog you want to enable for external publication does not have an external
subscription.

Procedure
1 In the admin view, retrieve the XML representation of the catalog.

Use a request like this one:

GET [Link]

2 Examine the AdminCatalog element to find the publishToExternalOrganizations link it contains.

This link has the following form:

<Link
rel="publishToExternalOrganizations"
type="application/[Link]+xml"

href="[Link]
/>

3 Create a PublishExternalCatalogParams element.

See “Example: Publish an Existing Catalog,” on page 233.

4 POST the PublishExternalCatalogParams element to the publishToExternalOrganizations URL.

Example: Publish an Existing Catalog

This request updates the catalog created in “Example: Create a Catalog,” on page 221 to publish it externally.

VMware, Inc. 233

vCloud API Programming Guide for Service Providers

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<PublishExternalCatalogParams
xmlns="[Link]
<IsPublishedExternally>true</IsPublishedExternally>
Password>Pa55w0rd</Password>
</PublishExternalCatalogParams>

Response:

204 No Content

Content Subscription Endpoint Specification

This document specifies the requirements for creating an endpoint that is compatible with a client using
version 1 of the VMware Content Subscription Protocol (VCSP). VMware vCloud Director catalogs use this
protocol when synchronizing content from an external subscription.

Introduction
VMware vCloud Director enables organizations to create catalogs that acquire their content from a
subscription to an external source. The external source can be an externally published catalog hosted on
another instance of vCloud Director or a Web site that hosts a VCSP endpoint.

Configuration parameters for vCloud Director catalogs that have external subscriptions include a VCSP
endpoint URL and, if the endpoint requires authentication, a user name and password. Users periodically
synchronize to update catalog contents from the subscribed endpoint. You can request synchronization for
an entire catalog, or for individual catalog items. The process is similar in both cases.

1 The VCSP client makes a GET request to retrieve the endpoint descriptor. If the version in the descriptor
matches the version of the catalog being synchronized, no content has changed at the endpoint, and no
further action is required.

2 If the version in the descriptor is greater than the version of the catalog, the client makes a GET request
to retrieve the endpoint index file.

3 To update the entire catalog, the client makes GET requests to retrieve all catalog items whose version at
the endpoint is greater than their version in the catalog. To update an individual catalog item, the client
makes a GET request to retrieve it only if its version number at the endpoint is greater than its version
in the catalog.

The endpoint is a passive partner in this process. Its only responsibilities are to keep the version numbers up
to date in the endpoint descriptor and endpoint index files, and to return the HTTP status codes and other
responses expected by the VCSP client.

URLs
A VCSP endpoint URL must have a scheme of HTTP or HTTPS and a path that terminates in the name of
the endpoint descriptor. A VCSP endpoint whose contents are stored on a host named [Link] in
a directory named /vcsp on the host and whose descriptor file is named [Link] would have the
following endpoint URL:

[Link]

234 VMware, Inc.

Chapter 7 Managing an Organization

Endpoint Descriptor
The endpoint descriptor is a file whose contents define the catalog available at the endpoint. The contents,
which must be expressed in JavaScript Object Notation (media type application/json) as defined by
RFC4627, define a JSON object, and must specify values for the following key names.

vcspVersion An integer that specifies the version of the VCSP protocol to which this
endpoint conforms.

version An integer that specifies the version of the catalog, as described in “Version
Numbers,” on page 241.

id The object identifier, expressed in URN format. This value uniquely identifies
the catalog, persists for the life of the catalog, and must never be reused.

name The display name of the catalog. Must be a nonempty string.

created Time and date when the endpoint was created.

itemType Must have value [Link].

itemsHref A reference to the endpoint index file relative to the location of the endpoint
descriptor. Replacing the final component of the endpoint URL with the
value of the itemsHref key must create a valid URL.

capabilities A JSON object that describes the capabilities of this catalog. The object must
define all of the following properties:

transferIn An array with a single member that must be the

string httpGet.

transferOut An array with a single member that must be the

string httpGet.

generateIds A Boolean value that must be set to true.

metadata An array of catalog object metadata. See “Metadata,” on page 239.

maintenanceMessage A string indicating that the endpoint is inaccessible because it is undergoing

maintenance. For example:

"maintenanceMessage" : "This catalog is currently in maintenance

mode"

If the endpoint descriptor includes this key, attempts by subscribers to

synchronize with this endpoint fail and display the string.

The following example shows a typical endpoint descriptor.

{
"vcspVersion" : "1",
"version" : "10",
"id" : "urn:uuid:ccdd2c56-e54e-4883-bc0a-619baaca92a6",
"name" : "published",
"created" : "2012-09-14T[Link].807Z",
"itemType" : "[Link]",
"itemsHref" : "items",
"capabilities" : {
"transferIn" : [ "httpGet" ],
"transferOut" : [ "httpGet" ],
"generateIds" : true

VMware, Inc. 235

vCloud API Programming Guide for Service Providers

}
"metadata" : [ {
"type" : "STRING",
"domain" : "GENERAL",
"key" : "key1",
"value" : "value1",
"visibility" : "READWRITE"
}, {
"type" : "STRING",
"domain" : "SYSTEM",
"key" : "key2",
"value" : "value2",
"visibility" : "READONLY"
} ]
}

Endpoint Index
The endpoint index is a file whose contents define the set of items available in the catalog. The contents,
which must be expressed in JavaScript Object Notation (media type application/json) as defined by
RFC4627, define a JSON object, and must specify values for the following key names.

itemType Must be [Link].

items An array of zero or more item objects. Each item object must specify values
for the following key names.

version An integer that specifies the version of the item, as

described in “Version Numbers,” on page 241.

id The object identifier of the item, expressed in URN

format. This value uniquely identifies the item,
persists for the life of the item, and must never be
reused.

name The display name of the item. Must be a nonempty

string.

created Time and date when the item was created.

type Item type. Must have one of the following values:

n [Link] if the item is an ISO image.

n [Link] if the item is an OVF package.

236 VMware, Inc.

Chapter 7 Managing an Organization

files An array of file objects that includes all the files that
represent the item. Each file object is represented as
an array with three elements:

etag An integer representing the

version of the file. The value of
this key must be the same for each
file in the array. When any file in
this array gets updated, you must
increment the value of the etag
key for all files in the array.

name The name of the file.

hrefs An array of pathnames to the file.

Must contain a single pathname
to the file from the root of the
endpoint, written as a URL
fragment.

properties An array of additional properties of the item. This

array has a single member:

selfHref A URL to the item descriptor for

this item. See “Item Descriptors,”
on page 239.

metadata An array of catalog item metadata. See “Metadata,”

on page 239.

vms If this item represents a vApp template, you must

include an array representing the virtual machines
referenced in the template.

name The name of the virtual machine.

metadata An array of virtual machine

metadata. See “Metadata,” on
page 239.

version An integer that specifies the version of the endpoint index, as described in
“Version Numbers,” on page 241.

The following example shows a typical endpoint index.

{
"itemType" : "[Link]",
"items" : [ {
"version" : "1",
"id" : "urn:uuid:6dfa4596-a7c5-4d62-9a84-c559968baa26",
"name" : "vapp-demo",
"created" : "2012-09-17T[Link].161Z",
"type" : "[Link]",
"files" : [ {
"etag" : "37"
"name" : "[Link]",
"hrefs" : [ "/vcsp/item/6dfa4596-a7c5-4d62-9a84-c559968baa26/file/[Link]" ]

VMware, Inc. 237

vCloud API Programming Guide for Service Providers

}, {
"name" : "[Link]",
"hrefs" : [ "/vcsp/item/6dfa4596-a7c5-4d62-9a84-c559968baa26/file/[Link]" ]
}, {
"etag" : "37"
"name" : "[Link]",
"hrefs" : [ "/vcsp/item/6dfa4596-a7c5-4d62-9a84-c559968baa26/file/vm-d5349476-aae2-4b65-
[Link]" ]
} ],
"properties" : {
},
"selfHref" : "/vcsp/item/6dfa4596-a7c5-4d62-9a84-c559968baa26/[Link]"
}, {
"version" : "2",
"id" : "urn:uuid:b63c9bbe-3614-4153-82fd-d5f4916a1327",
"name" : "template1",
"created" : "2012-09-14T[Link].858Z",
"description" : "Added with VMware OVFTool.",
"type" : "[Link]",
"files" : [ {
"name" : "[Link]",
"hrefs" : [ "/vcsp/item/b63c9bbe-3614-4153-82fd-d5f4916a1327/file/[Link]" ]
}, {
"name" : "[Link]",
"hrefs" : [ "/vcsp/item/b63c9bbe-3614-4153-82fd-d5f4916a1327/file/[Link]" ]
}, {
"name" : "[Link]",
"hrefs" : [ "/vcsp/item/b63c9bbe-3614-4153-82fd-d5f4916a1327/file/vm-3fe8a95b-ccd1-4816-
[Link]" ]
} ],
"properties" : {
},
"selfHref" : "/vcsp/item/b63c9bbe-3614-4153-82fd-d5f4916a1327/[Link]"
} ],
"metadata" : []
"vms" : [ {
"name" : "vm1",
"metadata" : [ ]

}, {
"name" : "vm2",
"metadata" : []
} ]
}, {
"version" : "10"
}

238 VMware, Inc.

Chapter 7 Managing an Organization

Metadata
The endpoint descriptor and endpoint index allow you to include object metadata that is used to create
vCloud Director object metadata when endpoint contents are synchronized by a subscribed catalog. For
more information about the design and operation of vCloud Director object metadata, see Chapter 9,
“Working With Object Metadata,” on page 357.

metadata An array of object metadata. You may include an arbitrary number of

metadata objects in this array, subject to the size limitations documented in
“vCloud API Object Metadata Limits,” on page 359

type The type of the metadata value. One of STRING,

BOOLEAN, DATETIME or NUMBER. See “vCloud API Object
Metadata Contents,” on page 358.

domain The access domain of the metadata. One of GENERAL

or SYSTEM. See “Access Control for vCloud API Object
Metadata,” on page 359. WhenvCloud Director
object metadata is created from this endpoint, the
metadata domain is always set to SYSTEM, regardless
of the value you supply here.

key An arbitrary key name.

value The value of the key.

visibility The visibility the metadata. One of PRIVATE, READONLY

or READWRITE. See “Access Control for vCloud API
Object Metadata,” on page 359. When
vCloud Director object metadata is created from this
catalog item, the metadata visibility is always set
to READONLY, regardless of the value you supply here.

Item Descriptors
Every item listed in the endpoint index must include an item descriptor file in the directory that holds all the
item's files. The contents, which must be expressed in JavaScript Object Notation (media type
application/json) as defined by RFC4627, define a JSON object, and must specify values for the following
key names.

version An integer that specifies the version of the item, as described in “Version
Numbers,” on page 241.

id The object identifier, expressed in URN format. This value uniquely identifies
the catalog, persists for the life of the catalog, and must never be reused.

name The display name of the catalog. Must be a nonempty string.

created Time and date when the endpoint was created.

description A description of the item, as it will appear in the destination catalog.

type Item type. Must have one of the following values:

n [Link] if the item is an ISO image.

n [Link] if the item is an OVF package.

VMware, Inc. 239

vCloud API Programming Guide for Service Providers

files An array of file objects that includes all the files that represent the item.
Each file object is represented as an array with two elements:

name The name of the file.

hrefs An array of pathnames to the file. Must contain a

single pathname to the file from the root of the
endpoint, written as a URL fragment.

properties An array of additional properties of the item. Must be empty.

The following example shows a typical item descriptor for an OVF package.

{
"version" : "1",
"id" : "urn:uuid:b63c9bbe-3614-4153-82fd-d5f4916a1327",
"name" : "template1",
"created" : "2012-09-14T[Link].858Z",
"description" : "Added with VMware Ovf Tool.",
"type" : "[Link]",
"files" : [ {
"name" : "[Link]",
"size" : 9985,
"hrefs" : [ "[Link]" ]
}, {
"name" : "[Link]",
"size" : 833536,
"hrefs" : [ "[Link]" ]
} ],
} "properties" : {
}
}

Responses
VCSP clients retrieve catalog files, including the descriptor and the endpoint index, with GET requests. The
endpoint must return one of the following responses:

n HTTP status 200 (OK) followed by the file content

n HTTP status 503 (Service unavailable) followed by a document that provides additional information.
This document has media type application/json, and provides values for the following keys:

status Status of the requested file.

progress File generation progress, expressed as an integer in the range 0 to 100.

message An error message describing any errors that prevented the file from being
generated.

The client continues to make GET requests until it receives either a 200 response or a 503 response with a
nonempty message.

For example, an in-progress operation could return the following response.

{
"status" : "",
"progress" : 10
}

240 VMware, Inc.

Chapter 7 Managing an Organization

An operation that has encountered an error could return the following response.

{
"status" : "failed",
"message" : "File Generation failed"
}

Authentication
An endpoint can require authentication. VCSP clients always present the user name vcsp when logging in.
The endpoint can specify any password for this user, but must accept the user name vcsp. The user name
and password are encoded as specified for Basic HTTP authentication.

Version Numbers
Version numbers appear in the endpoint descriptor and endpoint index as version values, which are integer
values that increment monotonically. It is the responsibility of the endpoint to increment the appropriate
version value whenever any of the following changes occur.

Changes to a catalog n A file in the item is added, removed, or changed.

item
n The name or description of the item is changed.

Changes to a catalog n An item is added to or removed from the catalog.

n The version value of any contained catalog item changes.

n The name or description of the catalog is changed.

User and Group Administration

A newly created organization has no users or groups in it. An administrator must create or import them.

An organization can contain an arbitrary number of users and groups. Users can be created locally or
managed by an external identity provider. Groups must be managed by an external identity provider.
Permissions within an organization are controlled through the assignment of rights and roles to users and
groups.

Local Users, Imported Users, and Groups

Local user accounts are stored in the vCloud Director database and managed by the organization
administrator. Local users cannot be made members of groups.

Imported users and groups must be managed at the source identity provider. If an imported user changes
his password, contact information, or other account properties, those changes are not effective in
vCloud Director until the user is imported again. The semantics of an import operation depend on the type
of the identity provider in use. See “About Federation and Single Sign-On,” on page 251.

Modifying User or Group Metadata

An organization administrator can modify metadata such as name and description for a user or group object
by creating a modified version of the User or Group element that represents the object and updating the
object by making a PUT request to the object's rel="edit" link, supplying the modified element in the
request body.

VMware, Inc. 241

vCloud API Programming Guide for Service Providers

Create a Local User

An organization administrator can create user accounts that are local to the organization. Local user
accounts are stored in the vCloud Director database.

Every user exists within the context of an organization. An organization administrator can create a local user
in an organization by POSTing a User element to the organization’s add URL for users, as shown in
“Example: Create a Local User,” on page 242.

When you create a user, you must include the Role and Password elements in the request body. The role can
be a predefined role or one created by the system administrator. For more information about retrieving a list
of predefined roles, see “Retrieve an Administrative View of a Cloud,” on page 56. For more information
about creating new roles, see “Create a Role in Your Organization,” on page 263.

Prerequisites
This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

Procedure
1 Create a User element that defines the user account properties.
See the request portion of “Example: Create a Local User,” on page 242.

2 POST the User element to the organization's add URL for users.

The server creates a user account in the vCloud Director database and returns an updated User element to
the client.

Example: Create a Local User

This example adds the user to the organization created in “Example: Create an Organization,” on page 280.
The request includes an optional IsEnabled element that enables the user. If not present in the request,
IsEnabled defaults to false.

The response is a User element, most of which does not appear in the example. The response includes a link
that an administrator can use to edit user properties, and additional elements, such as IsDefaultCached and
StoredVmQuota, whose values are inherited from the organization.

n The Password element, which must not be empty when you create a local User, is never returned.

n The ProviderType, which defines the identity provider for this user, was not specified in the request,
and defaults to INTEGRATED. Local users are managed by the integrated identity provider. See “About
Identity Providers,” on page 251.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<User
xmlns="[Link]
name="ExampleUser" >
<FullName>Example User Full Name</FullName>
<EmailAddress>user@[Link]</EmailAddress>
<IsEnabled>true</IsEnabled>
<Role

242 VMware, Inc.

Chapter 7 Managing an Organization

href="[Link] />
<Password>Pa55w0rd</Password>
<GroupReferences />
</User>

Response:

201 Created
Content-Type: application/[Link]+xml
...
<User
xmlns="[Link]
name="ExampleUser"
id="urn:vcloud:user:85"
type="application/[Link]+xml"
href="[Link] ... >
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<FullName>Example User Full Name</FullName>
<EmailAddress>user@[Link]</EmailAddress>
<IsEnabled>true</IsEnabled>
<ProviderType>INTEGRATED</ProviderType>
<IsAlertEnabled>false</IsAlertEnabled>
<IsDefaultCached>false</IsDefaultCached>
<IsGroupRole>false</IsGroupRole>
<StoredVmQuota>0</StoredVmQuota>
<DeployedVmQuota>0</DeployedVmQuota>
<Role
type="application/[Link]+xml"
name="vApp Author"
href="[Link] />
<GroupReferences />
</User>

Import a User from an LDAP Service

If an organization defines an LDAP service to use, an organization or system administrator can import user
accounts from that service.

Importing a group from LDAP imports all the users in the group. See “Import a Group from an LDAP
Service,” on page 245. You can also import users individually.

Prerequisites
n This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

n Verify that your organization has defined an LDAP service to use.

Procedure
1 Create a User element that identifies the LDAP user account to import.

The name attribute of the User element must match the LDAP user name, as specified in the organization's
LDAP properties. You must include the Role element in the request body.

2 POST the User element to the organization's users URL.

VMware, Inc. 243

vCloud API Programming Guide for Service Providers

The server matches the value of the name attribute in the request body with the value of the LDAP attribute
that the organization specified in the value of the UserName element in the UserAttributes of its
OrgLdapSettings. LDAP attributes such as userPrincipalName or samAccountName are common choices here.
The server imports the user from the organization's LDAP service, and returns an updated User element to
the client.

Example: Import a User from an LDAP Database

This example imports a user to the organization created in “Example: Create an Organization,” on page 280.
The request includes an optional IsEnabled element, so the user is enabled as soon as the import is complete.

The response is a User element, most of which is not shown in the example. The response includes a link
that an administrator can use to edit user metadata, and additional elements, such as IsDefaultCached and
StoredVmQuota, inherited from organization defaults. It also includes a NameInSource element, which
contains the user's name as stored by the LDAP server, using the server's native encoding.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<User
xmlns="[Link]
name="user@[Link]"
type="application/[Link]+xml">
<IsEnabled>true</IsEnabled>
<IsExternal>true</IsExternal>
<Role
href="[Link] />
</User>

Response:

201 Created
Content-Type: application/[Link]+xml
...
<User
xmlns="[Link]
name="user@[Link]"
id="urn:vcloud:user:85"
type="application/[Link]+xml"
href="[Link]
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<FullName>Imported User Full Name</FullName>
<EmailAddress>user@[Link]</EmailAddress>
<IsEnabled>true</IsEnabled>
<ProviderType>INTEGRATED</ProviderType>
<NameInSource>\F4\D3\42\8E\6A\BC\D3</NameInSource>
<IsAlertEnabled>false</IsAlertEnabled>
<IsDefaultCached>false</IsDefaultCached>
<StoredVmQuota>0</StoredVmQuota>
<DeployedVmQuota>0</DeployedVmQuota>
<Role
type="application/[Link]+xml"

244 VMware, Inc.

Chapter 7 Managing an Organization

name="vApp Author"
href="[Link] />
<GroupReferences />
</User>

Import a Group from an LDAP Service

If an organization defines an LDAP service to use, an organization or system administrator can import
groups from that service.

Importing a group from LDAP imports all the users in the group. You can also import users individually.
See “Import a User from an LDAP Service,” on page 243.

Prerequisites
n This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

n Verify that your organization has defined an LDAP service to use.

Procedure
1 Create a Group element that identifies the LDAP group to import.
The name attribute of the Group element must match the LDAP group name, as specified in the
organization's LDAP properties. You must include a Role element in the request body. The role
specified in this element is assigned to all group members during the import.

2 POST the Group element to the organization's groups URL.

The server matches the value of the name attribute in the request body with the value of the LDAP attribute
that the organization specified in the value of the GroupName element in the GroupAttributes of its
OrgLdapSettings. The LDAP cn attribute is a common choice here. The server imports that group and all of
its users from organization's LDAP service, and returns an updated Group element to the client.

Example: Import a Group from an LDAP Service

This example imports a group to the organization created in “Example: Create an Organization,” on
page 280. The response is a Group element, most of which does not appear in the example. The response
includes a link that an administrator can use to edit group metadata such as name and description, and a
UsersList element that includes a UserReference element for each user in the group. The response also
includes a NameInSource element, which contains the group's name as stored by the LDAP service, using its
native encoding.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Group
name="Engineering"
xmlns="[Link]
<Role
href="[Link]
</Group>

VMware, Inc. 245

vCloud API Programming Guide for Service Providers

Response:

201 Created
Content-Type: application/[Link]+xml
...
<Group
xmlns="[Link]
name="Engineering"
id="urn:vcloud:group:44"
type="application/[Link]+xml"
href="[Link] ...>
<Role
type="application/[Link]+xml"
name="vApp Author"
href="[Link] />
</Group>

Until the import is complete, the Group element contains only partial information. After the import is
complete, the element includes a list of users and other information.

<Group
xmlns="[Link]
name="Engineering"
id="urn:vcloud:group:44"
type="application/[Link]+xml"
href="[Link] ...>
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="remove"
href="[Link] />
<Description>Research and development</Description>
<NameInSource>\C5\AF\B9\D4\9E\B5\32\40\AD\C5\E3\8E\17\4C\0D\28</NameInSource>
<UsersList>
<UserReference
type="application/[Link]+xml"
name="User-1"
href="[Link] />
<UserReference
type="application/[Link]+xml"
name="User-3"
href="[Link] />
</UsersList>
<Role
type="application/[Link]+xml"
name="vApp Wrangler"
href="[Link] />
</Group>

246 VMware, Inc.

Chapter 7 Managing an Organization

Import a User from an OAuth Identity Provider

If your organization defines an OAuth identity provider in its OrgOAuthSettings, users managed by that
identity provider are created implicitly when they first log in to the organization. You can also import a user
from an OAuth identity provider explicitly if you need the user to exist in the organization before first login,
or to assign the user a specific role.

Unlike imports from an LDAP service, imports from an OAuth identity provider do not actually import
information from an external database. Instead, the operation creates a mapping between a user defined in
your organization and a user defined by your organization's OAuth provider. The vCloud Director database
stores these mappings, but does not store any user properties retrieved from the OAuth provider.

Prerequisites
n This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

n Verify that your organization has defined an OAuth identity provider in its OrgOAuthSettings.

Procedure
1 Create a User element that identifies a user defined by your organization's OAuth provider.
2 Include the following line in the User or Group element.

<ProviderType>OAUTH</ProviderType>

3 POST the element to the organization's users URL.

Example: Import a User from an OAuth Identity Provider

This example imports a user from an OAuth identity provider and assigns the user a specific role (the
predefined role vApp Author).

Note Any user managed by an OAuth identity provider is assigned the role Defer to Identity Provider
when created implicitly at first login (see “Predefined Roles and Their Rights,” on page 257). You can assign
this role when you import a user explicitly, though in many cases there is no need to do an explicit import
unless you want to assign the user another role or multiple roles.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<User
xmlns="[Link]
name="user@[Link]"
type="application/[Link]+xml">
<IsEnabled>true</IsEnabled>
<ProviderType>OAUTH</ProviderType>
<Role
type="application/[Link]+xml"
href="[Link] />
</User>

The response is a User element, most of which is not shown in the example. The response includes a link
that an administrator can use to edit user metadata, and additional elements, such as IsDefaultCached and
StoredVmQuota, inherited from organization defaults. It also includes a NameInSource element, which
contains the user's name in the encoding used by the identity provider.

VMware, Inc. 247

vCloud API Programming Guide for Service Providers

Response:

201 Created
Content-Type: application/[Link]+xml
...
<User
xmlns="[Link]
name="user@[Link]"
id="urn:vcloud:user:85"
type="application/[Link]+xml"
href="[Link]
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<FullName>Imported User Full Name</FullName>
<EmailAddress>user@[Link]</EmailAddress>
<IsEnabled>true</IsEnabled>
<ProviderType>OAUTH</ProviderType>
<NameInSource>\F4\D3\42\8E\6A\BC\D3</NameInSource>
<IsAlertEnabled>false</IsAlertEnabled>
<IsDefaultCached>false</IsDefaultCached>
<StoredVmQuota>0</StoredVmQuota>
<DeployedVmQuota>0</DeployedVmQuota>
<Role
type="application/[Link]+xml"
name="vApp Author"
href="[Link] />
<GroupReferences />
</User>

Import a User or Group from a SAML Identity Provider

If your organization defines a SAML identity provider in its OrgFederationSettings, you must import users
individually or as members of groups from the identity provider before they can log in to the organization.

Unlike imports from an LDAP service, imports from a SAML identity provider do not import information
from an external database. Instead, the operation creates a mapping between a user or group name in your
organization's database and a user or group name that your organization's SAML provider defines. The
vCloud Director database stores these mappings, but does not store data retrieved from the SAML provider.

When you import a user from a SAML identity provider, you must include the domain name, such as
user@[Link]. When you import a group from a SAML identity provider, you must use its fully
distinguished name.

When a user login presents a SAML token to the organization, user and group names in the token are
evaluated using the mappings established by the import operation. This evaluation process includes the
following steps:

n If the SAML token includes an attribute named UserName, try to match the value of that attribute to the
value of the name attribute of the User.

n If the SAML token does not include an attribute named UserName, try to match the value of the NameId
element to the value of the name attribute of the User.

n If the SAML token includes an attribute named Groups, assume that the value of that attribute is a list of
group names, and try to match each value in the list to the value of the name attribute of a Group in the
organization.

248 VMware, Inc.

Chapter 7 Managing an Organization

n If the SAML token does not include an attribute named Groups, assume that the user is not a member of
any group.

Prerequisites
n This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

n Verify that your organization has defined a SAML identity provider in its OrgFederationSettings.

Procedure
1 Create a User or Group element that identifies a user or group that your organization's SAML provider
defines.

2 Include the following line in the User or Group element.

<ProviderType>SAML</ProviderType>

3 POST the element to the organization's users or groups URL.

Example: Import a User from a SAML Identity Provider

This example imports a user from the SAML identity provider that the the organization defines. This
example is identical to the one shown in “Example: Import a User from an LDAP Database,” on page 244,
but includes a ProviderType element that specifies the source as the organization's SAML identity provider.
This example also omits the IsExternal element, which is required when importing from LDAP but is
ignored when importing from SAML.

The response is a User element, most of which is not shown in the example. The response includes a link
that an administrator can use to edit user metadata, and additional elements, such as IsDefaultCached and
StoredVmQuota, inherited from organization defaults. It also includes a NameInSource element, which
contains the user's name in the encoding that the identity provider uses.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<User
xmlns="[Link]
name="user@[Link]"
type="application/[Link]+xml">
<IsEnabled>true</IsEnabled>
<ProviderType>SAML</ProviderType>
<Role
type="application/[Link]+xml"
href="[Link] />
</User>

Response:

201 Created
Content-Type: application/[Link]+xml
...
<User
xmlns="[Link]
name="user@[Link]"
id="urn:vcloud:user:85"
type="application/[Link]+xml"

VMware, Inc. 249

vCloud API Programming Guide for Service Providers

href="[Link]
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<FullName>Imported User Full Name</FullName>
<EmailAddress>user@[Link]</EmailAddress>
<IsEnabled>true</IsEnabled>
<ProviderType>SAML</ProviderType>
<NameInSource>\F4\D3\42\8E\6A\BC\D3</NameInSource>
<IsAlertEnabled>false</IsAlertEnabled>
<IsDefaultCached>false</IsDefaultCached>
<StoredVmQuota>0</StoredVmQuota>
<DeployedVmQuota>0</DeployedVmQuota>
<Role
type="application/[Link]+xml"
name="vApp Author"
href="[Link] />
<GroupReferences />
</User>

Take Control of a User's Objects

An administrator can take control of a user's vApps, media, and catalogs.

When an administrator retrieves a User element, it contains a link that the administrator can use to take
ownership of that user's vApps, media, and catalogs. This action is typically required when a user leaves the
organization and an administrator needs to transfer ownership of that user's objects to other users.

Prerequisites
This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

Procedure
1 Retrieve the XML representation of the user.

Use a request like this one:

GET [Link]

2 Examine the response to find the link where rel="takeOwnership".

<User
...
href="[Link] ... >
...
<Link
rel="takeOwnership"
href="[Link]
...
</User>

3 Make a POST request to the URL in the href value of that link.

POST [Link]

The response is empty (204 No Content).

250 VMware, Inc.

Chapter 7 Managing an Organization

All vApps, media, and catalogs that belonged to the user now belong to the administrator who made the
request.

About Federation and Single Sign-On

An identity provider is a service that manages user and group identities. vCloud Director organizations that
use the same identity provider are said to be federated.

An organization can define an identity provider that it shares with other applications or enterprises. Users
authenticate to the identity provider to obtain a token that they can then use to log in to the organization.
Such a strategy can enable an enterprise to provide access to multiple, unrelated services, including
vCloud Director, with a single set of credentials, an arrangement often referred to as single sign-on.

About Identity Providers

vCloud Director supports the following kinds of identity providers:

OAuth An organization can define an external identity provider that supports

OAuth authentication, as defined in RFC 6749
([Link] All organizations that participate in an
OAuth-based federated identity scheme must include an OrgOAuthSettings
element whose public key, IssuerId and OAuthKeyConfigurations were
retrieved from the same identity provider.

SAML An organization can define an external identity provider that supports the
Security Assertion Markup Language (SAML) 2.0 standard. All
organizations participating in a SAML-based federated identity scheme must
include an OrgFederationSettings element that contains SAML metadata
retrieved from the same identity provider.

Integrated The integrated identity provider is a vCloud Director service that

authenticates users who are created locally or imported from LDAP. All
organizations that participate in an LDAP-based federated identity scheme
must include an OrgLdapSettings element that specifies shared configuration
parameters.

The XML representation of a User can include an IdentityProvider element that specifies INTEGRATED, OAUTH,
or SAML. If the element is missing or empty, a value of INTEGRATED is assumed.

The XML representation of a Group can include a ProviderType element that specifies INTEGRATED or SAML. If
the element is missing or empty, a value of INTEGRATED is assumed.

VMware, Inc. 251

vCloud API Programming Guide for Service Providers

Configuring and Managing Federation with OAuth

An organization can define an external identity provider that supports OAuth 2.0 authentication, as defined
in RFC 6749. All organizations that participate in an OAuth-based federated identity scheme must include
an OrgOAuthSettings element whose IssuerId and OAuthKeyConfigurations were retrieved from the same
identity provider.

Note When an organization is created, it is provided with a self-signed certificate for use when
establishing trust with an identity provider. This certificate expires after one year. You can regenerate this
certificate by making a request of the following form.

POST [Link]

You can retrieve this certificate with a request of the following form, where name is the name of the
organization.

GET [Link]

You do not have to be authenticated to make this request.

Prerequisites
This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

Select an OAuth service that supports OAuth 2.0. To enable your organization to use this service, you must
obtain the service's public key and related information that the OrgOAuthSettings element of your
organization's Settings element requires.

Procedure
1 Retrieve your organization's OrgOAuthSettings.

Use a request like this one:

GET [Link]

2 Modify the retrieved OrgOAuthSettings element to add your identity provider's OAuth metadata.

This metadata includes the service's public key, issuer identifier, a URL to which you can make an
authentication request, and at least one key configuration. See “Example: Update Organization OAuth
Settings,” on page 252.

3 Update the OrgOAuthSettings with your modifications.

a Find the Link element in the settings element where rel="edit".

b Make a PUT request to the URL in that link's href attribute value, and supply the modified section
as the request body. See the request portion of “Example: Update Organization Federation
Settings,” on page 255.

Example: Update Organization OAuth Settings

This example updates the OrgOAuthSettings of an organization whose URL is
[Link] The update adds information retrieved from an identity
provider, and enables OAuth federation by setting Enabled to true.

Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>

252 VMware, Inc.

Chapter 7 Managing an Organization

<OrgOAuthSettings
<IssuerId>[Link]
<OAuthKeyConfigurations>
<OAuthKeyConfiguration>
<KeyId>f2842a04-a172-407d-bac3-20f4a175af3e</KeyId>
<Algorithm>RSA</Algorithm>
<Key>-----BEGIN PUBLIC KEY-----
MIIBIjANBgk...
...
-----END PUBLIC KEY-----
</Key>
</OAuthKeyConfiguration>
</OAuthKeyConfigurations>
<Enabled>true</Enabled>
</OrgOAuthSettings>

The response contains information extracted from the request, and includes Link elements that the server
creates.

Response:

200 OK
Content-Type: application/[Link]+xml
...
<OrgOAuthSettings
href="[Link]
type="application/[Link]+xml">
<Link
rel="up"
href="[Link]
type="application/[Link]+xml" />
<Link
rel="edit"
href="[Link]
type="application/[Link]+xml" />
<IssuerId>[Link]
<OAuthKeyConfigurations>
<OAuthKeyConfiguration>
...
</OAuthKeyConfiguration>
</OAuthKeyConfigurations>
<Enabled>true</Enabled>
</OrgOAuthSettings>

Configuring and Managing Federation with SAML

An organization can define an external identity provider that supports the Security Assertion Markup
Language (SAML) 2.0 standard. All organizations participating in a SAML-based federated identity scheme
must include an OrgFederationSettings element that contains SAML metadata retrieved from the same
identity provider.

When an organization is created, it is provided with a self-signed certificate for use when establishing trust
with an identity provider. This certificate expires after one year. You can regenerate this certificate by
making a request of the following form.

POST [Link]

VMware, Inc. 253

vCloud API Programming Guide for Service Providers

You can retrieve this certificate with a request of the following form, where name is the name of the
organization.

GET [Link]

You do not have to be authenticated to make this request.

You can also add your own certificate chain and private key by including a SamlSPKeyAndCertificate
element in your OrgFederationSettings update.

Prerequisites
This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

Download the appropriate SAML metadata in XML format from your identity provider. The SAML
metadata must provide mappings for the user attributes shown in this XML fragment.

<saml:Attribute
FriendlyName="Groups"
Name="[Link]
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
<saml:Attribute
FriendlyName="givenName"
Name="[Link]
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
<saml:Attribute
FriendlyName="surname"
Name="[Link]
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
<saml:Attribute
FriendlyName="Subject Type"
Name="[Link]
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
<saml:Attribute
FriendlyName="userPrincipalName"
Name="[Link]
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
<saml:Attribute
FriendlyName="email"
Name="[Link]
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>

Procedure
1 Retrieve the OrgFederationSettings.

Use a request like this one:

GET [Link]

2 Modify the retrieved OrgFederationSettings element to add your identity provider's SAML metadata
as the value of the SAMLMetadata element.

XML entities must be encoded, as shown in “Example: Update Organization Federation Settings,” on
page 255

254 VMware, Inc.

Chapter 7 Managing an Organization

3 Update the OrgFederationSettings with your modifications.

a Find the Link element in the settings element where rel="edit".

b Make a PUT request to the URL in that link's href attribute value, and supply the modified section
as the request body. See the request portion of “Example: Update Organization Federation
Settings,” on page 255.

Example: Update Organization Federation Settings

This example updates the OrgFederationSettings of an organization whose URL is
[Link] The update adds SAML metadata retrieved from an
identity provider, and enables federation by setting Enabled to true. Only a subset of the SAML metadata is
shown.

Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<OrgFederationSettings
type="application/[Link]+xml">
<SAMLMetadata>
&lt;EntitiesDescriptor
xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" .... &gt;
...
&lt;/EntitiesDescriptor&gt;</SAMLMetadata>
<Enabled>true</Enabled>
</OrgFederationSettings>

Note To update or remove OrgFederationSettings after a SAML identity provider is specified, you must
include an empty SAMLMetadata element in the update request. If you do not, the request fails and the
OrgFederationSettings are not changed.

The response contains information extracted from the request, and includes Link elements that the server
creates.

Response:

200 OK
Content-Type: application/[Link]+xml
...
<OrgFederationSettings ...
type="application/[Link]+xml">
<Link
rel="up"
href="[Link]
type="application/[Link]+xml"/>
<Link
rel="edit"
href="[Link]
type="application/[Link]+xml"/>
<Link
rel="federation:regenerateFederationCertificate"

href="[Link]
Certificate"/>

VMware, Inc. 255

vCloud API Programming Guide for Service Providers

<SAMLMetadata>&lt;EntitiesDescriptor
xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" .... &gt;
...
&lt;/EntitiesDescriptor&gt; </SAMLMetadata>
<Enabled>true</Enabled>
</OrgFederationSettings>

Configuring and Managing Federation with LDAP

An organization can define an LDAP configuration that it shares with other organizations. This shared
configuration can support federation using LDAP as a directory service, an authentication service, or both.

When several organizations use the same LDAP service as their source for imported users and groups, they
enable a simple model of federation in which users in all the participating organizations can be managed by
a single LDAP service. In this kind of configuration, user credentials are imported into the vCloud Director
database, and vCloud Director is responsible for authenticating users. If all of the organizations also
configure the AuthenticationMechanism contained by CustomOrgLdapSettings to specify a shared Kerberos or
SSPI service, authentication can be managed by an external Kerberos or SSPI provider. For more information
about Setting up Kerberos authentication for vCloud Director, see [Link]

Prerequisites
This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

Procedure
1 Retrieve the organization LDAP settings.

Use a request like this one:

GET [Link]

The response is an OrgLdapSettings element.

2 Modify the retrieved OrgLdapSettings element.

You can set the value of OrgLdapMode to SYSTEM to specify that this organization uses the system LDAP
configuration. When you do this, you can also specify a CustomUsersOu value so that only users in a
specific LDAP organizational unit can be imported into this organization. See “Example: Update
Organization LDAP Settings,” on page 256.
To configure an LDAP service for the exclusive use of this organization, set the value of OrgLdapMode to
CUSTOM and include a CustomOrgLdapSettings element in the modified OrgLdapSettings.

3 Update the OrgLdapSettings with your modifications.

Find the Link element in the settings element where rel="edit". Make a PUT request to the URL in that
link's href attribute value, and supply the modified section as the request body. See “Example: Update
Organization LDAP Settings,” on page 256.

Example: Update Organization LDAP Settings

This example updates the OrgLdapSettings of the organization created in “Example: Create an
Organization,” on page 280. The update sets the value of the CustomUsersOu element to specify that only
LDAP users whose OU attribute has a value of Finance are imported into this organization.

256 VMware, Inc.

Chapter 7 Managing an Organization

Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<OrgLdapSettings ... >
<OrgLdapMode>SYSTEM</OrgLdapMode>
<CustomUsersOu>OU=Finance</CustomUsersOu>
</OrgLdapSettings>

Working With Roles and Rights

A role associates a role name with a set of rights. A newly created organization includes a set of predefined
roles and rights inherited from the system. A system administrator can use the vCloud Director Web
Console or the vCloud API to create or update role objects in any organization in the system. Organization
administrators can use the vCloud API to create or update role objects in organizations they administer.

vCloud Director uses roles and their associated rights to determine whether a user or group is authorized to
perform an operation. Many of the procedures documented in the vCloud Director Administrator's Guide,
vCloud Director User's Guide, and vCloud API Programming Guide for Service Providers include a prerequisite
role. These prerequisites assume that the named role is the unmodified predefined role or a role that
includes an equivalent set of rights.

When you create or import a user or import a group, you must assign it a role.

Note You can create and modify rights associated with extension services, but not those associated with
vCloud Director. See “Create a Service-Specific Right,” on page 428

Roles and Rights in an Organization

In previous releases of vCloud Director, roles were global objects created by system administrators and
available to all organizations. Beginning with vCloud Director 8.20, role objects are created and managed at
the organization level. Each organization is created with a set of predefined roles and the rights contained
by those roles. A system administrator can use the vCloud API to grant additional rights to an organization
during creation or afterward. A system administrator can also remove rights from an organization. A system
administrator can edit a predefined role to add or remove rights.

Note When you upgrade vCloud Director from a release earlier than 8.20, all roles that exist in the system,
including roles created by system administrators, are treated as predefined roles. Copies of these roles,
along with the rights they contain, are propagated to all organizations in the system. Only a system
administrator can delete or modify a predefined role.

Predefined Roles and Their Rights

Each vCloud Director predefined role contains a default set of rights required to perform operations
included in common workflows. With the exception of the System Administrator role, each predefined role
exists in every organization in the system.

The System Administrator Role

The system administrator role exists only in the System organization. The System organization and system
administrator role include all rights. System administrator credentials are established during installation
and configuration. A system administrator can create additional system administrator accounts. All system
administrators are members of the System organization.

VMware, Inc. 257

vCloud API Programming Guide for Service Providers

You cannot modify the rights associated with the System Administrator role. A system administrator can
use the vCloud Director Web Console or the vCloud API to create or update other role objects in any
organization in the system.

Predefined Roles
Predefined roles and the rights they contain are available in all organizations.

Organization After creating an organization, a system administrator can assign the role of
Administrator organization administrator to any user in the organization. A user with the
predefined Organization Administrator role can use the vCloud Director
Web Console or the vCloud API to manage users and groups in their
organization and assign them roles, including the predefined Organization
Administrator role. An organization administrator can use the vCloud API to
create or update role objects that are local to the organization. Roles created
or modified by an organization administrator are not visible to other
organizations.

Catalog Author The rights associated with the predefined Catalog Author role allow a user to
create and publish catalogs.

vApp Author The rights associated with the predefined vApp Author role allow a user to
use catalogs and create vApps.

vApp User The rights associated with the predefined vApp User role allow a user to use
existing vApps.

Console Access Only The rights associated with the predefined Console Access Only role allow a
user to view virtual machine state and properties and to use the guest OS.

Defer to Identity Rights associated with the predefined Defer to Identity Provider role are
Provider determined based on information received from the user's OAuth or SAML
Identity Provider. To qualify for inclusion when a user or group is assigned
the Defer to Identity Provider role, a role or group name supplied by the
Identity Provider must be an exact, case-sensitive match for a role or group
name defined in your organization.

n If the user is defined by an OAuth Identity Provider, the user will be

assigned the roles named in the roles array of the user's OAuth token.

n If the user is defined by a SAML Identity Provider, the user will be

assigned the roles named in the SAML attribute whose name appears in
the RoleAttributeName element in the organization's
OrgFederationSettings.

If a user is assigned the Defer to Identity Provider role but no matching

role or group name is available in your organization, the user can log in to
the organization but has no rights. If an Identity Provider associates a user
with a system-level role such as System Administrator, the user can log in to
the organization but has no rights. You must manually assign a role to such
users.

With the exception of the Defer to Identity Provider role, each predefined role includes a set of default
rights. Only a system administrator can modify the rights in a predefined role. If a system administrator
modifies a predefined role, the modifications propagate to all instances of the role in the system.

258 VMware, Inc.

Chapter 7 Managing an Organization

Rights in Predefined Roles

Predefined roles and new roles created by the organization administrator are listed in the RoleReferences
element of AdminOrg response. To view the list of rights included in a role, make a request like this one,
where org-id is the UUID of the organization and role-id is the UUID of the role.

GET [Link]

You can also use the adminRole query and filter on the organization UUID.

GET [Link]
type=adminRole&format=records&filter=org==[Link]

The system classifies rights according to the object type to which they apply.

Table 7‑4. Rights Associated With Catalogs

Catalog vApp Console
Name Description Admin Author Author vApp User Access Only

Catalog: Add Permission to add a X X X

vApp from vApp to a catalog
My Cloud from My Cloud.

Catalog: Permission to change X

Change the owner of a
Owner catalog.

Catalog: Permission to create X X

Create/Delete and delete catalogs.
a Catalog

Catalog: Edit Permission to edit X X

Catalog catalog properties.
Properties

Catalog: Permission to X X
Allow publish catalogs for
External external
Publishing/Su consumption and to
bscriptions for subscribe to external
the Catalogs catalog feeds.

Catalog: Share Permission to share X X

a Catalog to catalogs to users and
Users/Groups groups in the same
within organization.
Current
Organization

Catalog: View Permission to view X X X

Private and both private and
Shared shared catalogs in
Catalogs the organization.
within
Current
Organization

Catalog: View Permission to view X

Shared catalogs shared from
Catalogs from other organizations.
Other
Organizations

VMware, Inc. 259

vCloud API Programming Guide for Service Providers

Table 7‑5. Rights Associated With Independent Disks

Catalog vApp Console
Name Description Admin Author Author vApp User Access Only

Disk: Create Permission to create X X X

independent disks.

Disk: Delete Permission to delete X X X

independent disks.

Disk: Edit Permission to edit X X X

Properties the properties of an
independent disk.

Disk: View Permission to view X X X X

Properties the properties of an
independent disk.

Disk: Change Permission to change X

Owner the owner of an
independent disk.

Table 7‑6. Rights Associated With vApp Templates and Media

Catalog vApp Console
Name Description Admin Author Author vApp User Access Only

Catalog Item: Permission to add a X X X X

Add to My vApp template or
Cloud media file to My
Cloud.

Catalog Item: Permission to copy X X X

Copy/Move a and move vApp
vApp templates and media
Template/Med files.
ia

Catalog Item: Permission to create X X

Create/Upload and upload vApp
a vApp templates and media
Template/Med files.
ia

Catalog Item: Permission to enable X X

Enable vApp a vApp template or
Template/Med media item to be
ia Download downloaded.

Catalog Item: Permission to edit X X

Edit vApp the properties of a
Template/Med vApp template or
ia Properties media file.

Catalog Item: Permission to view X X X X

View vApp vApp templates and
Templates/Me media files.
dia

Table 7‑7. Rights Associated With vApps

Catalog vApp Console
Name Description Admin Author Author vApp User Access Only

vApp: Change Permission to change X

Owner the owner of a vApp.

vApp: Copy a Permission to copy a X X X X

vApp vApp.

260 VMware, Inc.

Chapter 7 Managing an Organization

Table 7‑7. Rights Associated With vApps (Continued)

Catalog vApp Console
Name Description Admin Author Author vApp User Access Only

vApp: Permission to create X X X

Create/Reconfi and reconfigure
gure a vApp vApps.

vApp: Delete Permission to delete X X X X

a vApp a vApp.

vApp: Permission to X X X X
Download a download a vApp.
vApp

vApp: Edit Permission to edit a X X X X

vApp vApp's properties.
Properties

vApp: Edit Permission to edit X X X

VM CPU virtual machine
CPUs.

vApp: Edit Permission to edit X X X

VM Hard Disk virtual machine hard
disks.

vApp: Edit Permission to edit X X X

VM Memory virtual machine
memory.

vApp: Edit Permission to edit X X X X

VM Network virtual machine
network
configuration.

vApp: Edit Permission to edit X X X X

VM Properties virtual machine
properties.

vApp: Permission to edit X X X X X

Manage VM virtual machine
Password password settings.
Settings

vApp: Permission to start, X X X X

Start/Stop/Sus stop, suspend, and
pend/Reset a reset a vApp
vApp

vApp: Share a Permission to share X X X X

vApp vApps.

vApp: Permission to create, X X X X

Create/Remov revert, and delete
e/Revert a virtual machine
Snapshot snapshots.

vApp: Upload Permission to upload X X X X

a vApp a vApp.

vApp: Access Permission to use the X X X X X

to a VM virtual machine
Console console.

vApp: View Permission to view X X X

VM Metrics virtual machine
metrics.

VMware, Inc. 261

vCloud API Programming Guide for Service Providers

Table 7‑7. Rights Associated With vApps (Continued)

Catalog vApp Console
Name Description Admin Author Author vApp User Access Only

vApp: Insert Permission to insert a X X X X X

CD CD into any virtual
machine in the vApp

Allow Permission to apply X X X

metadata metadata in the
mapping VCENTER domain to
domain to a virtual machine
vCenter

Administrative Rights
These rights are granted to the system administrator throughout the system, and to an organization
administrator within the organization. These rights are not granted to any other predefined role. The system
administrator is granted additional rights not granted to organization administrators.

Table 7‑8. Additional Rights Granted to Organization Administrators

Name Description Admin

General: Administrator Control Permission to use all administrator privileges. X

General: Administrator View Permission to view vCloud Director as an administrator. X

General: Send Notification Permission to send vCloud Director user notifications. X

Gateway: Configure Services Permission to configure gateway services. X

Organization VDC Network: Permission to edit the properties of an organization virtual X

Edit Properties data center network.

Organization VDC Network: Permission to view the properties of an organization virtual X

View Properties data center network.

Organization VDC: Set Default Permission to set the default storage policy for an X
Storage Policy organization virtual data center.

Organization VDC: View Permission to view organization virtual data centers. X

Organization VDCs

Organization: Allow Access to Permission to access all organization virtual data centers X
All Organization VDCs through vCloud Air

Organization: Edit Federation Permission to edit an organization's federation settings. X

Settings

Organization: Edit Leases Policy Permission to edit an organization's leases policy. X

Organization: Edit Organization Permission to edit an organization's network properties X

Network Properties

Organization: Edit Organization Permission to edit organization properties. X

Properties

Organization: Edit Password Permission to edit an organization's password policy. X

Policy

Organization: Edit Quotas Policy Permission to edit an organization's quotas policy. X

Organization: Edit SMTP Permission to edit an organization's SMTP settings. X

Settings

Organization: Edit Organization Permission to edit an organization's associations. X

Associations

262 VMware, Inc.

Chapter 7 Managing an Organization

Table 7‑8. Additional Rights Granted to Organization Administrators (Continued)

Name Description Admin

Organization: Implicitly Import Permission to import vCloud Director users and groups while X
User/Group from IdP While editing VDC Access Control Lists in vCloud Air
Editing VDC ACL

Organization: Edit Access Permission to edit the vCloud Air Access Control Lists of X
Control List of Organization organization virtual data centers
VDCs

Organization: View Access Permission to view the vCloud Air Access Control Lists of X
Control List of Organization organization virtual data centers
VDCs

Organization: View Organization Permission to view organization networks. X

Networks

Organization: View Permission to view organizations. X

Organizations

Organization: Edit Operation Permission to edit an organization's X (system

Limits OrgOperationLimitsSettings. administrator only)

Create a Role in Your Organization

A system administrator can use the vCloud Director Web Console or the vCloud API to create or update
role objects in any organization in the system. Organization administrators can use the vCloud API to create
or update role objects in the organizations they administer.

Role and right objects are local to an organization. An organization is initially granted a set of rights derived
from the rights contained in the predefined roles, and includes a copy of each predefined role. A system
administrator can grant additional rights to an organization. See “Edit Organization Rights,” on page 283.

Organization administrators can create or update roles in organizations they administer by aggregating a set
of rights in a Role element and POSTing it to the organization's add URL for roles. Roles created in this way
are local to a specific organization.

Important An organization administrator cannot modify a predefined role or create a new role that has
the same name as a predefined role.

Prerequisites
This operation requires the rights included in the predefined Organization Administrator role or an
equivalent set of rights.

Procedure
1 Retrieve the set of rights available to your organization.
To get the RightReference objects that populate the Role, use a request like this one:

GET [Link]

The OrgRights element returned by this request includes a RightReference element for each right
granted to the organization by the system administrator.

2 Create a Role element that defines the role with a name and a set of rights.

See the request portion of “Example: Create a Role,” on page 264.

3 POST the Role element to the organization's add URL for roles.

The system creates the role in your organization and returns its representation, a Role element, in the
response.

VMware, Inc. 263

vCloud API Programming Guide for Service Providers

Example: Create a Role

This example adds a role named vAppWrangler to the organization with id 21. The new role is created in this
organization, but not in any other organizations in the system. You must be a system administrator or an
administrator of this organization to make this request. The rights associated with this new role are less
comprehensive than those associated with the built-in vApp Author role, but still include rights to perform
many common vApp operations. This example uses href attributes that contain actual UUID values for
specific rights, since these are invariant across vCloud Director installations and releases.

Request:

POST [Link]
Accept: application/*;version=27.0
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Role
name="vAppWrangler"
xmlns="[Link]
<Description>Create and manage vApps</Description>
<RightReferences>
<RightReference
type="application/[Link]+xml"
name="vApp: Copy"
href="[Link]
fc716d20bf4b" />
<RightReference
type="application/[Link]+xml"
name="vApp: Create / Reconfigure"
href="[Link]
ce0453160b53" />
<RightReference
type="application/[Link]+xml"
name="vApp: Delete"
href="[Link]
a9cfe8d49014" />
<RightReference
type="application/[Link]+xml"
name="vApp: Edit Properties"
href="[Link]
de3d525d49f3" />
<RightReference
type="application/[Link]+xml"
name="vApp: Edit VM CPU"
href="[Link]
f56612a06722" />
<RightReference
type="application/[Link]+xml"
name="vApp: Edit VM Hard Disk"
href="[Link]
b782-5d31a1d77d85" />
<RightReference
type="application/[Link]+xml"
name="vApp: Edit VM Memory"
href="[Link]

264 VMware, Inc.

Chapter 7 Managing an Organization

fc42-33a8-844f-8ab5a91f8a6c" />
<RightReference
type="application/[Link]+xml"
name="vApp: Edit VM Network"
href="[Link]
f953-3976-9f2b-8b355b25881d" />
<RightReference
type="application/[Link]+xml"
name="vApp: Edit VM Properties"

href="[Link] />
<RightReference
type="application/[Link]+xml"
name="vApp: Power Operations"
href="[Link]
ac39-4f9d8e3e1cd2" />
</RightReferences>
</Role>

The response is a Role element, most of which does not appear in this excerpt. The response includes links
that an administrator can use to edit or remove the role.
Response:

201 Created
Content-Type: application/[Link]+xml
...
<Role
name="vAppWrangler"
...
href="[Link] ...>
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link]
<Link
rel="remove"
href="[Link]
<Description>Create and manage vApps</Description>
<RightReferences>
...
</RightReferences>
</Role>

VMware, Inc. 265

vCloud API Programming Guide for Service Providers

266 VMware, Inc.

Managing and Monitoring a Cloud 8
The VMware vCloud API includes extensions that support operations on the vSphere platform, which
provides resources to vCloud Director. A system administrator can use these extensions to retrieve or
update the configuration of a cloud, add or remove vSphere resources, and import vApps and media from
vCenter.

Only the system administrator can perform vSphere platform operations. Before you attempt these
operations, log in to the System organization with the user name and password of the system administrator
account that was created when vCloud Director was installed. See “Administrator Credentials and
Privileges,” on page 185.

This chapter includes the following topics:

n “Retrieve or Update System Settings,” on page 268

n “Attach a vCenter Server,” on page 269

n “Finding Available vCenter Resources,” on page 270

n “Create an Organization,” on page 279

n “Create a Provider VDC,” on page 286

n “Create an External Network,” on page 297

n “Create a Network Pool,” on page 300

n “Add a VDC to an Organization,” on page 304

n “Creating and Managing VM-Host Affinity Rules,” on page 323

n “Creating and Managing VDC Templates,” on page 329

n “Import a Virtual Machine from vCenter,” on page 343

n “Relocate a Virtual Machine to a Different Datastore,” on page 346

n “Configure the vCloud Director AMQP Service,” on page 347

n “System Truststore and Keytab Maintenance,” on page 351

n “Retrieve the vSphere URL of an Object,” on page 354

VMware, Inc. 267

vCloud API Programming Guide for Service Providers

Retrieve or Update System Settings

System settings establish systemwide behaviors and default values.

The SystemSettings element includes all system settings for this vCloud Director server group. The element
also includes links that allow you to retrieve these subsidiary elements, which define specific categories of
settings.

GeneralSettings Specify service URLs, timeouts, truststore details, and similar global
properties of the server group.

NotificationsSettings Control the vCloud Director AMQP notifications service.

LdapSettings Specify details of the system LDAP directory service.

AmqpSettings Specify credentials and connection information for the AMQP broker that
handles notifications and blocking task messages.

EmailSettings Define configuration and connection parameters for the system default email
service, and specifies properties of email alerts that the system sends.

License System license serial number and related settings.

BrandingSettings Customize the branding of the vCloud Director Web Console and some of
the links that appear on the vCloud Director Home login screen.

BlockingTaskSettings Control the behavior of blocking tasks and enable blocking for specific
operations.

PasswordPolicySettings Specify default policies to be followed when a user in any organization

enters an incorrect password. Organization administrators can override this
default for their organizations.

LookupServiceSettings Specify the vSphere Lookup Service URL so system administrators can
authenticate using vSphere Single Sign-On (SSO).

CatalogSettings Specify the schedule for background synchronization of catalogs that have an
external subscription. These settings apply to all organizations in the system.

You can retrieve the entire SystemSettings element to view all of these settings. To update an individual
subsection, retrieve it with a GET request, modify it, and update it with a PUT request.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the SystemSettings element.

Use a request like this one.

GET [Link]

2 Examine the response to locate the Link elements that you can use to retrieve an individual subsection.

These links have a rel attribute value of down.

3 Use the link to retrieve the subsection.

Make a GET request to the href value of the link.

4 (Optional) Modify the retrieved subsection.

Subsections that you can modify include a link where rel="edit".

268 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

5 (Optional) To update the subsection, PUT the modified subsection to the href of the link described in
Step 4.

Attach a vCenter Server

A system administrator can register a vCenter server and a companion vShield Manager server for use in a
cloud by making a POST request to the cloud’s action/registervimserver URL and supplying a
RegisterVimServerParams request body.

Prerequisites
n This operation is restricted to system administrators.

n Verify that you know the name, IP address, and administrator password of the vCenter server and
vShield Manager server.

Procedure
1 Retrieve the XML representation of the vSphere platform extensions.

Use a request like this one.

GET [Link]

2 Examine the response to locate the Link element that contains the URL for adding vCenter servers to
the cloud.

This element has a rel attribute value of add and a type attribute value of
application/[Link]+xml, as shown here:

<Link
type="application/[Link]+xml"
rel="add"
href="[Link]

3 Create a RegisterVimServerParams element that includes the information required to register the
vCenter server and vShield manager.

4 POST the RegisterVimServerParams element you created in Step 3 to the URL described in Step 2.

See the request portion of “Example: Register a vCenter Server and vShield Manager,” on page 269.

Example: Register a vCenter Server and vShield Manager

You must supply the user name and password of the vCenter administrator in the request. The response
includes vCloud URLs for the newly registered vCenter and vShield Manager servers, and omits the
password.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:RegisterVimServerParams
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
<vmext:VimServer
name="VC-22">
<vmext:Username>Administrator</vmext:Username>
<vmext:Password>Pa55w0rd</vmext:Password>
<vmext:Url>[Link]

VMware, Inc. 269

vCloud API Programming Guide for Service Providers

<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>[Link]
</vmext:ShieldManager>
</vmext:RegisterVimServerParams>

Response:

200 OK
Content-Type: application/[Link]+xml
...
<vmext:RegisterVimServerParams
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
<vmext:VimServer
type="application/[Link]+xml"
name="VC-22"
href="[Link]
...
</vmext:VimServer>
<vmext:ShieldManager
...
</vmext:ShieldManager>
</vmext:RegisterVimServerParams>

Finding Available vCenter Resources

Many of the operations required to import virtual machines or create Provider VDCs, external networks,
and network pools require you to identify vCenter resources and obtain references to them. You use these
references to make the vCenter resources available in the cloud.

Every vCenter server registered to your cloud is represented as a VimServerReference element in the cloud's
vimServerReferences list. You can retrieve one of these references to get a detailed representation of the
server object, including links to the server's resource pools, networks, hosts, and virtual machines.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the list of vCenter servers registered to this cloud.

Use a request like this one.

GET [Link]

2 Retrieve the representation of a vCenter server.

The response to the request you made in Step 1 contains a list of VimServerReference elements. You can
make a GET request to any of these references to retrieve the XML representation of a vCenter server
registered to this cloud.

The VimServer element returned in response to the request you made in Step 2 includes several Link
elements where rel="down". These links contain URLs that you can use to retrieve lists of references to
vCenter resources on this server.

270 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

Table 8‑1. vCenter Resource Lists

List URL List Contents

[Link] References to virtual machines in this vCenter server's

n/vimServer/id/vmsList inventory

[Link] References to hosts in this vCenter server's inventory

n/vimServer/id/hostReferences

[Link] ResourcePool objects

n/vimServer/id/resourcePoolList

[Link] VimObjectRef elements of type DV_PORTGROUP and

n/vimServer/id/networks NETWORK

[Link] VMWStorageProfile objects.

n/vimServer/id/storageProfiles

Example: Resources on a vCenter Server

Request:

GET [Link]

Response:

200 OK
...
<vmext:VimServer
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
name="VC22"
id="urn:vcloud:vimserver:9"
type="application/[Link]+xml"
href="[Link] ...>
...
<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
...
<vmext:Username>administrator</vmext:Username>
<vmext:Url>[Link]
<vmext:IsEnabled>true</vmext:IsEnabled>

VMware, Inc. 271

vCloud API Programming Guide for Service Providers

<vmext:IsConnected>true</vmext:IsConnected>
<vmext:ShieldManagerHost>[Link]</vmext:ShieldManagerHost>
<vmext:ShieldManagerUserName>admin</vmext:ShieldManagerUserName>
<vmext:ShieldManagerUserName>admin</vmext:ShieldManagerUserName>
<vmext:Uuid>44D5DAAA-7F3E-456D-B1CB-8288D7308AD6</vmext:Uuid>
<vmext:VcProxy>cell1</vmext:VcProxy>
<vmext:VcVersion>5.0.0</vmext:VcVersion>
<vmext:UseVsphereService>false</vmext:UseVsphereService>
</vmext:VimServer>

Retrieve a List of Resource Pools from a vCenter Server

You can retrieve the list of resource pools available on a vCenter server registered to a cloud. To retrieve the
list, you make a GET request to the server's resourcePoolList link.

The ResourcePoolList of a VimServer element contains an entry for every available resource pool on the
server. Resource pools that a provider VDC is already using are not listed, because they are considered
unavailable. See “Finding Available vCenter Resources,” on page 270.

Prerequisites
n This operation is restricted to system administrators.

n Retrieve the XML representation of a vCenter server registered to your cloud. See “Finding Available
vCenter Resources,” on page 270.

Procedure
1 Examine the VimServer element to locate its resourcePoolList link.

The link has the following form:

<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />

2 GET the URL in the value of this link's href attribute to retrieve the list of resource pools.

See “Example: Retrieve a List of Resource Pools from a vCenter Server,” on page 272. If the list is empty,
all resource pools on the server are already in use.

Example: Retrieve a List of Resource Pools from a vCenter Server

Request:

GET [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<vmext:ResourcePoolList
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
type="application/[Link]+xml" ... >
<vcloud:Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<vmext:ResourcePool

272 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

name="cluster2">
<vmext:MoRef>resgroup-195</vmext:MoRef>
<vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType>
<vmext:DataStoreRefs>
<vmext:VimObjectRef>
<vmext:VimServerRef
type="application/[Link]+xml"
name="vc9-ds1"
href="[Link] />
<vmext:MoRef>datastore-172</vmext:MoRef>
<vmext:VimObjectType>DATASTORE</vmext:VimObjectType>
</vmext:VimObjectRef>
<vmext:VimObjectRef>
<vmext:VimServerRef
type="application/[Link]+xml"
name="vc9-ds2"
href="[Link] />
<vmext:MoRef>datastore-173</vmext:MoRef>
<vmext:VimObjectType>DATASTORE</vmext:VimObjectType>
</vmext:VimObjectRef>
</vmext:DataStoreRefs>
</vmext:ResourcePool>
<vmext:ResourcePool
name="cluster3">
<vmext:MoRef>resgroup-230</vmext:MoRef>
<vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType>
<vmext:DataStoreRefs>
<vmext:VimObjectRef>
<vmext:VimServerRef
type="application/[Link]+xml"
name="vc9-ds10"
href="[Link] />
<vmext:MoRef>datastore-174</vmext:MoRef>
<vmext:VimObjectType>DATASTORE</vmext:VimObjectType>
</vmext:VimObjectRef>
</vmext:DataStoreRefs>
</vmext:ResourcePool>
...
</vmext:ResourcePoolList>

Retrieve a List of Available Portgroups and Switches from a vCenter Server

You can retrieve the list of available portgroups and switches that are available on a vCenter server
registered to a cloud. To retrieve the list, make a GET request to the server's networks link.

Retrieving the networks link from a VimServer element returns a VimObjectRefList element that contains
references to available DV_SWITCH, DV_PORTGOUP, and NETWORK objects on the server. Objects that have already
been consumed in the creation of an external network are not listed. See “Finding Available vCenter
Resources,” on page 270.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of a vCenter server registered to your cloud.

VMware, Inc. 273

vCloud API Programming Guide for Service Providers

2 Examine the response, a VimServer element, to locate the networks link.

This link has the following form:

<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />

3 GET the URL in the value of this link's href attribute to retrieve the list of network resources.

See “Example: Retrieve a List of Available Portgroups and Switches from a vCenter Server,” on
page 274. If the list is empty, all network resources on the server are already in use.

Example: Retrieve a List of Available Portgroups and Switches from a vCenter

Server
Request:

GET [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<vmext:VimObjectRefList
xmlns:vmext="[Link]
xmlns:vcloud="[Link] ... >
<vcloud:Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<vmext:VimObjectRefs>
<vmext:VimObjectRef>
<vmext:VimServerRef
type="application/[Link]+xml"
name="vc9"
href="[Link] />
<vmext:MoRef>dvportgroup-32</vmext:MoRef>
<vmext:VimObjectType>DV_PORTGROUP</vmext:VimObjectType>
</vmext:VimObjectRef>
<vmext:VimObjectRef>
<vmext:VimServerRef
type="application/[Link]+xml"
name="vc9"
href="[Link] />
<vmext:MoRef>dvportgroup-175</vmext:MoRef>
<vmext:VimObjectType>DV_PORTGROUP</vmext:VimObjectType>
</vmext:VimObjectRef>
</vmext:VimObjectRefs>
</vmext:VimObjectRefList>

274 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

Retrieve a List of External Networks and Network Pools

You can retrieve a list of external networks and network pools that have been created on a vCenter server
registered to a cloud.

A reference to an external network is required when you create an Edge Gateway. A reference to a network
pool is usually required when you create an organization VDC. These resources do not exist in a new
vCloud Director installation. A system administrator must create them, as described in “Create an External
Network,” on page 297 and “Create a Network Pool,” on page 300.

Note When you create a Provider VDC, a VxlanPoolType network pool is created automatically on the
vCenter server that backs the Provider VDC. See “Create a Network Pool,” on page 300.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of your cloud.

Use a request like this one:

GET [Link]

2 Examine the response, a VMWExtension element, to locate the links to lists of external networks and
network pools.

These links have the following form:

<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />

3 Make a GET request to the link that represents the object type of interest.

See “Example: Retrieve a List of External Networks,” on page 275.

Example: Retrieve a List of External Networks

Request:

GET [Link]

Each reference to an external network includes its type, name, and href attributes, as shown in this example.

Response:

<vmext:VMWExternalNetworkReferences ... >

...
<vmext:ExternalNetworkReference
type="application/[Link]+xml"
name="VC0"
href="[Link] />
<vmext:ExternalNetworkReference
type="application/[Link]+xml"

VMware, Inc. 275

vCloud API Programming Guide for Service Providers

name="VC1"
href="[Link] />
...
</vmext:VMWExternalNetworkReferences>

The corresponding element for network pools, VMWNetworkPoolReferences, is similar. In most cases, you can
supply just the href attribute value when you specify an external network or network pool in an
organization network creation request. You can retrieve additional information about the external network
or network pool by making a GET request to its href attribute value.

Retrieve a List of Virtual Machines from a vCenter Server

You can retrieve the list of virtual machines in the inventory of a vCenter server that is registered to a cloud.
To retrieve the list, make a GET request to the server's vmsList link.

When you import a virtual machine from vCenter, your request must supply a reference to the vCenter
server and a VIM object reference to the virtual machine. See “Finding Available vCenter Resources,” on
page 270.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of a vCenter server registered to your cloud.

2 Examine the response, a VimServer element, to locate the vmsList link.

This link has the following form:

<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />

3 GET the URL in the value of this link's href attribute to retrieve the list of virtual machines.

See the request portion of “Example: Retrieve a List of Virtual Machines from a vCenter Server,” on
page 276. If the list is empty, there are no virtual machines in the server's inventory.

Example: Retrieve a List of Virtual Machines from a vCenter Server

Request:

GET [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<vmext:VmObjectRefsList
xmlns:vmext="[Link]
page="1"
numberOfPages="1"
xmlns:xsi="[Link] ... >
<vmext:VmObjectRef
name="RH5u3_32bit">
<vmext:VimServerRef
type="application/[Link]+xml"
name="vc2-v41u1"

276 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

href="[Link] />
<vmext:MoRef>vm-41</vmext:MoRef>
<vmext:VimObjectType>VIRTUAL_MACHINE</vmext:VimObjectType>
</vmext:VmObjectRef>
<vmext:VmObjectRef
name="W2K3 64 R2">
<vmext:VimServerRef
type="application/[Link]+xml"
name="vc2-v41u1"
href="[Link] />
<vmext:MoRef>vm-43</vmext:MoRef>
<vmext:VimObjectType>VIRTUAL_MACHINE</vmext:VimObjectType>
</vmext:VmObjectRef>
<vmext:VmObjectRef
name="Ubuntu91_32_vt4">
<vmext:VimServerRef
type="application/[Link]+xml"
name="vc2-v41u1"
href="[Link] />
<vmext:MoRef>vm-44</vmext:MoRef>
<vmext:VimObjectType>VIRTUAL_MACHINE</vmext:VimObjectType>
</vmext:VmObjectRef>
</vmext:VmObjectRefsList>

Retrieve a List of Storage Profiles from a vCenter Server

You can retrieve the list of storage profiles that have been defined on a vCenter server registered to a cloud.
To retrieve the list, you make a GET request to the server's storageProfiles link.

Storage profiles are named configurations of vCenter storage. When you create a Provider VDC, you must
specify the name of at least one storage profile to provide storage capacity for that Provider VDC.

The VMWStorageProfiles of a VimServer element contains an entry for every storage profile that has been
defined on the server. See “Finding Available vCenter Resources,” on page 270.

Note Storage profiles are represented as Storage Policies in the vCloud Director Web console.

Prerequisites
n This operation is restricted to system administrators.

n Retrieve the XML representation of a vCenter server registered to your cloud. See “Finding Available
vCenter Resources,” on page 270.

VMware, Inc. 277

vCloud API Programming Guide for Service Providers

Procedure
1 (Optional) Refresh the cached list of storage profiles.

vCloud Director maintains a cache of the storage profiles that have been created on each of its
registered vCenter servers. The cache is refreshed on a regular schedule, and is likely to contain an up-
to-date list. If a vCenter administrator has recently created a new storage profile, you can force it to be
added to the cache by following these steps.

a Examine the VimServer element to locate its action/refreshStorageProfiles link.

The link has the following form:

<vcloud:Link
rel="refreshStorageProfiles"

href="[Link]
files" />

b Refresh the cached list of storage profiles from the vCenter server.

Use a request like this one.

POST
[Link]

The response is a Task. When the task completes, the cached list of storage profiles on the vCenter
server has been updated.

2 Examine the VimServer element to locate its storageProfiles link.

The link has the following form:

<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />

3 GET the URL in the value of this link's href attribute to retrieve the list of storage profiles.

See “Example: Retrieve a List of Storage Profiles from a vCenter Server,” on page 278.

Example: Retrieve a List of Storage Profiles from a vCenter Server

Request:

GET [Link]

This response shows that the specified vCenter server contains three storage profiles, named Gold, Silver,
and Bronze. Storage profile details, including datastore identifiers and capacities, are included in the
response, but only the value of the name attribute of a VMWStorageProfile is needed when adding that
storage profile to a Provider VDC.
Response:

200 OK
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:VMWStorageProfiles
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
...>
...

278 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

<vmext:VMWStorageProfile
name="Gold">
<vmext:MoRef>storageProfile-CFAA6D92-36FC-4C16-9B30-FAC79B902371</vmext:MoRef>
<vmext:VimObjectType>STORAGE_PROFILE</vmext:VimObjectType>
<vmext:FreeStorageMb>169203.0</vmext:FreeStorageMb>
<vmext:TotalStorageMb>325120.0</vmext:TotalStorageMb>
<vmext:DataStoreRefs>
<vmext:VimObjectRef>
<vmext:VimServerRef
type="application/[Link]+xml"
name=""
href="[Link] />
<vmext:MoRef>datastore-44</vmext:MoRef>
<vmext:VimObjectType>DATASTORE</vmext:VimObjectType>
</vmext:VimObjectRef>
<vmext:VimObjectRef>
<vmext:VimServerRef
type="application/[Link]+xml"
name=""
href="[Link] />
<vmext:MoRef>datastore-45</vmext:MoRef>
<vmext:VimObjectType>DATASTORE</vmext:VimObjectType>
</vmext:VimObjectRef>
</vmext:DataStoreRefs>
</vmext:VMWStorageProfile>
<vmext:VMWStorageProfile
name="Silver">
...
</vmext:VMWStorageProfile>
<vmext:VMWStorageProfile
name="Bronze">
...
</vmext:VMWStorageProfile>
</vmext:VMWStorageProfiles>

Create an Organization
To create an organization, a system administrator POSTs an AdminOrg element to the cloud’s add URL for
orgs.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the cloud.

Use a request like this one.

GET [Link]

VMware, Inc. 279

vCloud API Programming Guide for Service Providers

2 Examine the response to locate the Link element that contains the URL for adding organizations to the
cloud.

This element has a rel attribute value of add and a type attribute value of
application/[Link]+xml, as shown here:

<Link href="[Link]
rel="add"
type="application/[Link]+xml"/>

3 Create an AdminOrg element that specifies the properties of the organization.

See the request portion of “Example: Create an Organization,” on page 280.

4 POST the AdminOrg element you created in Step 3 to the URL described in Step 2.

See the request portion of “Example: Create an Organization,” on page 280.

The server creates and enables the organization, and returns an AdminOrg element that includes the contents
you POSTed, along with a set of Link elements that you can use to access, remove, disable, or modify it.
vCloud API users can log in to this organization using the URL specified in the href attribute of the Link
where rel="alternate". Users of the vCloud Director Web console can log in to the organization at a URL of
the form cloud-url/org/name, where cloud-url is a URL of the form [Link] and
name is the value of the name attribute of the AdminOrg element. To log in to the organization created by
“Example: Create an Organization,” on page 280, a user opens a browser and navigates to
[Link]

Example: Create an Organization

This request creates an organization and specifies its required properties. For a list of all required and
optional elements that an AdminOrg contains, see the schema reference.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<AdminOrg
xmlns="[Link]
name="Finance"
type="application/[Link]+xml">
<Description>Example Corporation’s Finance Organization</Description>
<FullName>Finance</FullName>
<Settings>
<OrgGeneralSettings>
<CanPublishCatalogs>false</CanPublishCatalogs>
<CanPublishExternally>true</CanPublishExternally>
<CanSubscribe>false</CanSubscribe>
<DeployedVMQuota>0</DeployedVMQuota>
<StoredVmQuota>0</StoredVmQuota>
<UseServerBootSequence>false</UseServerBootSequence>
<DelayAfterPowerOnSeconds>0</DelayAfterPowerOnSeconds>
</OrgGeneralSettings>
<OrgLdapSettings>
<OrgLdapMode>SYSTEM</OrgLdapMode>
<CustomUsersOu />
</OrgLdapSettings>
<OrgEmailSettings>

280 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

<IsDefaultSmtpServer>true</IsDefaultSmtpServer>
<IsDefaultOrgEmail>true</IsDefaultOrgEmail>
<FromEmailAddress />
<DefaultSubjectPrefix />
<IsAlertEmailToAllAdmins>true</IsAlertEmailToAllAdmins>
</OrgEmailSettings>
</Settings>
</AdminOrg>

The response contains information extracted from the request, and includes links that an administrator can
use to manage the organization and its settings, and to add resources such as VDCs, catalogs, and users. On
creation, AdminOrg objects are disabled by default unless the create request includes an IsEnabled element
with a value of true. A system administrator must enable a disabled AdminOrg before users can log into it.

The response also includes elements inherited from system defaults, such as OrgPasswordPolicySettings,
VAppLeaseSettings, and VAppTemplateLeaseSettings. The full content of these elements appears in the actual
response. This example shows only a subset.

Response:

201 Created
Content-Type: application/[Link]+xml
...
<AdminOrg
xmlns="[Link]
name="Finance"
id="urn:vcloud:org:26"
type="application/[Link]+xml"
href="[Link]
<Link
rel="add"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="add"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="add"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="add"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="remove"
href="[Link] />
<Link
rel="enable"
href="[Link] />
<Link
rel="alternate"

VMware, Inc. 281

vCloud API Programming Guide for Service Providers

type="application/[Link]+xml"
href="[Link] />
<Description>Example Corporation’s Finance Organization</Description>
<FullName>Finance</FullName>
<IsEnabled>false</IsEnabled>
<Settings
type="application/[Link]+xml"
href="[Link]
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<OrgGeneralSettings
type="application/[Link]+xml"
href="[Link]
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<CanPublishCatalogs>false</CanPublishCatalogs>
<CanPublishExternally>true</CanPublishExternally>
<CanSubscribe>false</CanSubscribe>
<DeployedVMQuota>0</DeployedVMQuota>

282 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

<StoredVmQuota>0</StoredVmQuota>
<UseServerBootSequence>false</UseServerBootSequence>
<DelayAfterPowerOnSeconds>0</DelayAfterPowerOnSeconds>
</OrgGeneralSettings>
<VAppLeaseSettings>
...
</VAppLeaseSettings>
<VAppTemplateLeaseSettings>
</VAppTemplateLeaseSettings>
<OrgLdapSettings>
...
</OrgLdapSettings>
<OrgEmailSettings>
...
</OrgEmailSettings>
<OrgPasswordPolicySettings>
...
</OrgPasswordPolicySettings>
<OrgOperationLimitsSettings>
...
</OrgOperationLimitsSettings>
<OrgFederationSettings>
...
</OrgFederationSettings>
</Settings>
</AdminOrg>

Edit Organization Rights

An organization is initially granted a set of rights that is the union of all rights contained in the predefined
roles. A system administrator can grant additional rights to an organization or remove rights previously
granted.

When you create an organization, you can include an explicit set of RightReferences in the AdminOrg request
body if you want the organization to include a set of rights that differs from the set it would otherwise
receive on creation. If you do this, the predefined roles are created in the organization with a set of rights
that is the intersection of the rights in the predefined role and the rights you granted to the organization.
You can also edit the rights available in an existing organization, as shown in “Example: Grant Additional
Rights to an Organization,” on page 284. When you edit the rights in an organization, you replace the
existing set of rights with a new set of rights. The replacement set of rights typically combines the rights that
currently exist in the organization with additional rights available from the system.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the set of rights available in the system.

Use a request like this one:

GET [Link]

The RightReferences element returned by this request includes a RightReference for each right that you
can grant to an organization.

VMware, Inc. 283

vCloud API Programming Guide for Service Providers

2 Retrieve the set of rights that exist in the organization.

Use a request like this one:

GET [Link]

The OrgRights element returned by this request includes a RightReference for each right that exists in
the organization.

3 Create an OrgRights request body that includes the rights returned by the request you made in Step 2
and the additional rights (a subset of the rights returned by request you made in Step 1) that you want
to grant to the organization.

See “Example: Grant Additional Rights to an Organization,” on page 284.

4 PUT the modified OrgRights request body to the organization's edit link for rights.

Example: Grant Additional Rights to an Organization

This request adds several unassigned rights (rights that are not part of any predefined role) to the set of
rights that exist in an organization. The request replaces the rights in the organization with the set of rights
in the request body, so you must include existing rights as well as new ones. Any rights not present in the
request body are removed from the organization, and from all organization roles that include them.

Request:

PUT [Link]
Content-type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<OrgRights xmlns="[Link]
<!-- include the existing rights -->
<RightReference
href="[Link]
name="Disk: Change Owner"
type="application/[Link]+xml" />
<RightReference
href="[Link]
name="Organization vDC Gateway: Configure Services"
type="application/[Link]+xml" />
...

<!-- then add the new rights -->

<RightReference
href="[Link]
name="vApp: Allow All Extra Config"
type="application/[Link]+xml" />
<RightReference
href="[Link]
name="vApp: Allow Ethernet Coalescing Extra Config"
type="application/[Link]+xml" />
<RightReference
href="[Link]
name="vApp: Allow Latency Extra Config"
type="application/[Link]+xml" />
<RightReference

284 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

href="[Link]
name="vApp: Allow Matching Extra Config"
type="application/[Link]+xml" />
</OrgRights>

The response (only a portion of which is shown here) includes the new set of OrgRights. It also includes a
link you can use to edit this list of rights.

Response:

<?xml version="1.0" encoding="UTF-8"?>

<OrgRights
xmlns="[Link]
href="[Link]
<Link
rel="edit"
href="[Link]
type="application/[Link]+xml" />
<RightReference
href="[Link]
name="Disk: Change Owner"
type="application/[Link]+xml" />
<RightReference
href="[Link]
name="Organization vDC Gateway: Configure Services"
type="application/[Link]+xml" />
...
<RightReference
href="[Link]
name="vApp: Allow All Extra Config"
type="application/[Link]+xml" />
<RightReference
href="[Link]
name="vApp: Allow Ethernet Coalescing Extra Config"
type="application/[Link]+xml" />
<RightReference
href="[Link]
name="vApp: Allow Latency Extra Config"
type="application/[Link]+xml" />
<RightReference
href="[Link]
name="vApp: Allow Matching Extra Config"
type="application/[Link]+xml" />
</OrgRights>

Enable, Disable, or Remove an Organization

An AdminOrg element includes action links that a system administrator can use to enable, disable, or remove
the organization.

Prerequisites
n This operation is restricted to system administrators.

n Retrieve the XML representation of the organization. See “Retrieve a List of Organizations Accessible to
You,” on page 54.

VMware, Inc. 285

vCloud API Programming Guide for Service Providers

Procedure
n To enable an organization, POST a request to its action/enable link.

n To disable an organization, POST a request to its action/disable link.

n To remove an organization, remove all the objects it contains, then disable and remove it.

a Delete all of the following from the organization:

n local users and groups

n catalogs

n VDCs

b POST a request to the action/disable link to disable the organization.

After the organization is disabled, its representation includes a rel="remove" link.

c Make a DELETE request to the organization's rel="remove" link.

Note You can make a request like this one, which adds the query string recursive=true to the Org
href, to remove an organization that contains one or more objects as long as those objects are in a state
that normally allows removal.

DELETE [Link]

You can use an additional query parameter to force this kind of recursive removal even when the
organization contains objects that are not in an appropriate state for removal.

DELETE [Link]

The server takes the requested action and returns a Task.

Create a Provider VDC

A Provider VDC is a collection of compute, memory, and storage resources from one vCenter server. A
Provider VDC provides resources to organization VDCs.

A Provider VDC is represented as a VMWProviderVdc element in the extension view and a ProviderVdc
element in the admin view. A system administrator can create a VMWProviderVdc or modify it to add or
remove datastores, storage profiles, and resource pools, or change other properties such as its description. A
system administrator cannot change the primary resource pool or vCenter server that was specified when
the Provider VDC was created. An organization administrator can retrieve a read-only representation of a
Provider VDC in a ProviderVdc element. The ProviderVdc element includes a subset of the elements and
attributes that are visible in the corresponding VMWProviderVdc.

Prerequisites
n This operation is restricted to system administrators.

n Choose a vCenter server to supply a resource pool and storage profiles to this Provider VDC. See
“Finding Available vCenter Resources,” on page 270.

Procedure
1 Retrieve the XML representation of the vSphere platform extensions.

Use a request like this one.

GET [Link]

286 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

2 Examine the response to locate the Link element that contains the URL for adding Provider VDCs to the
cloud.

This element has a rel attribute value of add and a type attribute value of
application/[Link]+xml, as shown here:

<Link
type="application/[Link]+xml"
rel="add"
href="[Link]

3 Create a VMWProviderVdcParams element that specifies the properties of the Provider VDC.

a Include a VimServer element that references the vCenter server that you have chosen to supply a
resource pool and storage profiles to this Provider VDC.

b Include a ResourcePoolRefs element that specifies one resource pool.

The ResourcePoolRef must contain the href attribute value of the VimServer element you created in
Step 3a, as well as the MoRef and VimObjectType values of the resource pool as they appear in the
ResourcePool and element from the resource pool list. See the request portion of “Example: Create
a Provider VDC,” on page 287.

Note You must specify exactly one resource pool when you create the Provider VDC. You can
add more resource pools after the Provider VDC is created.

c Include at least one StorageProfile element that contains the name of a storage profile that has
been defined on the vCenter server referenced in the VimServer element you created in Step 3a.

4 POST the VMWProviderVdc element you created in Step 3 to the URL described in Step 2.

See the request portion of “Example: Create a Provider VDC,” on page 287.

The server creates and enables the Provider VDC and returns a VMWProviderVdc element that includes
information derived from the contents you POSTed, along with a set of Link elements that you can use to
access, remove, disable, or modify the Provider VDC.

n The new Provider VDC becomes a member of the ProviderVdcReferences element of the VCloud.

n The resource pool you selected is removed from the resource pool list of the vCenter server.

n Each storage profile you specified becomes the basis for a ProviderVdcStorageProfile object, and can be
retrieved from the Provider VDC after it has been created, or by using a providerVdcStorageProfile
query.

n A VxlanPoolType network pool is created on the vCenter server referenced by the VimServer element
you created in Step 3a and implicitly attached to the new Provider VDC. You can create other types of
network pools on that vCenter server if you want them to be available in the Provider VDC. See “Create
a Network Pool,” on page 300.

Example: Create a Provider VDC

This request creates a Provider VDC specifying a resource pool extracted from the response portion of
“Example: Retrieve a List of Resource Pools from a vCenter Server,” on page 272 and a storage profile
extracted from “Example: Retrieve a List of Storage Profiles from a vCenter Server,” on page 278. The
vCenter server that provides the resources (the resource pool whose MoRef is resgroup-195 and a storage
profile named Gold) is referenced in the VimServerRef and VimServer elements.

VMware, Inc. 287

vCloud API Programming Guide for Service Providers

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:VMWProviderVdcParams
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
name="PVDC-Example">
<vcloud:Description>Example Provider VDC</vcloud:Description>
<vmext:ResourcePoolRefs>
<vmext:VimObjectRef>
<vmext:VimServerRef
href="[Link] />
<vmext:MoRef>resgroup-195</vmext:MoRef>
<vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType>
</vmext:VimObjectRef>
</vmext:ResourcePoolRefs>
<vmext:VimServer
href="[Link] />
<vmext:StorageProfile>Gold</vmext:StorageProfile>
</vmext:VMWProviderVdcParams>

The response includes a Task that tracks the creation of the Provider VDC, and a set of Link elements that
you can use to operate on or modify the Provider VDC. It also includes read-only values for
ComputeCapacity and SupportedHardwareVersions, and a list of HostReferences identifying the ESX hosts
that provide the resources.

Response:

201 Created
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:VMWProviderVdc
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
status="0"
name="PVDC-Example"
id="urn:vcloud:providervdc:35"
type="application/[Link]+xml" ... >
<vcloud:Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="alternate"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="update:resourcePools"
type="application/[Link]+xml"

href="[Link]
/>
<vcloud:Link

288 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

rel="down"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="down"
type="application/[Link]+xml"

href="[Link] />
<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Description>Example Provider VDC</vcloud:Description>
<vcloud:Tasks>
<vcloud:Task
...
operation="Creating Provider Virtual Datacenter PVDC-Example(35)">
...
</vcloud:Task>
</vcloud:Tasks>
<vcloud:ComputeCapacity>
<vcloud:Cpu>
<vcloud:Units>MHz</vcloud:Units>
<vcloud:Allocation>0</vcloud:Allocation>
<vcloud:Total>0</vcloud:Total>
<vcloud:Used>0</vcloud:Used>
<vcloud:Overhead>0</vcloud:Overhead>
</vcloud:Cpu>
<vcloud:Memory>
<vcloud:Units>MB</vcloud:Units>
<vcloud:Allocation>0</vcloud:Allocation>
<vcloud:Total>0</vcloud:Total>
<vcloud:Used>0</vcloud:Used>
<vcloud:Overhead>0</vcloud:Overhead>
</vcloud:Memory>
</vcloud:ComputeCapacity>
<AvailableNetworks>
<Network
type="application/[Link]+xml"
name="VC1-VLAN48"
href="[Link] />
</AvailableNetworks>
<StorageProfiles>
<ProviderVdcStorageProfile
type="application/[Link]+xml"
name="Gold"
href="[Link] />
</StorageProfiles>
<Capabilities>
<SupportedHardwareVersions>
<SupportedHardwareVersion>vmx-04</SupportedHardwareVersion>
<SupportedHardwareVersion>vmx-07</SupportedHardwareVersion>
<SupportedHardwareVersion>vmx-08</SupportedHardwareVersion>
</SupportedHardwareVersions>
</Capabilities>

VMware, Inc. 289

vCloud API Programming Guide for Service Providers

<IsEnabled>true</IsEnabled>
<vcloud:NetworkPoolReferences>
<vcloud:NetworkPoolReference
type="application/[Link]+xml"
name="VXLAN01"
href="[Link]
b8f6-2e2a11785c9f" />
</vcloud:NetworkPoolReferences>
<vmext:DataStoreRefs />
<vmext:ResourcePoolRefs>
<vmext:VimObjectRef>
<vmext:VimServerRef
type="application/[Link]+xml"
name="VC-A"
href="[Link] />
<vmext:MoRef>resgroup-195</vmext:MoRef>
<vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType>
</vmext:VimObjectRef>
</vmext:ResourcePoolRefs>
<vmext:VimServer
type="application/[Link]+xml"
name="ConfigWizard Configured vCenter"
href="[Link] />
<vmext:HostReferences>
<vmext:HostReference
type="application/[Link]+xml"
name="[Link]"
href="[Link] />
<vmext:HostReference
type="application/[Link]+xml"
name="[Link]"
href="[Link] />
</vmext:HostReferences>
</vmext:VMWProviderVdc>

Retrieve a Provider VDC Resource Pool Set

The VMWProviderVdcResourcePoolSet of a Provider VDC contains information about all of the Provider
VDC's resource pools. Getting this information is usually a prerequisite to adding or removing a resource
pool.

Each reference in a VMWProviderVdcResourcePoolSet lists the vCenter server that provides the resource pool
and indicates whether the resource pool is primary. All resource pools in a VMWProviderVdcResourcePoolSet
must come from the same vCenter server.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the Provider VDC.

Use a request like this one:

GET [Link]

290 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

2 Locate the resourcePools link in the VMWProviderVdc.

Every VMWProviderVdc element includes a link like this one to the Provider VDC's resource pools.

<Link
rel="down"
type="application/[Link]+xml"
href="[Link]

3 Retrieve the VMWProviderVdcResourcePoolSet for the Provider VDC.

See “Example: Retrieve a Resource Pool Set,” on page 291.

Example: Retrieve a Resource Pool Set

This example lists the resource pools for the Provider VDC created in “Example: Create a Provider VDC,”
on page 287. The response is a VMWProviderVdcResourcePoolSet that contains two resource pools, one of
which is designated primary. Both reference the same vCenter server at
[Link]

Request:

GET [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:VMWProviderVdcResourcePoolSet
xmlns:vmext="[Link]
xmlns:vcloud="[Link] ... >
<vcloud:Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<vmext:VMWProviderVdcResourcePool
primary="true">
<vcloud:Link
rel="migrateVms"

href="[Link] />
<vcloud:Link
rel="resourcePoolVmList"
href="[Link] />
<vmext:ResourcePoolVimObjectRef>
<vmext:VimServerRef
type="application/[Link]+xml"
name="ConfigWizard Configured vCenter"
href="[Link] />
<vmext:MoRef>resgroup-235</vmext:MoRef>
<vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType>
</vmext:ResourcePoolVimObjectRef>
<vmext:ResourcePoolRef
type="application/[Link]+xml"

VMware, Inc. 291

vCloud API Programming Guide for Service Providers

href="[Link] />
<vmext:Enabled>true</vmext:Enabled>
</vmext:VMWProviderVdcResourcePool>
</vmext:VMWProviderVdcResourcePoolSet>

Update Provider VDC Resource Pools

A system administrator can update the resource pool set of an existing Provider VDC to add or remove
resource pools. Adding resource pools allows organization VDCs that reference the Provider VDC to
consume additional resources during periods of high demand. Removing resource pools frees the
underlying resources.

When you create a Provider VDC, it initially contains a single resource pool, called the primary resource
pool. Adding secondary resource pools allows a Provider VDC to support resource elasticity in organization
VDCs that use the AllocationPool or AllocationVApp (pay as you go) allocation model. Resource elasticity
allows an organization VDC's compute resources to grow or shrink on demand.

All of a Provider VDC's resource pools must come from the same vCenter. See “Retrieve a List of Resource
Pools from a vCenter Server,” on page 272.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the Provider VDC.

Use a request like this one:

GET [Link]

2 Locate the updateResourcePools link in the VMWProviderVdc.

Every VMWProviderVdc element includes an action link like this one to the Provider VDC's
updateResourcePools action.

<Link
rel="update:resourcePools"
type="application/[Link]+xml"

href="[Link]
s"/>

3 Retrieve the resource pool list from the Provider VDC.

The VMWProviderVdcResourcePoolSet contains references to the Provider VDC's existing resource pools
and the vCenter server that hosts them.

4 Update the resource pool set.

To add resource pools:

a Choose another resource pool from the same vCenter server.

b Create an UpdateResourcePoolSetParams element that contains an AddItem element for each

resource pool to add.

292 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

To remove resource pools:

a Examine the resource pool list and find the pool to remove.

b Verify the pool is not the primary resource pool, and that no virtual machines are using it.

If necessary, use the action/migrateVms link to migrate virtual machines to another resource pool.
c Create an UpdateResourcePoolSetParams element that contains a DeleteItem element for each
resource pool to remove.

5 POST the UpdateResourcePoolSetParams element to the Provider VDC's resourcePools link.

Example: Update Provider VDC Resource Pools

This request adds a resource pool to the Provider VDC created in “Example: Create a Provider VDC,” on
page 287. The additional resource pool is hosted on the same vCenter server that hosts the existing resource
pool. See “Retrieve a List of Resource Pools from a vCenter Server,” on page 272 for an example that lists the
resource pools available on that server.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:UpdateResourcePoolSetParams
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
<vmext:AddItem>
<vmext:VimServerRef
type="application/[Link]+xml"
href="[Link] />
<vmext:MoRef>resgroup-230</vmext:MoRef>
<vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType>
</vmext:AddItem>
</vmext:UpdateResourcePoolSetParams>

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... >
...
</Task>

This request removes one of the two resource pools (a secondary resource pool) shown in “Retrieve a
Provider VDC Resource Pool Set,” on page 290. The response is a task.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:UpdateResourcePoolSetParams
xmlns:vmext="[Link]

VMware, Inc. 293

vCloud API Programming Guide for Service Providers

xmlns:vcloud="[Link]
<vmext:DeleteItem
href="[Link] />
</vmext:UpdateResourcePoolSetParams>

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... >
...
</Task>

Update Provider VDC Storage Profiles

A system administrator can update the storage profiles that are included in a Provider VDC. New storage
profiles can be added, and unused storage profiles can be removed.

Storage profiles can be created by a vCenter administrator on any vCenter server that supports the profile-
driven storage feature. A Provider VDC can provide access to any of the storage profiles that have been
created on its vCenter server (the one referenced in its vmext:VimServer element). A vCloud Director system
administrator must specify at least one vCenter storage profile when creating a Provider VDC, and can add
or remove storage profiles later as needed. Organization VDCs reference Provider VDC storage profiles in
much the same way that Provider VDCs reference vCenter storage profiles. Media and Disk objects, as well
as vApps and virtual machines reference organization VDC storage profiles by name.

Note Storage profiles are represented as Storage Policies in the vCloud Director Web console.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the Provider VDC.

Use a request like this one:

GET [Link]

2 Examine the VMWProviderVdc element to find the storageProfiles link and the vmext:VimServer
element.

The storageProfiles link has the following form:

<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />

3 Create an UpdateProviderVdcStorageProfiles request body that specifies the details of the update.

To add a storage profile:

a Choose another storage profile from the vCenter server referenced in the vmext:VimServer element
you located in Step 2.

b Create an UpdateProviderVdcStorageProfiles element that contains an AddStorageProfile element

for each storage profile to add.

294 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

To remove a storage profile:

a Retrieve the Provider VDC's availableStorageProfiles list and find the name of the profile to
remove.

Use a request like this one:

GET
[Link]

b Verify that no organization VDCs are using the storage profile you want to remove.

c Create an UpdateProviderVdcStorageProfiles element that contains a RemoveStorageProfile

element for each storage profile to remove.

4 POST the UpdateProviderVdcStorageProfiles element to the Provider VDC's storageProfiles link.

The server returns a Task element that you can use to track the progress of the update. When the update is
complete, the Provider VDC includes the updated set of storage profiles in its StorageProfiles element.
Each storage profile you added becomes the basis for a ProviderVdcStorageProfile object, and can be
retrieved from the Provider VDC after it has been created, or by using a providerVdcStorageProfile query.

Example: Update Provider VDC Storage Profiles

This request adds a storage profile named Bronze to the Provider VDC created in “Example: Create a
Provider VDC,” on page 287. The new storage profile is hosted on the same vCenter server that hosts the
existing storage profile. See “Retrieve a List of Storage Profiles from a vCenter Server,” on page 277 for an
example that lists the storage profiles available on that server.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:UpdateProviderVdcStorageProfiles
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
<vmext:AddStorageProfile>Bronze</vmext:AddStorageProfile>
</vmext:UpdateProviderVdcStorageProfiles>

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... >
...
</Task>

Configure Storage I/O Control Support in a Provider VDC

If you want to enable specification of hard disk read/write performance by members of an organization, a
Provider VDC that supports the organization must include a storage profile that is backed by an
appropriately configured vSphere datastore.

Managed read/write performance in physical storage devices and virtual disks is defined in units called
IOPS, which measure read/write operations per second. When an organization VDC storage profile is
backed by a Provider VDC storage profile that includes storage devices that are capable of IOPS allocation,
you can configure disks that use it to request a specified level of I/O performance. A storage profile

VMware, Inc. 295

vCloud API Programming Guide for Service Providers

configured with IOPS support delivers its default IOPS value to all disks that use it, even disks that are not
configured to request a specific IOPS value. A hard disk configured to request a specific IOPS value cannot
use a storage profile whose maximum IOPS value is lower than the requested value, or a storage profile that
is not configured with IOPS support.

When backed by an appropriately configured Provider VDC storage profile, storage profiles in an
organization VDC can be configured to support delivery of a specified level of I/O performance to disks that
use them. See “Configure Storage I/O Control Support in an Organization VDC,” on page 313.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Choose or create an appropriately configured vSphere storage policy.

Before vCloud Director can enable IOPS for a Provider VDC storage profile, an IOPS-enabled vSphere
storage policy must exist on a vCenter server registered to vCloud Director.

n The storage devices backing the underlying vSphere datastores must be capable of IOPS support.

Note You cannot enable IOPS support on a VMware Virtual SAN datastore.

n A vSphere administrator must configure the datastores with a specific vSphere custom field and
value, as described in VMware Knowledge Base article [Link]

n A vSphere administrator must create a vSphere storage policy that includes the IOPS-capable
datastore.

2 Include the IOPS-capable vSphere storage profile in a Provider VDC.

Reference the IOPS-capable vSphere storage profile by name in a ProviderVdcStorageProfile element

in the VMWProviderVdcParams request body you use when creating a Provider VDC or in the
UpdateProviderVdcStorageProfiles element in an updateStorageProfiles request body you use when
updating Provider VDC storage profiles.

Merge Provider VDCs

You can merge two Provider VDCs by specifying a target Provider VDC and a contributor Provider VDC to
merge with it. The merged Provider VDC contains all resources from the target and contributor Provider
VDCs

Because merging Provider VDCs is a resource-intensive operation, vCloud Director allows only a single
contributor to a merge. You can merge multiple Provider VDCs into a single target by making multiple
merge requests, each specifying the same target and a new contributor.

When the merge is complete:

n Networks, network pools, storage profiles, resource pools, and datastores from the contributor Provider
VDC are available in the target Provider VDC.

n Organization VDCs that were backed by the contributor are now backed by the target.

n The contributor Provider VDC is deleted.

Prerequisites
This operation is restricted to system administrators.

296 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

Procedure
1 Identify the Provider VDCs to merge.

Select a contributor that is not backed by the same resource pool as the target. You can use a query like
this one to discover the resource pools backing each of your Provider VDCs.

GET [Link]

2 Construct a ProviderVdcMergeParams element whose ProviderVdcReference references the contributor.

See the request portion of “Example: Merge Provider VDCs,” on page 297.

3 Make a POST request to the action/merge link of the target Provider VDC and supply the
ProviderVdcMergeParams as the request body.

Example: Merge Provider VDCs

This request merges the Provider VDC at
[Link] with the target Provider VDC specified
in the request URL.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<vmext:ProviderVdcMergeParams
type="application/[Link]+xml"
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
<vmext:ProviderVdcReference
type="application/[Link]+xml"
name="PVDC-VC001"
href="[Link] />
</vmext:ProviderVdcMergeParams>

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... >
...
</Task>

Create an External Network

An external network is a reference to a portgroup on a vCenter server attached to vCloud Director. To create
an external network, a system administrator must specify the vCenter server and a portgroup associated
with it. External networks provide support for bridged organization networks.

Only a system administrator can create an external network. A system administrator can modify an external
network to change properties such as its description, and to add or remove portgroups in the
VimPortGroupRefs element. An organization administrator can retrieve a read-only representation of an
external network to examine its properties.

Prerequisites
n This operation is restricted to system administrators.

VMware, Inc. 297

vCloud API Programming Guide for Service Providers

n Retrieve the list of available portgroups. See “Retrieve a List of Available Portgroups and Switches from
a vCenter Server,” on page 273.

Procedure
1 Retrieve the XML representation of the vSphere platform extensions.
Use a request like this one.

GET [Link]

2 Examine the response to locate the Link element that contains the URL for adding external networks to
the cloud.

This element has a rel attribute value of add and a type attribute value of
application/[Link]+xml, as shown here:

<Link
type="application/[Link]+xml"
rel="add"
href="[Link]

3 Choose a vCenter server to provide a portgroup for the network.

4 Create a VMWExternalNetwork element that specifies the properties of the external network.

These properties include the portgroup you specified in Step 3.

5 POST the VMWExternalNetwork element you created in Step 4 to the URL described in Step 2.

See the request portion of “Example: Create an External Network,” on page 298.

The server creates the external network and returns a VMWExternalNetwork element that includes the contents
you POSTed, along with a set of Link elements that you can use to access, remove, disable, or modify it. A
reference to the new external network is added to the VMWExternalNetworkReferences element of the VCloud.
The portgroup you specified is removed from the VimObjectRefList of the vCenter server.

Example: Create an External Network

This request creates an external network backed by one of the portgroups listed in the response portion of
“Retrieve a List of Available Portgroups and Switches from a vCenter Server,” on page 273.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:VMWExternalNetwork
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
name="example-extnet"
type="application/[Link]+xml">
<vcloud:Description>ExternalNet</vcloud:Description>
<vcloud:Configuration>
<vcloud:IpScopes>
<vcloud:IpScope>
<vcloud:IsInherited>false</vcloud:IsInherited>
<vcloud:Gateway>[Link]</vcloud:Gateway>
<vcloud:Netmask>[Link]</vcloud:Netmask>
<vcloud:Dns1>[Link]</vcloud:Dns1>
<vcloud:Dns2>[Link]</vcloud:Dns2>

298 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

<vcloud:DnsSuffix>[Link]</vcloud:DnsSuffix>
</vcloud:IpScope>
</vcloud:IpScopes>
<vcloud:FenceMode>Isolated</vcloud:FenceMode>
</vcloud:Configuration>
<vmext:VimPortGroupRefs>
<vmext:VimObjectRef>
<vmext:VimServerRef
href="[Link] />
<vmext:MoRef>dvportgroup-175</vmext:MoRef>
<vmext:VimObjectType>DV_PORTGROUP</vmext:VimObjectType>
</vmext:VimObjectRef>
</vmext:VimPortGroupRefs>
</vmext:VMWExternalNetwork>

You can specify more than one VimObjectRef in the VimPortGroupRefs as long as each VimObjectRef
references a portgroup on a different vCenter Server registered to the system and all referenced objects have
the same VimObjectType (DV_PORTGROUP or NETWORK).

The response includes a Task that tracks the creation of the network, and a set of Link elements that you can
use to operate on or modify it.

Response:

201 Created
Content-Type: application/[Link]/vmwexternalnet+xml
...
<vmext:VMWExternalNetwork
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
name="example-extnet"
id="urn:vcloud:network:85"
type="application/[Link]+xml"
href="[Link] >
<vcloud:Link
rel="alternate"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="remove"
href="[Link] />
<vcloud:Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="repair"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Description>ExternalNet</vcloud:Description>
<vcloud:Tasks>
<vcloud:Task
status="running"

VMware, Inc. 299

vCloud API Programming Guide for Service Providers

startTime="2011-03-10T[Link].506-08:00"
operationName="_network_create_provider_network"
operation="Busy Network example-extnet(85)" ... >
...
</vcloud:Task>
</vcloud:Tasks>
...
</vmext:VMWExternalNetwork>

Create a Network Pool

Network pools provide support for isolated and routed networks in organization VDCs. Although every
Provider VDC includes a VXLAN network pool that can support most networking use cases, a system
administrator can create other types of network pools if they are needed.

A network pool object represents a collection of vSphere network resources that are contained by a Provider
VDC and available to the organization VDCs backed by that Provider VDC. Traffic on each network in a
pool is isolated at layer 2 from all other networks.

Only a system administrator can create a network pool. A system administrator can modify a network pool
to change properties such as its description, but cannot change the network resources, such as virtual
switches or portgroups, that provide backing for it. After a network pool has been associated with an
organization VDC (typically when the VDC is created), network resources from the pool are consumed as
needed to create isolated or routed organization VDC networks or vApp networks in the VDC.

Note When you create a Provider VDC, a VxlanPoolType network pool is created automatically on the
vCenter server that backs the Provider VDC. This pool is given a name derived from the name of the
containing Provider VDC and attached to it at creation. You cannot delete or modify this network pool. You
cannot create aVxlanPoolType network pool by any other method. If you rename a Provider VDC, its
VxlanPoolType network pool is automatically renamed.

vSphere VXLAN networks are based on the IETF draft VXLAN standard. These networks support local-
domain isolation equivalent to what is supported by vSphere isolation-backed networks. In addition, they
provide:

n logical networks spanning layer 3 boundaries

n logical networks spanning multiple racks on a single layer 2

n broadcast containment

n higher performance

n greater scale (up to 16 million network addresses)

All network pools are defined by a VMWNetworkPool element. The contents of this element depend on its type,
which is specified in its xsi:type attribute. The following values of xsi:type are supported for pools created
by a system administrator.

VlanPoolType This pool type is based on ESXi VLANs on the vCenter server that backs the
Provider VDC, and is backed by a range of VLAN IDs.

PortGroupPoolType This pool type is based on distributed port groups of a vSphere distributed
switch or third-party distributed switch on the vCenter server that backs the
Provider VDC.

Prerequisites
This operation is restricted to system administrators.

300 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

Procedure
1 Retrieve the XML representation of the vSphere platform extensions.

Use a request like this one.

GET [Link]

2 Examine the VMWExtension response to locate the Link element that contains the URL for adding
network pools to your cloud.

This element has a rel attribute value of add and a type attribute value of
application/[Link]+xml, as shown here:

<Link
type="application/[Link]+xml"
rel="add"
href="[Link]

3 Create a VMWNetworkPool element that specifies the pool type and backing vCenter resources.

Details of this element's contents depend on the type of pool you are creating.

4 POST the VMWNetworkPool element you created in Step 3 to the URL described in Step 2.

The server creates the network pool and returns a VMWNetworkPool element that includes the contents you
POSTed, along with a set of Link elements that you can use to access, remove, disable, or modify it. A
reference to the new network pool is added to the VMWNetworkPoolReferences element of the VCloud.
Network resources you specified in the VMWNetworkPool element are removed from the VimObjectRefList of
the vCenter server.

Create a VLAN-Backed Network Pool

To create a VLAN-backed network pool, create a VMWNetworkPool element whose type attribute has the value
VlanPoolType, and POST the element to your cloud's add link for networkPools.

A VLAN-backed network pool is backed by a range of VLAN IDs.

Prerequisites
n This operation is restricted to system administrators.

n Verify that you know your cloud's add URL for networkPools. See “Create a Network Pool,” on
page 300.

n Verify that at least one vCenter server attached to your cloud has network resources available. See
“Retrieve a List of Available Portgroups and Switches from a vCenter Server,” on page 273

Procedure
1 Choose a vCenter server to provide a switch for the network pool.
2 Create a VMWNetworkPool element that specifies the properties of the network pool.

See the request portion of “Example: Create a VLAN-Backed Network Pool,” on page 301.

3 POST the VMWNetworkPool element you created in Step 2 to your cloud's add URL for networkPools.

See the request portion of “Example: Create a VLAN-Backed Network Pool,” on page 301.

Example: Create a VLAN-Backed Network Pool

Use the query service to retrieve a list of DV Switch objects available on vCenter servers registered to this
cloud.

[Link]

VMware, Inc. 301

vCloud API Programming Guide for Service Providers

The query response includes the values you'll need for the VimServerRef and MoRef elements. The
VimObjectType for a DV Switch is always DV_SWITCH.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:VMWNetworkPool
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
xmlns:xsi="[Link]
xsi:type="vmext:VlanPoolType"
name="example-Vlan-pool">
<vcloud:Description>Example VLAN-backed network pool</vcloud:Description>
<vmext:VlanRange>
<vmext:Start>1</vmext:Start>
<vmext:End>4</vmext:End>
</vmext:VlanRange>
<vmext:VimSwitchRef>
<vmext:VimServerRef
href="[Link] />
<vmext:MoRef>dvs-33</vmext:MoRef>
<vmext:VimObjectType>DV_SWITCH</vmext:VimObjectType>
</vmext:VimSwitchRef>
</vmext:VMWNetworkPool>

The response includes a Task that tracks the creation of the network pool, and a set of Link elements that you
can use to operate on or modify it.

Response:

201 Created
Content-Type: application/[Link]+xml
...
<vmext:VMWNetworkPool
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
xsi:type="vmext:VlanPoolType"
name="example-Vlan-pool"
id="urn:vcloud:networkpool:67"
type="application/[Link]+xml"
href="[Link] ... >
<vcloud:Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="remove"
href="[Link] />
<vcloud:Description>Example VLAN-backed network pool</vcloud:Description>
<vcloud:Tasks>
<vcloud:Task

302 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

status="running"
...
operation="Creating Network Pool 67"
...
</vcloud:Task>
</vcloud:Tasks>
...
</vmext:VMWNetworkPool>

Create a Portgroup-Backed Network Pool

To create a portgroup-backed network pool, you create a VMWNetworkPool element whose type attribute has
the value PortGroupPoolType, and POST the element to your cloud's add link for networkPools.

Prerequisites
n This operation is restricted to system administrators.

n Verify that you know your cloud's add URL for networkPools. See “Create a Network Pool,” on
page 300.

n Verify that at least one vCenter server attached to your cloud has network resources available. See
“Retrieve a List of Available Portgroups and Switches from a vCenter Server,” on page 273

Procedure
1 Choose a vCenter server to provide a portgroup for the network pool.

2 Create a VMWNetworkPool element that specifies the properties of the network pool.

See the request portion of “Example: Create a Portgroup-Backed Network Pool,” on page 303.

3 POST the VMWNetworkPool element you created in Step 2 to your cloud's add URL for networkPools. See
“Create a Network Pool,” on page 300.

See the request portion of “Example: Create a Portgroup-Backed Network Pool,” on page 303.

Example: Create a Portgroup-Backed Network Pool

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:VMWNetworkPool
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
xmlns:xsi="[Link]
xsi:type="vmext:PortGroupPoolType"
name="example-portgroup-pool"
type="application/[Link]+xml">
<vcloud:Description>Example portgroup-backed network pool</vcloud:Description>
<vmext:PortGroupRefs>
<vmext:VimObjectRef>
<vmext:VimServerRef
href="[Link] />
<vmext:MoRef>dvportgroup-32</vmext:MoRef>
<vmext:VimObjectType>DV_PORTGROUP</vmext:VimObjectType>
</vmext:VimObjectRef>

VMware, Inc. 303

vCloud API Programming Guide for Service Providers

</vmext:PortGroupRefs>
<vmext:VimServer
href="[Link]
</vmext:VMWNetworkPool>

The response includes a Task that tracks the creation of the network pool, and a set of Link elements that you
can use to operate on or modify it.

Response:

201 Created
Content-Type: application/[Link]+xml
...
<vmext:VMWNetworkPool
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
xmlns:xsi="[Link]
xsi:type="vmext:PortGroupPoolType"
name="example-portgroup-pool"
id="urn:vcloud:networkpool:66"
type="application/[Link]+xml"
href="[Link] ... >
<vcloud:Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="remove"
href="[Link] />
<vcloud:Description>Example portgroup-backed network pool</vcloud:Description>
<vcloud:Tasks>
<vcloud:Task
status="running"
...
operation="Creating Network Pool 66"
...
</vcloud:Task>
</vcloud:Tasks>
...
</vmext:VMWNetworkPool>

Add a VDC to an Organization

A system administrator can allocate resources from a provider VDC to a VDC in an organization by
POSTing a CreateVdcParams element to an organization’s add URL for VDCs.

An organization virtual datacenter (organization VDC) is a deployment environment for virtual systems
owned by the containing organization, and an allocation mechanism for resources such as networks,
storage, CPU, and memory. In an organization VDC, computing resources are fully virtualized, and can be
allocated based on demand, service level requirements, or a combination of the two.

Prerequisites
n This operation is restricted to system administrators.

304 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

n Retrieve the list of network pools. Several types of organization VDC networks require the VDC to
include a network pool, which you can specify when you create or update the VDC. See “Retrieve a List
of External Networks and Network Pools,” on page 275 for information about how to retrieve this list.

n If you want the new VDC to adopt specific resource pools, see “Adopt Resource Pools With a VDC,” on
page 310.

Procedure
1 Retrieve the XML representation of the organization to which you want to add the VDC.

Use a request like this one:

GET [Link]

2 Examine the response to locate the Link element that contains the URL for adding VDCs to the
organization.

This element has a rel attribute value of add and a type attribute value of
application/[Link]+xml, as shown here:

<Link
href="[Link]
rel="add"
type="application/[Link]+xml"/>

3 Choose a provider VDC to supply resources for the new organization VDC

a Retrieve the XML representation of the VCloud object and examine the ProviderVdcReferences
element it contains.

The following request retrieves the representation of the VCloud object:

GET [Link]

The VCloud element contains a ProviderVdcReferences element. Each provider VDC in the system
is represented in that element by a ProviderVdcReference element, as shown here:

<ProviderVdcReference
type="application/[Link]+xml"
name="Main Provider"
href="[Link]

b (Optional) List the organization VDCs that each ProviderVdc supports.

The following request retrieves the list of organization VDCs that .../providervdc/2 supports:

GET [Link]

Taking this optional step can help you allocate ProviderVdc resources equitably across the
organization VDCs in a cloud.

VMware, Inc. 305

vCloud API Programming Guide for Service Providers

4 Create a CreateVdcParams request body.

a Include an AllocationModel element that specifies how compute resources are allocated by this
VDC.

Choose one of the following values for AllocationModel:

AllocationVApp Pay as you go. Resources are committed to the organization VDC only
when vApps are created in it. When you use this allocation model,
any Limit values you specify for Memory and CPU are ignored when you
create a vApp and returned as 0 when you retrieve a vApp. Resources
available to this kind of organization VDC can grow or shrink as
needed when its provider VDC has multiple resource pools.

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 resources and limitations.

Note If you choose AllocationPool or ReservationPool, you can also include an

OverCommitAllowed element in the CreateVdcParams request. Setting its value to false prevents
creation of the VDC if the ComputeCapacity you specified is greater than what the backing Provider
VDC can supply.

b Include at least one VdcStorageProfile element that specifies a ProviderVdcStorageProfile defined

in the Provider VDC you chose in Step 3.

c Include a NetworkPoolReference element.

The VDC must include a network pool if you want to create routed or isolated networks in it.

d Include a ProviderVdcReference element that contains a reference to the Provider VDC you chose
in Step 3.
See the request portion of “Example: Create an Organization VDC,” on page 306.

5 POST the CreateVdcParams request body to the organization's add link for vdcs.

See the request portion of “Example: Create an Organization VDC,” on page 306.

The server creates the new VDC in the specified organization and returns an AdminVdc element that includes
a set of Link elements that you can use to access, remove, or modify the new VDC. Users can reference this
VDC using the URL specified in the href attribute in the Link where rel="alternate". See the response
portion of “Example: Create an Organization VDC,” on page 306.

If the target organization already contains the maximum number of VDCs allowed by the system
administrator, the request fails. A system administrator can change the VDC quota for an organization by
updating the value of VdcQuota in the organization's GeneralOrgSettings.

Example: Create an Organization VDC

This example adds an AllocationvApp VDC to the organization created in “Example: Create an
Organization,” on page 280. The new organization VDC is provisioned from the Provider VDC created in
“Create a Provider VDC,” on page 286, and includes a storage profile named Silver, which is backed by one
of the storage profiles available in the Provider VDC. It also includes a network pool, so that it is capable of
supporting routed and isolated organization VDC networks. See “Retrieve a List of External Networks and
Network Pools,” on page 275 for information on how to find a NetworkPoolReference to use.

306 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<CreateVdcParams
name="org26vdc1"
xmlns="[Link]
<Description>Example VDC</Description>
<AllocationModel>AllocationVApp</AllocationModel>
<ComputeCapacity>
<Cpu>
<Units>MHz</Units>
<Allocated>2048</Allocated>
<Limit>2048</Limit>
</Cpu>
<Memory>
<Units>MB</Units>
<Allocated>2048</Allocated>
<Limit>2048</Limit>
</Memory>
</ComputeCapacity>
<NicQuota>0</NicQuota>
<NetworkQuota>100</NetworkQuota>
<VdcStorageProfile>
<Enabled>true</Enabled>
<Units>MB</Units>
<Limit>20480</Limit>
<Default>true</Default>
<ProviderVdcStorageProfile
href="[Link] />
</VdcStorageProfile>
<ResourceGuaranteedMemory>1</ResourceGuaranteedMemory>
<ResourceGuaranteedCpu>1</ResourceGuaranteedCpu>
<VCpuInMhz>2048</VCpuInMhz>
<IsThinProvision>false</IsThinProvision>
<NetworkPoolReference
href="[Link]
<ProviderVdcReference
name="Main Provider"
href="[Link] />
<UsesFastProvisioning>true</UsesFastProvisioning>
</CreateVdcParams>

The response, a subset of which appears here, contains information extracted from the request, and includes
a Task element that tracks creation of the VDC. The response also includes Link elements that enable
administrative operations on the VDC, and a Capabilities element that lists the VMware virtual hardware
architectures that the VDC supports. These elements are retrieved from the Provider VDC that you specified
when you created the CreateVdcParams. While the VDC is under construction, its status remains 0.

Response:

201 Created
Content-Type: application/[Link]+xml
...
<AdminVdc

VMware, Inc. 307

vCloud API Programming Guide for Service Providers

xmlns="[Link]
status="0"
name="org26vdc1"
id="urn:vcloud:vdc:44"
type="application/[Link]+xml"
href="[Link] ... >
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="alternate"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Description>Example VDC</Description>
...
<Tasks>
<Task
name="task"
status="running"
operation="Creating Virtual Datacenter org26vdc1(44)"
...
</Task>
</Tasks>
<AllocationModel>AllocationVApp</AllocationModel>
...
<Capabilities>
<SupportedHardwareVersions>
<SupportedHardwareVersion>vmx-04</SupportedHardwareVersion>
<SupportedHardwareVersion>vmx-08</SupportedHardwareVersion>
</SupportedHardwareVersions>
</Capabilities>
...
</AdminVdc>

When construction is complete, the status changes to 1 and the Task is no longer included in representation.
The following changes in the AdminVdc are also evident:

n A reference to the vSphere resource pool that supports the VDC appears in a ResourcePoolRefs element
and, for compatibility, in a VCloudExtension element.

n There is an empty ResourceEntities element, because the VDC contains no Media, VAppTemplate, or
Disk entities. For information about adding them, see Chapter 4, “Provisioning an Organization,” on
page 61.

n There is an empty AvailableNetworks element. To add networks to this organization VDC, see “Create
an Organization VDC Network,” on page 212.

308 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

n Additional Link elements are included for operations that are now valid, but that were not valid while
the VDC was under construction.

<AdminVdc
xmlns="[Link]
xmlns:vmext="[Link]
status="1"
name="org26vdc1"
id="urn:vcloud:vdc:44"
type="application/[Link]+xml"
href="[Link] ... >
<VCloudExtension
required="false">
<vmext:VimObjectRef>
<vmext:VimServerRef
type="application/[Link]+xml"
name="vc1"
href="[Link] />
<vmext:MoRef>resgroup-949</vmext:MoRef>
<vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType>
</vmext:VimObjectRef>
</VCloudExtension>
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="disable"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="alternate"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="add"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="edgeGateways"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="add"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="orgVdcNetworks"
type="application/[Link]+xml"

VMware, Inc. 309

vCloud API Programming Guide for Service Providers

href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
...
<ResourceEntities />
<AvailableNetworks />
...
<VdcStorageProfiles>
<VdcStorageProfile
type="application/[Link]+xml"
name="Silver"
href="[Link] />
</VdcStorageProfiles>
...
<ResourcePoolRefs>
<vmext:VimObjectRef>
<vmext:VimServerRef
type="application/[Link]+xml"
name="vc1"
href="[Link] />
<vmext:MoRef>resgroup-949</vmext:MoRef>
<vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType>
</vmext:VimObjectRef>
</ResourcePoolRefs>
</AdminVdc>

Adopt Resource Pools With a VDC

When adding a VDC to an organization, a system administrator can specify one or more resource pools that
are available in the supporting Provider VDC. When the VDC is created, the specified resource pools are
said to have been adopted by the VDC. Any vCenter VMs that exist in an adopted resource pool become
available as discovered vApps in the new VDC.

When you create an organization VDC without specifying a resource pool, the system creates the VDC using
the default resource pool of the specified Provider VDC. Before creating an organization VDC, you can
query a Provider VDC to get a list of all resource pools that are candidates for adoption by the new VDC. If
any resource pools contain VMs created in vCenter that your organization would like to access in a VDC,
specify those pools when you create the VDC. vCenter VMs in the specified pools appear in the new VDC as
discovered vApps and are candidates for adoption.

Prerequisites
This operation is restricted to system administrators.

310 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

Procedure
1 Choose a provider VDC to supply resources for the new organization VDC

a Retrieve the XML representation of the VCloud object and examine the ProviderVdcReferences
element it contains.
The following request retrieves the representation of the VCloud object:

GET [Link]

The VCloud element contains a ProviderVdcReferences element. Each provider VDC in the system
is represented in that element by a ProviderVdcReference element, as shown here:

<ProviderVdcReference
type="application/[Link]+xml"
name="Main Provider"
href="[Link]

b (Optional) List the organization VDCs that each ProviderVdc supports.

The following request retrieves the list of organization VDCs that .../providervdc/2 supports:

GET [Link]

Taking this optional step can help you allocate ProviderVdc resources equitably across the
organization VDCs in a cloud.

2 Retrieve the XML representation of the provider VDC you have chosen to back the new organization
VDC.

The VMWProvderVDC response body includes a Link of the following form:

<Link
rel="down"
href="[Link]
type="application/[Link]+xml"/>"

3 Retrieve the list of resource pools that are candidates for adoption by a VDC backed by the selected
Provider VDC.

Use the Link shown in Step 3 to make a request like this one:

GET [Link]
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:VMWDiscoveredResourcePools
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
<vmext:VMWDiscoveredResourcePool
name="pvdc-1 (mapped as pVDC)"
valideCandidate="false">
<vcloud:Link
rel="down"

href="[Link]
group-80"
type="application/[Link]+xml" />
<vmext:ResourcePoolVimObjectRef>
<vmext:VimServerRef
href="[Link]
name="vCenter System 1"
type="application/[Link]+xml" />

VMware, Inc. 311

vCloud API Programming Guide for Service Providers

<vmext:MoRef>resgroup-80</vmext:MoRef>
<vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType>
</vmext:ResourcePoolVimObjectRef>
</vmext:VMWDiscoveredResourcePool>
</vmext:VMWDiscoveredResourcePools>

4 Create a CreateVdcParams request body.

See the request portion of “Example: Add a VDC With an Adopted Resource Pool to an Organization,”
on page 312.

5 POST the CreateVdcParams request body to the organization's add link for vdcs.

See the request portion of “Example: Add a VDC With an Adopted Resource Pool to an Organization,”
on page 312.

Example: Add a VDC With an Adopted Resource Pool to an Organization

This example modifies the request shown in “Example: Create an Organization VDC,” on page 306 to add a
ResourcePoolRefs element that specifies the resource pool identified in Step 3.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<CreateVdcParams
name="org26vdc1"
xmlns:vmext="[Link]
xmlns="[Link]
<Description>Example VDC</Description>
<AllocationModel>AllocationVApp</AllocationModel>
<ComputeCapacity>
<Cpu>
<Units>MHz</Units>
<Allocated>2048</Allocated>
<Limit>2048</Limit>
</Cpu>
<Memory>
<Units>MB</Units>
<Allocated>2048</Allocated>
<Limit>2048</Limit>
</Memory>
</ComputeCapacity>
<NicQuota>0</NicQuota>
<NetworkQuota>100</NetworkQuota>
<VdcStorageProfile>
<Enabled>true</Enabled>
<Units>MB</Units>
<Limit>20480</Limit>
<Default>true</Default>
<ProviderVdcStorageProfile
href="[Link] />
</VdcStorageProfile>
<ResourceGuaranteedMemory>1</ResourceGuaranteedMemory>
<ResourceGuaranteedCpu>1</ResourceGuaranteedCpu>
<VCpuInMhz>2048</VCpuInMhz>

312 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

<IsThinProvision>false</IsThinProvision>
<NetworkPoolReference
href="[Link]
<ProviderVdcReference
name="Main Provider"
href="[Link] />
<ResourcePoolRefs>
<vmext:VimObjectRef >
<vmext:VimServerRef
href="[Link]
name="VC"
type="application/[Link]+xml"/>
<vmext:MoRef>resgroup-70</vmext:MoRef>
<vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType>
</vmext:VimObjectRef>
</ResourcePoolRefs>
<UsesFastProvisioning>true</UsesFastProvisioning>
</CreateVdcParams>

Configure Storage I/O Control Support in an Organization VDC

You can modify a VDC storage profile to enable support for vCenter Storage I/O Control if that feature is
configured in the underlying Provider VDC.

Managed read/write performance in physical storage devices and virtual disks is defined in units called
IOPS, which measure read/write operations per second. When an organization VDC storage profile is
backed by a Provider VDC storage profile that includes storage devices that are capable of IOPS allocation,
you can configure disks that use it to request a specified level of I/O performance. A storage profile
configured with IOPS support delivers its default IOPS value to all disks that use it, even disks that are not
configured to request a specific IOPS value. A hard disk configured to request a specific IOPS value cannot
use a storage profile whose maximum IOPS value is lower than the requested value, or a storage profile that
is not configured with IOPS support.

vCloud Director sets an IOPS limit and reservation for every disk that uses an IOPS-enabled storage profile.
vSphere is responsible for allocating the IOPS capacity of the underlying datastore across all virtual disks
that use the storage profile. IOPS management is primarily intended to ensure that no disk can consume
more than its fair share of IOPS. Realized IOPS for a given disk are limited by what the backing LUN can
provide, and can be influenced by factors such as read/write block size. While a given storage profile can
include a mix of datastores that IOPS-enabled and those that are not, such configurations can interfere with
the system's ability to allocate IOPS fairly across all disks that use the storage profile.

The ability of a Provider VDC storage profile to provide IOPS support depends on the configuration of the
vSphere datastores that support it. See “Configure Storage I/O Control Support in a Provider VDC,” on
page 295.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the VDC in the admin view, and examine the AdminVdc element to
find the VdcStorageProfiles element it contains.

Request:

GET [Link]

VMware, Inc. 313

vCloud API Programming Guide for Service Providers

Response:

<AdminVdc>
...
<VdcStorageProfiles>
<VdcStorageProfile
href="[Link]
name="*"
type="application/[Link]+xml"/>
<VdcStorageProfile
href="[Link]
name="bronze"
type="application/[Link]+xml"/>
</VdcStorageProfiles>
...
</AdminVdc>

2 Retrieve an organization VDC storage profile to discover the provider VDC storage profile that backs it.

Request:

GET [Link]

Response:

<AdminVdcStorageProfile
xmlns="[Link]
name="bronze"
type="application/[Link]+xml" ... >
...
<ProviderVdcStorageProfile
href="[Link]
name="Bronze"
type="application/[Link]+xml"/>
</AdminVdcStorageProfile>

3 Verify that the provider VDC storage profile can provide IOPS support.

You can use providerVdcStorageProfile query as shown here, and include a filter expression that
specifies the href value of the ProviderVdcStorageProfile. Examine the iopsAllocated and
iopsCapacity attributes in the response. Values greater than 0 indicate that the provider VDC storage
profile can provide IOPS support:

GET [Link]
&filter=href==[Link]
...

<QueryResultRecords
...
<ProviderVdcStorageProfileRecord
iopsAllocated="256000"
iopsCapacity="400000"
... />
</QueryResultRecords>

4 Make a PUT request to the rel="edit" link from the AdminVdcStorageProfile you retrieved in Step 2
and supply the modified AdminVdcStorageProfile as the request body.

Supply the Vdc element as the request body.

314 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

Example: Add IOPS Support to an Organization VDC Storage Profile

This request adds IOPS support to a storage profile.

Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<AdminVdcStorageProfile
xmlns="[Link]
name="bronze"
type="application/[Link]+xml">
<Link
rel="edit"
href="[Link]
type="application/[Link]+xml" />
<Enabled>true</Enabled>
<Units>MB</Units>
<Limit>1024</Limit>
<Default>true</Default>
<IopsSettings>
<Enabled>true</Enabled>
<DiskIopsMax>4000</DiskIopsMax>
<DiskIopsDefault>1000</DiskIopsDefault>
<StorageProfileIopsLimit>200000</StorageProfileIopsLimit>
<DiskIopsPerGbMax>100</DiskIopsPerGbMax>
</IopsSettings>

<ProviderVdcStorageProfile
href="[Link]
name="Bronze"
type="application/[Link]+xml" />
</AdminVdcStorageProfile>

If the storage profile contains storage pods, this request fails with a message like this one:

BadRequestException: Storage profile n contains storage pod p. Enabing IOPS guarantee is not
supported on a storage profile containing storage pods.

This request fails with a BadRequestException if any of the following are true:

n The storage profile includes one or more storage pods.

n The storage profile includes one or more VMware Virtual SAN datastores.

n The value you specified for DiskIopsMax, DiskIopsPerGbMax, or DiskIopsDefault is not in the range
allowed by the storage profile.

The response is a Task.

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... >
...
</Task>

VMware, Inc. 315

vCloud API Programming Guide for Service Providers

Create an Edge Gateway

An Edge Gateway is a virtual router for organization VDC networks. You can configure it to provide
network services such as DHCP, firewall, NAT, static routing, VPN, and load balancing.

You can create an Edge Gateway in either a compact or a full configuration. The full configuration provides
increased capacity and performance. The compact configuration requires less memory and fewer compute
resources. All services are supported in either configuration. You can enable either configuration for high
availability, which enables automatic failover of the Edge Gateway to a backup instance that is running on a
separate virtual machine.

An Edge Gateway can support up to ten interfaces. These interfaces are categorized as uplinks when they
connect to an external network, and internal interfaces when they connect to an organization VDC network.
You must specify at least one uplink interface when you create an Edge Gateway. All uplink interfaces on an
Edge Gateway must connect to an external network available in the Provider VDC that backs the
organization VDC in which you are creating the Edge Gateway. Internal interfaces are created automatically
when you create a routed organization VDC network that connects to an Edge Gateway.

Prerequisites
n This operation is restricted to system administrators.

n An Edge Gateway requires an organization VDC backed by a Provider VDC that contains at least one
external network.

Procedure
1 Choose an organization VDC to contain the Edge Gateway.

316 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

2 Choose an external network to use for the Edge Gateway's initial uplink interface.

This external network must be one of the networks listed in the AvailableNetworks element of the
Provider VDC that backs the organization VDC in which you are creating the Edge Gateway. Follow
these steps to find a suitable external network.
a Retrieve the XML representation of the organization VDC in which you are creating the Edge
Gateway.

Use a request like this one:

GET [Link]

The ProviderVdcReference element in the response contains a reference to the Provider VDC that
backs this organization VDC.

<AdminVdc ...>
...
<ProviderVdcReference
type="application/[Link]+xml"
name="PVDC-Example"
href="[Link]
...
</AdminVdc>

b Retrieve the the XML representation of the Provider VDC.

Use a request like this one:

GET [Link]

The AvailableNetworks element in the response lists the external networks that are available to that
Provider VDC, and to all the organization VDCs that it supports.

<vmext:VMWProviderVdc ... >

...
<vcloud:AvailableNetworks>
<vcloud:Network
type="application/[Link]+xml"
name="VC1-VLAN48"
href="[Link] />
<vcloud:Network ... />
<vcloud:Network ... />
</vcloud:AvailableNetworks>
...
</vmext:VMWProviderVdc>

Choose an available external network to provide the initial interface for the new Edge Gateway. See
“Example: Create an Edge Gateway,” on page 318 for more information about criteria for choosing
an external network.

3 Create an EdgeGateway element.

In the GatewayInterfaces element, create a GatewayInterface element that defines an uplink interface.

n Specify uplink for the InterfaceType.

n Include the external network reference you retrieved in Step 2 in the Network element.

n If you plan to create a NAT service or load balancer service in the Edge Gateway, you must create
an IP sub-allocation for the uplink by including a SubnetParticipation element in the
GatewayInterface element. IP addresses in the range you specify in this element are reserved for
use by this Edge Gateway.

VMware, Inc. 317

vCloud API Programming Guide for Service Providers

For information about additional elements that an EdgeGateway can contain, see “Example: Create an
Edge Gateway,” on page 318 and the schema reference.

4 POST the EdgeGateway element to the URL for adding Edge Gateways to the organization VDC.

The server takes the requested action and returns an XML representation of the partially-created object. This
representation includes an href attribute, properties specified in the creation request, and an embedded Task
element that tracks the creation of the object. When the task completes, the object has been created, and you
can use the value of the href attribute with a GET request to retrieve the XML representation of the object.

See the response portion of “Example: Create an Edge Gateway,” on page 318.

Example: Create an Edge Gateway

This example adds an Edge Gateway to the organization VDC created in “Add a VDC to an Organization,”
on page 304. The uplink interface specifies one of the networks shown in Step 2b.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<EdgeGateway
name="theEdge"
xmlns="[Link]
<Description>Example Edge Gateway</Description>
<Configuration>
<GatewayBackingConfig>compact</GatewayBackingConfig>
<GatewayInterfaces>
<GatewayInterface>
<Name>uplink1</Name>
<DisplayName>uplink1</DisplayName>
<Network href="[Link] />
<InterfaceType>uplink</InterfaceType>
<SubnetParticipation>
<Gateway>[Link]</Gateway>
<Netmask>[Link]</Netmask>
</SubnetParticipation>
</GatewayInterface>
</GatewayInterfaces>
<HaEnabled>false</HaEnabled>
<UseDefaultRouteForDnsRelay>false</UseDefaultRouteForDnsRelay>
</Configuration>
</EdgeGateway>

The response is an EdgeGateway element with an embedded Task element that tracks the creation of the Edge
Gateway object.

The response includes a number of Link elements that you can use to manage the new Edge Gateway. It also
includes an EdgeGatewayServiceConfiguration element that contains a simple FirewallService, which drops
all incoming and outgoing packets, effectively blocking all traffic through the Edge Gateway. This service is
created by default if you do not specify an EdgeGatewayServiceConfiguration when you create the
EdgeGateway. To remove or modify it, see “Configure Edge Gateway Services,” on page 201.

318 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

Response:

<?xml version="1.0" encoding="UTF-8"?>

<EdgeGateway
xmlns="[Link]
name="theEdge"
id="urn:vcloud:gateway:2000"
href="[Link] ... >
<Link
rel="edit"
href="[Link]
type="application/[Link]+xml" />
<Link
rel="remove"
href="[Link] />
<Link
rel="up"
href="[Link]
type="application/[Link]+xml" />
<Link
rel="edgeGateway:redeploy"
href="[Link] />
<Link
rel="edgeGateway:configureServices"
href="[Link]
type="application/[Link]+xml" />
<Link
rel="edgeGateway:configureSyslogServerSettings"

href="[Link]
type="application/[Link]+xml" />
<Link
rel="edgeGateway:reapplyServices"
href="[Link] />
<Link
rel="edgeGateway:syncSyslogSettings"

href="[Link] />
<Link
rel="edgeGateway:upgrade"
href="[Link] />
<Link
rel="edgeGateway:modifyFormFactor"
href="[Link]
type="application/[Link]+xml" />
<Description>Example Edge Gateway</Description>
<Tasks>
<Task
...
operation="Creating EdgeGateway theEdge(2000)"
operationName="networkEdgeGatewayCreate"
serviceNamespace="[Link]"
... >
.
.
.

VMware, Inc. 319

vCloud API Programming Guide for Service Providers

</Task>
</Tasks>
<Configuration>
<GatewayBackingConfig>compact</GatewayBackingConfig>
<GatewayInterfaces>
<GatewayInterface>
<Network
href="[Link]
name=""
type="application/[Link]+xml" />
<InterfaceType>uplink</InterfaceType>
<SubnetParticipation>
<Gateway>[Link]</Gateway>
<Netmask>[Link]</Netmask>
<UseForDefaultRoute>false</UseForDefaultRoute>
</SubnetParticipation>
<ApplyRateLimit>false</ApplyRateLimit>
<UseForDefaultRoute>false</UseForDefaultRoute>
</GatewayInterface>
</GatewayInterfaces>
<EdgeGatewayServiceConfiguration>
<FirewallService>
<IsEnabled>true</IsEnabled>
<DefaultAction>drop</DefaultAction>
<LogDefaultAction>false</LogDefaultAction>
</FirewallService>
</EdgeGatewayServiceConfiguration>
<HaEnabled>false</HaEnabled>
<UseDefaultRouteForDnsRelay>false</UseDefaultRouteForDnsRelay>
<AdvancedNetworkingEnabled>false</AdvancedNetworkingEnabled>
</Configuration>
</EdgeGateway>

Create an Organization VDC Network With a Direct Connection

An organization VDC network with a direct connection provides direct layer 2 connectivity to machines and
networks outside of the organization VDC. Machines outside of this organization VDC can connect to
machines within the organization VDC directly.

An organization VDC network with a direct connection is configured as a child network of one of the
external networks provisioned to the cloud by the system administrator.

Prerequisites
n This operation is restricted to system administrators.

n Retrieve the list of external networks. For information about how to retrieve this list, see “External
Networks and Network Pools,” on page 201.

320 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

Procedure
1 Choose the external network to which this organization VDC network will connect.

This external network must be one of the ones listed in the AvailableNetworks element of the Provider
VDC that backs the organization VDC in which you are creating the new network. Follow these steps to
find a suitable external network.

a Retrieve the XML representation of the organization VDC in which you are creating the new
network.

Use a request like this one:

GET [Link]

The ProviderVdcReference element in the response contains a reference to the Provider VDC that
backs this organization VDC.

<AdminVdc ...>
...
<ProviderVdcReference
type="application/[Link]+xml"
name="PVDC-Example"
href="[Link]
...
</AdminVdc>

b Retrieve the the XML representation of the Provider VDC.

Use a request like this one:

GET [Link]

The AvailableNetworks element in the response lists the external networks that are available to that
Provider VDC, and to all the organization VDCs that it supports.

<vcloud:AvailableNetworks>
<vcloud:Network
type="application/[Link]+xml"
name="VC1-VLAN48"
href="[Link] />
<vcloud:Network ... />
<vcloud:Network ... />
</vcloud:AvailableNetworks>

2 Create an OrgVdcNetwork element.

a Specify the href of the external network you chose in Step 1 in the ParentNetwork element.

The type and name attributes are optional here.

b Set the FenceMode to bridged.

This creates a direct connection to the parent network.

See the request portion of “Example: Create an Organization VDC Network With a Direct Connection,”
on page 322.

3 POST the OrgVdcNetwork element you created in Step 2 to the URL for adding networks to the
organization VDC.

See the request portion of “Example: Create an Organization VDC Network With a Direct Connection,”
on page 322.

VMware, Inc. 321

vCloud API Programming Guide for Service Providers

The server takes the requested action and returns an XML representation of the partially-created object. This
representation includes an href attribute, properties specified in the creation request, and an embedded Task
element that tracks the creation of the object. When the task completes, the object has been created, and you
can use the value of the href attribute with a GET request to retrieve the XML representation of the object.

See the response portion of “Example: Create an Organization VDC Network With a Direct Connection,” on
page 322.

Example: Create an Organization VDC Network With a Direct Connection

This example adds a directly-connected network to the organization VDC created in “Add a VDC to an
Organization,” on page 304. Because the network has a Configuration whose ParentNetwork element
specifies an external network to connect to and sets the FenceMode to bridged, it provides a direct connection
to the parent network.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<OrgVdcNetwork
name="Internet"
xmlns="[Link]
<Description>Bridged to the public Internet</Description>
<Configuration>
<ParentNetwork
href="[Link] />
<FenceMode>bridged</FenceMode>
</Configuration>
</OrgVdcNetwork>

Response:

201 Created
Content-Type: application/[Link]+xml
...
<OrgVdcNetwork
xmlns="[Link]
name="Internet"
type="application/[Link]+xml"
href="[Link] ...>
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="remove"
href="[Link] />
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link] />
<Link

322 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

rel="down"
type="application/[Link]+xml"
href="[Link] />
<Description>Bridged to the public Internet</Description>
<Tasks>
<Task
name="task"
status="running"
operation="Creating Network Internet(54)"
...
</Task>
</Tasks>
<Configuration>
...
</Configuration>
<IsShares>false</IsShared>
</OrgVdcNetwork>

Creating and Managing VM-Host Affinity Rules

A vCloud Director system administrator can create groups of VMs in a resource pool, then use VM-Host
affinity rules to specify whether members of a VM group should be deployed on members of a vSphere host
DRS Group.

vCloud Director VM-Host affinity rules provide vCloud Director system administrators with a way to
specify how vSphere Distributed Resource Scheduler (DRS) should place VMs on hosts in a resource pool.
VM-Host affinity rules can be useful when host-based licensing requires VMs that are running certain
applications to be placed on hosts that are licensed to run those applications. They can also be useful when
virtual machines with workload-specific configurations require placement on hosts that have certain
characteristics. The technical white paper Best Practices for Performance Tuning of Telco and NFV Workloads in
vSphere ([Link]
provides several examples of virtual machine configurations that require specific host properties.

Affinity Rule Polarity

vCloud Director VM-Host affinity rules are user-specified constraints that the system considers during the
deployment process. There are two types, or polarities, of VM-Host affinity rules:

n A rule with a Polarity value of Affinity specifies that virtual machines in a VM group should be
deployed on a host in a host group.

n A rule with a Polarity value of Anti-Affinity specifies that virtual machines in a VM group should not
be deployed on a host in a host group.

You can make an affinity rule mandatory to specify that VM deployment must fail unless the specified
placement objective can be achieved. When a virtual machine and host are the subject of a mandatory
affinity rule, placement requirements dictated by the rule override any placement changes that might be
initiated by vSphere services such as high availability and Storage DRS.

Host Groups and Vm Groups

A vSphere VM-Host affinity rule is a rule of type Virtual Machines to Hosts, and must specify a host group
and a VM group. Before a vCloud Director system administrator can create a VM-Host affinity rule, a
vSphere administrator must create at least one host DRS group in a resource pool mapped to a
vCloud Director Provider VDC, and a vSphere administrator or vCloud Director system administrator must
create a VM group in the same resource pool. VM-Host affinity rules express an affinity in all members of a

VMware, Inc. 323

vCloud API Programming Guide for Service Providers

VM group for all hosts in a host DRS group, so all hosts in a group should share one or more characteristics
that a VM can require from a host. For example, you can group hosts on the basis of the application licenses
they carry, and group VMs on the basis of the application licenses they require. You can then create VM-
Host affinity rules that place VMs on hosts that carry the required licenses.

Because VM-Host affinity rules are properties of a resource pool, all members of groups that are subject to a
rule must be deployed in the same resource pool. If a virtual machine or host is removed from the resource
pool, the system removes it from any host group or VM group of which it is a member. The system does not
update the group when the host or VM is returned to the resource pool.

Affinity Rule Interactions and Conflicts

All VM-Host affinity rules in a resource pool have the same precedence. This configuration has implications
for how the rules interact. For example, a virtual machine that is a member of two VM groups, each of which
is named in a different required VM-Host rule, can run only on hosts that belong to both of those host
groups. When you create a VM-Host affinity rule, the system does not check for potential interactions of this
kind.

The system does check for conflicts that could arise when applying multiple mandatory rules. For example,
if you group VMs and hosts in a way that enables you to create a mandatory anti-affinity rule that applies to
a VM and a host that are members of other groups that are subject to a different mandatory affinity rule, the
system cannot apply to either rule. When two or more VM-Host affinity rules conflict in this way, the system
applies the oldest rule and disables the others. You can correct the problem by making the rules optional, or
by grouping the VMs and hosts in ways that minimize the chances of this sort of mandatory rule conflict
occurring.

Affinity Rules and vSphere Resource Management

vSphere resource management features such as DRS, vSphere HA, and vSphere DPM never take any action
that can violate a mandatory VM-Host affinity rule.

n DRS does not evacuate virtual machines to place a host in maintenance mode.

n DRS does not place virtual machines for power-on or load balance virtual machines.

n vSphere HA does not perform failovers.

n vSphere DPM does not optimize power management by placing hosts into standby mode.

To avoid these situations, be careful when you create more than one mandatory affinity rule that affects a
specific VM-host pair. Be sure that the resource pool contains enough hosts so that losing a host does not
leave the system with no host on which a VM that is governed by a rule can run. Rules that are not
mandatory can be violated to allow the proper functioning of DRS, vSphere HA, and vSphere DPM.

Create or Update a Host Group

A host group is a vSphere host DRS group. A vSphere administrator must create host DRS groups in a
resource pool mapped to a vCloud Director Provider VDC before they can be used in vCloud Director VM-
Host affinity rules.

vSphere host DRS groups created in resource pools that are mapped to a Provider VDC appear in those
resource pools and can be named in VM-Host affinity rules. For more information about host DRS groups,
see the VMware vSphere ESXi and vCenter Server Documentation.

Procedure
u Host groups are properties of a resource pool.

To retrieve the list of host groups in a resource pool, use a request like the one shown in “Example:
Host Groups in a Resource Pool,” on page 325

324 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

Example: Host Groups in a Resource Pool

The VMWProviderVdcResourcePoolSet element of a VMWProviderVdc response includes a link of this form.

<vcloud:Link
rel="down"
href="[Link]
type="application/[Link]+xml" />

You can make a GET request to this link to list all vSphere host DRS groups created in that resource pool.

Request:

GET [Link]

This response shows a single host DRS group that includes two hosts.

Response:

<?xml version="1.0" encoding="UTF-8"?>

<vmext:VMWHostGroups
xmlns:vmext="[Link]
xmlns:xsi="[Link] ... >
<vmext:HostGroup>
<vmext:HostGroupName>HostGroup-MSSQL</vmext:HostGroupName>
<vmext:Hosts type="application/[Link]+xml">
<vmext:HostReference
href="[Link]
name="ESXi37"
type="application/[Link]+xml" />
<vmext:HostReference
href="[Link]
name="ESXi39"
type="application/[Link]+xml" />
</vmext:Hosts>
</vmext:HostGroup>
</vmext:VMWHostGroups>

Create or Update a VM Group

A VM group is a collection of virtual machines with similar host requirements. The virtual machines must
all be in the same resource pool.

Prerequisites
You must be a system administrator to create or update a VM group.

Procedure
1 VM groups are properties of a resource pool.

Each VMWProviderVdcResourcePool element in a VMWProviderVdcResourcePoolSet response includes links

that you can use to create or update VM groups in the resource pool.

<?xml version="1.0" encoding="UTF-8"?>

<VMWProviderVdcResourcePoolSet ...>
...
<VMWProviderVdcResourcePool
primary="true">
<Link
rel="migrateVms"

VMware, Inc. 325

vCloud API Programming Guide for Service Providers

href="[Link] />
<Link
rel="resourcePoolVmList"
href="[Link] />
<Link
rel="down"
href="[Link]
type="application/[Link]+xml" />
<Link
rel="down"
href="[Link]
type="application/[Link]+xml" />
<Link
rel="add"
href="[Link]
type="application/[Link]+xml" />
<Link
rel="down"
href="[Link]
type="application/[Link]+xml" />
...
</VMWProviderVdcResourcePool>
...
</VMWProviderVdcResourcePoolSet>

2 To create a VM group in the resource pool, make a POST request to the add link for vmGroups.

The request body is a VMWVmGroup element. See “Example: Create a VM Group,” on page 326.

Example: Create a VM Group

The request body specifies a name for the group.

Request:

POST [Link]
Content-type: application/[Link]+xml
...
<VMWVmGroup
xmlns="[Link]
xmlns:vcloud_v1.5="[Link]
<VmGroupName>ExampleGroup</VmGroupName>
</VMWVmGroup>

The response is a Task. When the task completes, you can retrieve the vmGroups in the resource pool to see
the new VM Group. The system supplies a unique identifier and a count of VMs, initially 0, in the group.

GET [Link]
...
<vmext:VMWVmGroups ...>
<vmext:VmGroup
href="[Link]
<vcloud:Link
rel="remove"
href="[Link] />
<vcloud:Link
rel="down"

326 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

href="[Link]
type="application/[Link]+xml" />
<vcloud:Link
rel="addVms"
href="[Link]
type="application/[Link]+xml" />
<vcloud:Link
rel="removeVms"
href="[Link]
type="application/[Link]+xml" />
<vmext:VmGroupId>34</vmext:VmGroupId>
<vmext:VmGroupName>ExampleGroup</vmext:VmGroupName>
<vmext:vmCount>0</vmext:vmCount>
</vmext:VmGroup>
...
</vmext:VMWVmGroups>

Create or Update a VM-Host Affinity Rule

A VM-Host affinity rule specifies a relationship between a host group and a VM group in the same resource
pool. A system administrator can create, enable, disable or delete a VM-Host affinity rule.
After you create a VM-Host affinity rule, you can update it in the following ways:
n Enable the rule.

n Disable the rule.

n Delete the rule.

To make any other change (for example, to change the VM Group or Host Group), you must create a new
rule.

vSphere VM-Host affinity rules that are created in a resource pool that is mapped to a Provider VDC are
listed in the VMWVmHostAffinityRules element of the VMWProviderVdc response. For more information about
host DRS VM-Host affinity, see the VMware vSphere ESXi and vCenter Server Documentation.

Prerequisites
n This operation is restricted to system administrators.

n You cannot create VM-Host affinity rule in a resource pool that does not contain at least one host group
and one VM group.

Procedure
1 Choose a resource pool to contain the rule.

Each VMWProviderVdcResourcePool element in a VMWProviderVdcResourcePoolSet response contains a

link that you can use to retrieve or update the set of VM-Host affinity rules in the resource pool.

<?xml version="1.0" encoding="UTF-8"?>

<vmext:VMWProviderVdcResourcePoolSet
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
...
<vmext:VMWProviderVdcResourcePool
primary="true">
...
<vcloud:Link
rel="down"
href="[Link]

VMware, Inc. 327

vCloud API Programming Guide for Service Providers

type="application/[Link]+xml" />
<vcloud:Link
rel="down"
href="[Link]
type="application/[Link]+xml" />
<vcloud:Link
rel="add"
href="[Link]
type="application/[Link]+xml" />
<vcloud:Link
rel="add"
href="[Link]
type="application/[Link]+xml" />
<vcloud:Link
rel="down"
href="[Link]
type="application/[Link]+xml" />
...
</vmext:VMWProviderVdcResourcePool>
...
</vmext:VMWProviderVdcResourcePoolSet>

To retrieve the list of VM-Host affinity rules in a resource pool, use a request like the one shown in
“Example: Create a VM-Host Affinity Rule,” on page 328

2 Create a VMWVmHostAffinityRule element and POST it to the add link for rules in the resource pool.

See “Example: Create a VM-Host Affinity Rule,” on page 328.

Example: Create a VM-Host Affinity Rule

This example creates and enables a rule that binds the Host Group shown in “Example: Host Groups in a
Resource Pool,” on page 325 to the VM Group created in “Example: Create a VM Group,” on page 326.

Request:

POST [Link]
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:VMWVmHostAffinityRule
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
type="application/[Link]+xml">
<vcloud:Name>MSSQL-VMs</vcloud:Name>
<vcloud:IsEnabled>true</vcloud:IsEnabled>
<vcloud:IsMandatory>true</vcloud:IsMandatory>
<vcloud:Polarity>Affinity</vcloud:Polarity>
<vmext:HostGroupName>HostGroup-MSSQL</vmext:HostGroupName>
<vmext:VmGroupName>ExampleGroup</vmext:VmGroupName>
</vmext:VMWVmHostAffinityRule>

The response is a Task. When the task completes, you can make a request like this one to see the new rule
and others in this resource pool. Each rule contains links you can use to enable, disable, or delete the rule.

GET [Link]
...
<vmext:VMWVmHostAffinityRules ...>
<vcloud:Link
rel="add"

328 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

href="[Link]
type="application/[Link]+xml" />
<vmext:VmHostAffinityRule
id="85"
href="[Link]
type="application/[Link]+xml">
<vcloud:Link
rel="down"
href="[Link]
type="application/[Link]+xml" />
<vcloud:Link
rel="down"
href="[Link]
type="application/[Link]+xml" />
<vcloud:Link
rel="disable"
href="[Link] />
<vcloud:Link
rel="remove"
href="[Link] />
vcloud:Name>MSSQL-VMs</vcloud:Name>
<vcloud:IsEnabled>true</vcloud:IsEnabled>
<vcloud:IsMandatory>true</vcloud:IsMandatory>
<vcloud:Polarity>Affinity</vcloud:Polarity>
<vmext:HostGroupName>HostGroup-MSSQL</vmext:HostGroupName>
<vmext:VmGroupName>ExampleGroup</vmext:VmGroupName>
</vmext:VmHostAffinityRule>
...
<vmext:VmHostAffinityRule>
</vmext:VmHostAffinityRule>
...
<vmext:VmHostAffinityRule>
</vmext:VMWVmHostAffinityRules>

Creating and Managing VDC Templates

A VDC template specifies a configuration for an organization VDC and, optionally, an Edge Gateway and
organization VDC network. System administrators who want to enable organization administrators to create
these resources in their organization can create VDC templates and share them with those organizations.

By creating and sharing VDC templates, system administrator can enable self-service provisioning of
organization VDCs while retaining administrative control over allocation of system resources such as
Provider VDCs and external networks. Organization administrators, or any role that has rights to view and
instantiate VDC templates, use an instantiation operation to create organization VDCs from templates. See
“Create a VDC from a Template,” on page 191.

Provider VDC Specification

Although you can create a VDC template that specifies a single Provider VDC to support all organization
VDCs instantiated from that template, you can also let the system spread organization VDC load across
multiple Provider VDCs if they are present in the system. A VDC template can include multiple
ProviderVdcReference elements, each of which must be paired with an external network backed by the same

VMware, Inc. 329

vCloud API Programming Guide for Service Providers

vCenter server that backs the Provider VDC. Each time this sort of template is instantiated, the system
selects a Provider VDC and its paired network to back the organization VDC that the instantiation creates.
Selection criteria are intended to choose a Provider VDC that has the necessary CPU, memory, and storage
resources to support a new organization VDC.

Important

You cannot delete a Provider VDC, external network, storage profile, or network pool referenced in a VDC
template until the VDC template and all organization VDCs created from it are removed from the system.

Edge Gateway and Routed Network Specification

A VMWVdcTemplate element can specify the configuration of an Edge Gateway and an organization VDC
network. These objects are created in the VDC when the template is instantiated, and an organization
administrator can update them by using the workflows described in “Network Administration,” on
page 199. An organization VDC created from a template that does not include an Edge Gateway can contain
only isolated networks.

Allocation Models
Every VDC template includes a VdcTemplateSpecification element that specifies a set of properties similar
to those specified in the CreateVdcParams element that is used to create an organization VDC. See
“Example: Create an Organization VDC,” on page 306. The subtypes of VdcTemplateSpecificationType
specify one of the allocation models supported for organization VDCs. See “Create a VDC Template,” on
page 330.

Create a VDC Template

To create a VDC template, POST a VMWVdcTemplate element to the system URL for adding VDC templates.

In its simplest form, a VDC template must include references to the following objects:

n A Provider VDC

n A Provider VDC storage profile defined in that Provider VDC

When this form of VDC template is instantiated in an organization, it creates an organization VDC that has
no Edge Gateway or routed networking capability. An organization administrator can create isolated
networks in it. A system administrator can add networking capability to an organization VDC, whether or
not it was created from a template, by following the procedures documented in “Create an Edge Gateway,”
on page 316 and “Create an Organization VDC Network,” on page 212.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the vSphere platform extensions.

Use a request like this one.

GET [Link]

330 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

2 Examine the response to locate the Link element that contains the URL for adding VDC templates to the
system.

This element has a rel attribute value of add and a type attribute value of
application/[Link]+xml, as shown here:

<Link
rel="add"
href="[Link]
type="application/[Link]+xml"/>

3 Choose a provider VDC to supply resources for organization VDCs that are created by instantiating this
template.

You can use a query like this one to list all the Provider VDCs in the system.

GET [Link]

VMware, Inc. 331

vCloud API Programming Guide for Service Providers

4 Create a VMWVdcTemplate request body.

a Include a ProviderVdcReference that references the Provider VDC that you chose in Step 3.

b Include a VdcTemplateSpecification element that specifies how compute resources are allocated by
organization VDCs created from this template.
Each resource allocation model is defined in a subtype of VMWVdcTemplateSpecificationType.
Specify one of the following allocation models by setting the value of the
VdcTemplateSpecification element's type attribute as shown.

AllocationVapp <VdcTemplateSpecification
type="VMWAllocationVappVdcTemplateSpecificationType">

Specifies an AllocationVApp (Pay as you go) allocation model.

Resources are committed to the organization VDC only when vApps
are created in it. When you use this allocation model, Limit values that
you specify for Memory and CPU are ignored when you create a vApp,
and are returned as 0 when you retrieve a vApp. Resources available
to this kind of organization VDC can grow or shrink as needed when
its provider VDC has multiple resource pools.

AllocationPool <VdcTemplateSpecification
type="VMWAllocationPoolVdcTemplateSpecificationType">

Specifies an AllocationPool allocation model. Only a percentage of

the resources you allocate are committed to the organization VDC.

ReservationPool <VdcTemplateSpecification
type="VMWReservationPoolVdcTemplateSpecificationType">

Specifies a ReservationPool allocation model. 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
resources and limitations.

c Include at least one VdcStorageProfile element that specifies a ProviderVdcStorageProfile defined

in the Provider VDC you chose in Step 3.

You can use a query like this one to list all the Provider VDC storage profiles in the system. A filter
expression constrains the output to just those Provider VDC storage profiles that are associated
with a single Provider VDC, vCenter01, in this case.

GET [Link]
type=providerVdc&format=references&filter=providerVdc==vCenter01

The specified Provider VDC storage profiles are made available in organization VDCs created from
this template.

5 POST the VMWVdcTemplate request body to the system's add link for vdcTemplates.

See the request portion of “Example: Create a VDC Template,” on page 332.

The system creates the VDC template and returns a VMWVdcTemplate element that includes a set of Link
elements that you can use to access, remove, or modify the new template.

Example: Create a VDC Template

This request creates a VDC template that, when instantiated, adds an AllocationVapp VDC to an
organization. An organization VDC created by instantiating this template has many of the same properties
as the one created in “Example: Create an Organization VDC,” on page 306.

332 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

Request:

POST [Link]
Content-Type: application/[Link]+xml
<?xml version="1.0" encoding="UTF-8"?>
<vmext:VMWVdcTemplate
...
xmlns="[Link]
xmlns:vmext="[Link]
xmlns:xsi="[Link]
name="example-vdc-template">
<Description>Example AllocationVapp VDC Template without Edge Gateway</Description>
<vmext:TenantName>PayAsYouGo-VDCTemplate-no-net</vmext:TenantName>
<vmext:TenantDescription>PayAsYouGo VDC with no networking</vmext:TenantDescription>
<vmext:ProviderVdcReference
href="[Link]
name="vCenter01"
type="application/[Link]+xml" />
<vmext:VdcTemplateSpecification
xsi:type="vmext:VMWAllocationVappVdcTemplateSpecificationType">
<NicQuota>100</NicQuota>
<VmQuota>50</VmQuota>
<ProvisionedNetworkQuota>100</ProvisionedNetworkQuota>
<StorageProfile name="Bronze">
<Enabled>true</Enabled>
<Units>MB</Units>
<Limit>2097152</Limit>
<Default>true</Default>
</StorageProfile>
<vmext:ThinProvision>false</vmext:ThinProvision>
<vmext:FastProvisioningEnabled>false</vmext:FastProvisioningEnabled>
<CpuAllocationMhz>2048</CpuAllocationMhz>
<CpuLimitMhzPerVcpu>1000</CpuLimitMhzPerVcpu>
<MemoryAllocationMB>2048</MemoryAllocationMB>
<CpuGuaranteedPercentage>1</CpuGuaranteedPercentage>
<MemoryGuaranteedPercentage>1</MemoryGuaranteedPercentage>
</vmext:VdcTemplateSpecification>
</vmext:VMWVdcTemplate>

Response:

201 Created
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:VMWVdcTemplate
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
xmlns:xsi="[Link]
name="example-vdc-template" ...>
<vcloud:Link
rel="edit"
href="[Link]
type="application/[Link]+xml"/>
<vcloud:Link
rel="remove"
href="[Link]

VMware, Inc. 333

vCloud API Programming Guide for Service Providers

<vcloud:Link
rel="down"
href="[Link]
type="application/[Link]+xml"/>
<vcloud:Link
rel="controlAccess"
href="[Link]
type="application/[Link]+xml"/>
<vcloud:Link
rel="alternate"
href="[Link]
type="application/[Link]+xml"/>
<vcloud:Description>Example AllocationVapp VDC Template without Edge
Gateway</vcloud:Description>
<vmext:TenantName>PayAsYouGo-VDCTemplate-no-net</vmext:TenantName>
<vmext:TenantDescription>PayAsYouGo VDC with no networking</vmext:TenantDescription>
<vmext:ProviderVdcReference
href="[Link]
name="pvdc"
type="application/[Link]+xml"/>
<vmext:VdcTemplateSpecification
xsi:type="vmext:VMWAllocationVappVdcTemplateSpecificationType">
...
</vmext:VdcTemplateSpecification>
</vmext:VMWVdcTemplate>

Create a VDC Template That Includes Routed Networking

A VDC template can specify configurations for an Edge Gateway and organization VDC network. Each time
this kind of template is instantiated, the resulting organization VDC contains an Edge Gateway and routed
network. An organization administrator can then configure Edge Gateway services and add routed or
isolated organization VDC networks as needed.

A VDC template with routed networking must include references to the following objects:
n A Provider VDC

n A Provider VDC storage profile defined in that Provider VDC

n An external network available in that Provider VDC

n A network pool associated with that Provider VDC

When it is instantiated, this form of VDC template creates an organization VDC that includes an Edge
Gateway with a single uplink interface to the specified external network, and a single routed organization
VDC network.

Prerequisites
This operation is restricted to system administrators.

Create a VMWVdcTemplate request body. The procedure shown here adds routed networking capability to a
template like the one created in “Create a VDC Template,” on page 330.

Procedure
1 List the external networks and network pools associated with the Provider VDC referenced in the
template's ProviderVdcReference element.

Use a request like this one to retrieve the XML representation of the Provider VDC:

GET [Link]

334 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

The AvailableNetworks element in the response lists the external networks associated with that
Provider VDC. The NetworkPoolReferences element in the response lists references to all network pools
associated with that Provider VDC.

<vmext:VMWProviderVdc ... >

...
<vcloud:AvailableNetworks>
<vcloud:Network
type="application/[Link]+xml"
name="VC1-VLAN48"
href="[Link] />
<vcloud:Network ... />
<vcloud:Network ... />
</vcloud:AvailableNetworks>
...
<vcloud:NetworkPoolReferences>
<vcloud:NetworkPoolReference
type="application/[Link]+xml"
name="VC1-VXLAN"
href="[Link] />
</vcloud:NetworkPoolReferences>
</vmext:VMWProviderVdc>

2 Add a GatewayConfiguration element to the VdcTemplateSpecification.

This GatewayConfiguration must include exactly one GatewayInterface. Its Network element must
reference an external network from the list you retrieved in Step 1 and its InterfaceType must have a
value of uplink. You cannot specify a BackwardCompatibilityMode or any SubnetParticipation in this
GatewayConfiguration.

a Include a Network element that configures the initial organization VDC network for organization
VDCs created from this template

This Network must specify a FenceMode of natRouted, and cannot include any of the following
elements:

n BackwardCompatibilityMode

n EdgeGateway

n NetworkFeatures

n RouterInfo

n ServiceConfig

n SyslogServerSettings

Its IpScopes element must contain exactly one IpScope, which must have an IsInherited value of
false and an IsEnabled value of true. This IpScope cannot include any of the following elements:

n AllocatedIpAddresses

n Dns1

n Dns2

n DnsSuffix

n SubAllocations

See the request portion of “Example: Create a VDC Template That Includes Routed Networking,”
on page 336.

VMware, Inc. 335

vCloud API Programming Guide for Service Providers

3 Specify a network pool for the organization VDCs created from this template to use.

You can add a NetworkPoolReference element from the list you retrieved in Step 1 or you can add an
empty AutomaticNetworkPoolReference element to specify that organization VDCs created from this
template will use the automatically created VXLAN pool associated with the Provider VDC specified in
this template. See the request portion of “Example: Create a VDC Template That Includes Routed
Networking,” on page 336.

4 POST the VMWVdcTemplate request body to the system's add link for vdcTemplates.

See the request portion of “Example: Create a VDC Template That Includes Routed Networking,” on
page 336.

The system creates the new VDC template and returns a VMWVdcTemplate element that includes a set of Link
elements that you can use to access, remove, or modify the new template.

Example: Create a VDC Template That Includes Routed Networking

This example extends the one in “Example: Create a VDC Template,” on page 332 to create a VDC template
that, when instantiated, adds a VDC that contains an Edge Gateway and a routed organization VDC
network to the organization. An organization VDC that is created by instantiating this template has
properties similar to the one created in “Example: Create an Organization VDC,” on page 306. The Edge
Gateway and organization VDC network it contains are similar to the ones created in “Example: Create an
Edge Gateway,” on page 318 and “Create an Organization VDC Network With a Routed Connection,” on
page 213.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:VMWVdcTemplate
xmlns:vmext="[Link]
xmlns="[Link]
xmlns:xsi="[Link]
name="example-vdc-template">
<Description>Example AllocationVapp VDC Template with Gateway</Description>
<vmext:TenantName>PayAsYouGo-VDCTemplate</vmext:TenantName>
<vmext:TenantDescription>PayAsYouGo-VdcTemplate</vmext:TenantDescription>
<vmext:ProviderVdcReference
href="[Link]
name="vCenter01"
type="application/[Link]+xml"/>
<vmext:VdcTemplateSpecification
xsi:type="vmext:VMWAllocationVappVdcTemplateSpecificationType">
<NicQuota>100</NicQuota>
<VmQuota>50</VmQuota>
<ProvisionedNetworkQuota>100</ProvisionedNetworkQuota>
<GatewayConfiguration>
<Gateway name="theEdge">
<Description>Edge Gateway defined by VDC template</Description>
<Configuration>
<GatewayBackingConfig>compact</GatewayBackingConfig>
<GatewayInterfaces>
<GatewayInterface>
<Name>uplink1</Name>
<DisplayName>Uplink interface defined by VDC template</DisplayName>

336 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

<Network href="[Link]
<InterfaceType>uplink</InterfaceType>
</GatewayInterface>
</GatewayInterfaces>
<HaEnabled>false</HaEnabled>
<UseDefaultRouteForDnsRelay>false</UseDefaultRouteForDnsRelay>
</Configuration>
</Gateway>
<Network name="RoutedOVDCNet">
<Description>Routed through an Edge Gateway</Description>
<Configuration>
<IpScopes>
<IpScope>
<IsInherited>false</IsInherited>
<Gateway>[Link]</Gateway>
<Netmask>[Link]</Netmask>
<IpRanges>
<IpRange>
<StartAddress>[Link]</StartAddress>
<EndAddress>[Link]</EndAddress>
</IpRange>
</IpRanges>
</IpScope>
</IpScopes>
<FenceMode>natRouted</FenceMode>
</Configuration>
<IsShared>false</IsShared>
</Network>
</GatewayConfiguration>
<StorageProfile name="Bronze">
<Enabled>true</Enabled>
<Units>MB</Units>
<Limit>2097152</Limit>
<Default>true</Default>
</StorageProfile>
<vmext:ThinProvision>false</vmext:ThinProvision>
<vmext:FastProvisioningEnabled>false</vmext:FastProvisioningEnabled>
<vmext:NetworkPoolReference
href="[Link]
<CpuAllocationMhz>2048</CpuAllocationMhz>
<CpuLimitMhzPerVcpu>1000</CpuLimitMhzPerVcpu>
<MemoryAllocationMB>2048</MemoryAllocationMB>
<CpuGuaranteedPercentage>1</CpuGuaranteedPercentage>
<MemoryGuaranteedPercentage>1</MemoryGuaranteedPercentage>
</vmext:VdcTemplateSpecification>
</vmext:VMWVdcTemplate>

The response is similar to the one shown in “Example: Create a VDC Template,” on page 332.

VMware, Inc. 337

vCloud API Programming Guide for Service Providers

Create a VDC Template That Includes Routed Networking and Multiple Provider
VDCs
If the system includes more than one Provider VDC, and at least two of those Provider VDCs use a common
set of storage profiles, a VMWVdcTemplate in that system can include multiple ProviderVdcReference elements.
Each time this sort of template is instantiated, the system evaluates the current resource commitments of
each of the referenced Provider VDCs and chooses the one best able to support a new organization VDC.

A VDC template that includes routed networking and specifies multiple Provider VDCs must include
references to the following objects:

n Two or more candidate Provider VDCs that share at least one storage profile. Each of the Provider
VDCs must have at least one available external network.

n A reference to a Provider VDC storage profile defined in all candidate Provider VDCs

n A network pool specification.

When this form of VDC template is instantiated, it creates an organization VDC that is backed by one of the
candidate Provider VDCs.

Note When you specify multiple Provider VDCs in a template that includes networking, you must also
add a Binding element to each ProviderVdcReference. A Binding associates a symbolic name with an
external network in the Provider VDC. You use this symbolic name as the value of the href attribute of the
Network configured in the template. When the template is instantiated, the system replaces the symbolic
name with a reference to the network specified in the Value element of the Binding.

Prerequisites
This operation is restricted to system administrators.

Use a procedure like the one shown in “Create a VDC Template,” on page 330 or “Create a VDC Template
That Includes Routed Networking,” on page 334 to create a VMWVdcTemplate request body. You can specify
multiple Provider VDCs in a VDC template whether or not the template includes routed networking. The
procedure shown here adds another Provider VDC to the template shown in “Example: Create a VDC
Template That Includes Routed Networking,” on page 336.

Procedure
1 List the Provider VDCs that exist in the system.
You can use a query like this one to list all the Provider VDCs in the system.

GET [Link]

2 List the external networks and network pools available in each Provider VDCto specify in this VDC
template.

Use a request like this one to retrieve the XML representation of the Provider VDC:

GET [Link]

The AvailableNetworks element in the response lists the external networks created in that Provider
VDC. The NetworkPoolReferences element in the response lists references to all network pools created
in that Provider VDC.

<vmext:VMWProviderVdc ... >

...
<vcloud:AvailableNetworks>
<vcloud:Network
type="application/[Link]+xml"
name="VC1-VLAN48"

338 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

href="[Link] />
<vcloud:Network ... />
<vcloud:Network ... />
</vcloud:AvailableNetworks>
...
<vcloud:NetworkPoolReferences>
<vcloud:NetworkPoolReference
type="application/[Link]+xml"
name="VC1-VXLAN"
href="[Link] />
</vcloud:NetworkPoolReferences>
</vmext:VMWProviderVdc>

3 For each Provider VDC that you include in this template, create a ProviderVdcReference that references
the Provider VDC and includes a Binding element that references an external network available in that
Provider VDC.

4 POST the VMWVdcTemplate request body to the system's add link for vdcTemplates.

See the request portion of “Example: Create a VDC Template With Routed Networking and Multiple
Provider VDCs,” on page 339.

The system creates the new VDC template and returns a VMWVdcTemplate element that includes a set of Link
elements that you can use to access, remove, or modify the new template.

Example: Create a VDC Template With Routed Networking and Multiple Provider
VDCs
This request creates a VDC template that is identical to the one shown in “Example: Create a VDC Template
That Includes Routed Networking,” on page 336, but adds a second ProviderVdcReference and includes
Binding elements that provide symbolic references to external networks.

The Binding element in each ProviderVdcReference pairs a Name element that contains a user-specified
identifier in URN format with a Value element that specifies the href of an external network in the candidate
Provider VDC. The GatewayConfiguration of the template uses that URN instead of a URL for the href
attribute of its Network element.

<Network href="urn:vcloud:binding:35c80ae2-36ef-4e2f-a430-ca704db9709f"/>

When the template is instantiated, this URN is replaced by the network URL in the Value part of the Binding
associated with the ProviderVdcReference that the system selects during instantiation.

This example also uses the AutomaticNetworkPoolReference flag to specify that organization VDCs created
by instantiating this template use the VXLAN network pool that was created automatically when the
Provider VDC was created. If you decide not to use AutomaticNetworkPoolReference in a VDC template that
specifies multiple Provider VDCs, you must specify a network pool that exists in one of the candidate
Provider VDCs. All organization VDCs that are created from this template use that pool, regardless of the
Provider VDC that is chosen during instantiation.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:VMWVdcTemplate
xmlns:vmext="[Link]
xmlns="[Link]

VMware, Inc. 339

vCloud API Programming Guide for Service Providers

xmlns:xsi="[Link]
name="example-vdc-template-2PVDCs">
<Description>Example AllocationVapp VDC Template with Gateway</Description>
<vmext:TenantName>PayAsYouGo-VDCTemplate</vmext:TenantName>
<vmext:TenantDescription>PayAsYouGo-VdcTemplate</vmext:TenantDescription>
<vmext:ProviderVdcReference
href="[Link]
name="vCenter01"
type="application/[Link]+xml">
<vmext:Binding>
<vmext:Name>urn:vcloud:network:35c80ae2-36ef-4e2f-a430-ca704db9709f</vmext:Name>
<vmext:Value href="[Link]
</vmext:Binding>
</vmext:ProviderVdcReference>
<vmext:ProviderVdcReference
href="[Link]
name="vCenter02"
type="application/[Link]+xml">
<vmext:Binding>
<vmext:Name>urn:vcloud:network:35c80ae2-36ef-4e2f-a430-ca704db9709f</vmext:Name>
<vmext:Value href="[Link]
</vmext:Binding>
</vmext:ProviderVdcReference>
<vmext:VdcTemplateSpecification
xsi:type="vmext:VMWAllocationVappVdcTemplateSpecificationType">
<NicQuota>100</NicQuota>
<VmQuota>50</VmQuota>
<ProvisionedNetworkQuota>100</ProvisionedNetworkQuota>
<GatewayConfiguration>
<Gateway name="theEdge">
<Description>Edge Gateway defined by VDC template</Description>
<Configuration>
<GatewayBackingConfig>compact</GatewayBackingConfig>
<GatewayInterfaces>
<GatewayInterface>
<Name>uplink1</Name>
<DisplayName>Uplink interface defined by VDC template</DisplayName>
<Network
href="urn:vcloud:binding:35c80ae2-36ef-4e2f-a430-ca704db9709f"/>
<InterfaceType>uplink</InterfaceType>
</GatewayInterface>
</GatewayInterfaces>
<HaEnabled>false</HaEnabled>
<UseDefaultRouteForDnsRelay>false</UseDefaultRouteForDnsRelay>
</Configuration>
</Gateway>
<Network name="RoutedOVDCNet">
<Description>Routed through an Edge Gateway</Description>
<Configuration>
<IpScopes>
<IpScope>
<IsInherited>false</IsInherited>
<Gateway>[Link]</Gateway>
<Netmask>[Link]</Netmask>
<IpRanges>

340 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

<IpRange>
<StartAddress>[Link]</StartAddress>
<EndAddress>[Link]</EndAddress>
</IpRange>
</IpRanges>
</IpScope>
</IpScopes>
<FenceMode>natRouted</FenceMode>
</Configuration>
<IsShared>false</IsShared>
</Network>
</GatewayConfiguration>
<StorageProfile name="Bronze">
<Enabled>true</Enabled>
<Units>MB</Units>
<Limit>2097152</Limit>
<Default>true</Default>
</StorageProfile>
<vmext:ThinProvision>false</vmext:ThinProvision>
<vmext:FastProvisioningEnabled>false</vmext:FastProvisioningEnabled>
<vmext:AutomaticNetworkPoolReference/>
<CpuAllocationMhz>2048</CpuAllocationMhz>
<CpuLimitMhzPerVcpu>1000</CpuLimitMhzPerVcpu>
<MemoryAllocationMB>2048</MemoryAllocationMB>
<CpuGuaranteedPercentage>1</CpuGuaranteedPercentage>
<MemoryGuaranteedPercentage>1</MemoryGuaranteedPercentage>
</vmext:VdcTemplateSpecification>
</vmext:VMWVdcTemplate>

Controlling Access to VDC Templates

Upon creation, a VDC template is not accessible to any organization in the system. To enable organizations
to create VDCs from a template, a system administrator must use the vCloud API access control mechanism
to grant those organizations ReadOnly access to the template, and must also grant organization members
rights to view and instantiate VDC templates.

A system administrator can make a request similar to the ones described in “Controlling Access to vApps
and Catalogs,” on page 91 to control access to VDC templates.

Important The rights to view and instantiate VDC templates are restricted to the system administrator by
default. The system administrator must explicitly grant those rights to organization members or roles to
enable use of VDC templates in an organization.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the VDC template to find its controlAccess link.

Use a request like this one:

GET [Link]

VMware, Inc. 341

vCloud API Programming Guide for Service Providers

The controlAccess link has the following form:

<vcloud:Link
rel="controlAccess"
href="[Link]
type="application/[Link]+xml"/>

2 Create a ControlAccessParams request body that grants ReadOnly access to the organizations that you
want to have access to the template .

The only AccessLevel that you can grant for a VdcTemplate is ReadOnly. You cannot set
IsSharedToEveryone to true.

3 POST the ControlAccessParams request body to the link you retrieved in Step 1.

A link to the specified VDC template is returned in the vdcTemplates list of those organizations to which
access was granted. See “Create a VDC from a Template,” on page 191

Example: Grant Access to a VDC Template

This request grants access to a VDC template to two organizations.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<ControlAccessParams
xmlns:vmext="[Link]
xmlns="[Link]
<IsSharedToEveryone>false</IsSharedToEveryone>
<AccessSettings>
<AccessSetting>
<Subject href="[Link]
<AccessLevel>ReadOnly</AccessLevel>
</AccessSetting>
<AccessSetting>
<Subject href="[Link]
<AccessLevel>ReadOnly</AccessLevel>
</AccessSetting>
</AccessSettings>
</ControlAccessParams>

The response is a ControlAccessParams element.

Response:

200 OK
Content-Type: application/[Link]+xml
...
<ControlAccessParams
xmlns:vmext="[Link]
xmlns="[Link] \>
...
</ControlAccessParams>

342 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

Import a Virtual Machine from vCenter

A system administrator can import virtual machines from the inventory of any vCenter server registered to
vCloud Director. You can import the virtual machines to any VDC in a cloud, and you can import them in
vApp or vApp template form.

When you import a virtual machine from vCenter, you must specify the following items:

n A target VDC to receive the import.

n A form for the imported virtual machine to take. Choose vApp or vApp template.

n Whether to remove the source virtual machine from vCenter inventory after the import is complete.

Prerequisites
n This operation is restricted to system administrators.

n Identify the virtual machine to import. See “Retrieve a List of Virtual Machines from a vCenter Server,”
on page 276.

Procedure
1 Choose whether to import the virtual machine as a vApp or vApp template.

The VimServer element that represents the vCenter server from which you import the virtual machine
contains two links that import virtual machines. One has the following form, and imports the virtual
machine as a vApp.

<vcloud:Link
rel="add"
type="application/[Link]+xml"
href="[Link] />

The other has the following form, and imports the virtual machine as a vApp template.

<vcloud:Link
rel="add"
type="application/[Link]+xml"

href="[Link] />

2 (Optional) If you plan to import the virtual machine as a vApp template, identify a catalog where you
want to place a reference to the template.

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 of the VimServer that manages the virtual machine.

Prerequisites
n This operation is restricted to system administrators.

n Identify the virtual machine to import. See “Retrieve a List of Virtual Machines from a vCenter Server,”
on page 276.

Procedure
1 Create an ImportVmAsVAppParams element that specifies the VmMoRef of the source virtual machine and a
target VDC to hold the imported vApp.

2 POST the ImportVmAsVAppParams element to the importVmAsVApp link of the source vCenter server.

VMware, Inc. 343

vCloud API Programming Guide for Service Providers

Example: Import a Virtual Machine as a vApp

This example imports one of the virtual machines shown in the response portion of “Example: Retrieve a
List of Virtual Machines from a vCenter Server,” on page 276. The request body is an ImportVmAsVAppParams
element whose sourceMove attribute specifies that the source virtual machine should remain in vCenter
inventory after the import is complete. The request body includes the href of the VDC that receives the
import and a VmMoRef element that contains the managed object reference of the virtual machine to import.
The response is an unresolved vApp body that contains a Task that tracks the import.

Request:

POST [Link]
Content-type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<ImportVmAsVAppParams
xmlns="[Link]
name="ImportedWin2K8"
sourceMove="false">
<VmMoRef>vm-43</VmMoRef>
<Vdc
href="[Link] />
</ImportVmAsVAppParams>

Response:

201 Created
Content-Type: application/[Link]+xml
...
<VApp ...
status="0"
name="ImportedWin2K8"
type="application/[Link]+xml"
href="[Link] ... >
...
<Description />
<Tasks>
<Task
operation=”Busy Virtual Application Win2K8 ”>
...
</Task>
</Tasks>
</VApp>

Import a Virtual Machine as a vApp Template

To import a virtual machine as a vApp template, a system administrator can make a request to the
importVmAsVAppTemplate link of the VimServer that manages the virtual machine.

Prerequisites
n This operation is restricted to system administrators.

n Identify the virtual machine to import. See “Retrieve a List of Virtual Machines from a vCenter Server,”
on page 276.

344 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

Procedure
1 Create an ImportVmAsVAppTemplateParams element that specifies the VmMoRef of the source virtual
machine, a target VDC to hold the imported vApp template, and an optional catalog where you want to
place a reference to the template.
2 POST the ImportVmAsVAppTemplateParams element to the importVmAsVAppTemplate link of the source
vCenter server.

Example: Import a Virtual Machine as a vApp Template

This example imports one of the virtual machines shown in the response portion of “Example: Retrieve a
List of Virtual Machines from a vCenter Server,” on page 276 as a vApp template. The request body is an
ImportVmAsVAppTemplateParams element whose sourceMove attribute specifies that the source virtual machine
should remain in vCenter inventory after the import is complete. The request body includes the href of the
VDC that receives the import, a VmMoRef element that contains the managed object reference of the virtual
machine to import, and a Catalog element that references the catalog to which the imported template should
be added. The response is an unresolved VAppTemplate body that contains a Task that tracks the import.

Request:

POST [Link]
Content-type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<ImportVmAsVAppTemplateParams
xmlns="[Link]
name="ImportedWin2K8"
sourceMove="false">
<VmMoRef>vm-43</VmMoRef>
<Vdc
href="[Link] />
<Catalog
href="[Link] />
</ImportVmAsVAppTemplateParams>

Response:

201 Created
Content-Type: application/[Link]+xml
...
<VAppTemplate ...
status="0"
name="ImportedWin2K8"
type="application/[Link]+xml"
href="[Link] ... >
...
<Description />
<Tasks>
<Task
operation=”Busy Virtual Application Template Win2K8 ”>
...
</Task>
</Tasks>
</VAppTemplate>

VMware, Inc. 345

vCloud API Programming Guide for Service Providers

Relocate a Virtual Machine to a Different Datastore

If the datastore that contains a virtual machine has been disabled by the system administrator or is no longer
associated with virtual machine's designated storage profile, you must update the Vm element that represents
the virtual machine. That update revalidates the storage profile and relocates the virtual machine if
necessary.

Every Vm element includes a StorageProfile element. The value of the href attribute of that element is a
reference to the virtual machine's storage profile. The initial value of this attribute is inherited from the VDC
that contains it unless you specify the value when the virtual machine is created. To change the value, you
must update the entire Vm element that contains it.

Note When the system administrator changes the datastore that stores a virtual machine, you must update
the Vm element as shown in “Example: Update the Storage Profile for a Virtual Machine,” on page 176, but
leave the href of the current StorageProfile unchanged. This action, which replaces the deprecated
relocate action, forces revalidation of the existing storage profile. If the current datastore is disabled or no
longer supports the specified storage profile, the system relocates the virtual machine to a different
datastore that supports the referenced storage profile. After the returned Task completes, the validation and,
if necessary, relocation is complete.

Prerequisites
Verify that you are logged in to the vCloud API as an administrator or the object owner.

Procedure
1 Retrieve the Vm element.

Make a GET request to the URL in the value of the href attribute of the Vm.

2 Modify the retrieved Vm to change the StorageProfile reference.

Request bodies must contain all required elements and attributes, even if you are not changing their
values. Because optional elements and attributes typically revert to default values if they are omitted or
empty, it is a best practice to include optional elements in request bodies that modify existing objects.
Link elements and href attributes from responses do not need to be included in modified sections. Some
elements and attributes are read-only and cannot be modified. See the schema reference for details.

3 Update the Vm with your modifications.

a Find the Link element in the Vm where rel="edit".

b Make a PUT request to the URL in that link's href attribute value, and supply the modified Vm as
the request body.

The response to this request is a Task element that tracks the relocation of the virtual machine to a
datastore in the new storage profile. When the task is complete, the virtual machine has been relocated.

Example: Update the Storage Profile for a Virtual Machine

This example shows a Vm element containing a StorageProfile. The actual update operation requires the
entire Vm element, including the StorageProfile, in the request body. Only a small part of the element
appears in this example.

Request:

PUT [Link]
Content-type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Vm ...>

346 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

...
<StorageProfile
type="application/[Link]+xml"
name="Gold"
href="[Link] />

</Vm>

Response:

202 Accepted
Content-Type: application/[Link]+xml
...
<Task ... operation="Updating Virtual Application Linux FTP server (7)" ...>
...
</Task>

Configure the vCloud Director AMQP Service

The vCloud Director AMQP service is used by system notifications, object extensions, and extension
services. The system administrator can enable or disable this service and configure settings that the service
uses when it sends notifications or messages generated by extensions.

AMQP, the Advanced Message Queuing Protocol, is an open standard for message queuing that supports
flexible messaging for enterprise systems. vCloud Director includes an AMQP service and defines a set of
events that, when notifications are enabled, trigger publication of messages by this service.

By default, the vCloud Director AMQP service sends unencrypted messages. If you configure it to encrypt
these messages using SSL, it verifies the broker's certificate by using the default JCEKS trust store of the Java
runtime environment on the vCloud Director cell, typically located in the cell's
$VCLOUD_HOME/jre/lib/security/cacerts directory.

To use SSL with the vCloud Director AMQP service, select Use SSL on the AMQP Broker Settings section of
the Extensibility page of the vCloud Director Web console, and provide either of the following:

n an SSL certificate pathname

n a JCEKS trust store pathname and password

If you do not need to validate the AMQP broker's certificate, you can select Accept all certificates.

For more information about AMQP, see [Link]

AMQP broker settings are established when you install and configure RabbitMQ or another AMQP broker
to use with vCloud Director. These values include the following items:

n The fully-qualified domain name of the RabbitMQ server host, for example [Link].

n A username and password that are valid for authenticating with RabbitMQ.

n The port at which the broker listens for messages. The default is 5672.

n The RabbitMQ virtual host. The default is "/".

Note It is a good practice to test the AMQP settings before you change the configuration. See “Test AMQP
Settings,” on page 349.

Prerequisites
This operation is restricted to system administrators.

VMware, Inc. 347

vCloud API Programming Guide for Service Providers

Procedure
1 Retrieve the SystemSettings element.

2 Examine the response to locate the link that you can use to retrieve the system's AmqpSettings element.

This link has a rel attribute value of down and a type attribute value of
application/[Link]+xml, as shown here:

<Link href="[Link]
rel="down"
type="application/[Link]+xml"/>

3 Review or modify system AMQP settings.

a Retrieve the AmqpSettings element.

Make a GET request to the href value of the application/[Link]+xml link

described in Step 2.

b Modify the contents of this element as necessary.

See the schema reference for details of element contents.

c Update the modified element with the new contents.

PUT the modified element to the href value of its rel="edit" link. See “Example: Update AMQP
Settings,” on page 348

Example: Update AMQP Settings

This request modifies the AMQP settings for a cloud to require the use of SSL for AMQP connections. It also
overrides the default value for AmqpPrefix, vcd, with a new value, myCloud.

Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<AmqpSettings
xmlns="[Link]
<AmqpHost />
<AmqpPort>5672</AmqpPort>
<AmqpUsername>guest</AmqpUsername>
<AmqpPassword>Pa55w0rd</AmqpPassword>
<AmqpExchange>systemExchange</AmqpExchange>
<AmqpVHost>/</AmqpVHost>
<AmqpUseSSL>true</AmqpUseSSL>
<AmqpSslAcceptAll>false</vmext:AmqpSslAcceptAll>
<AmqpPrefix>myCloud</vmext:AmqpPrefix>
</AmqpSettings>

The response includes information supplied in the request, and contains a number of Link elements inserted
by the server. The value of AmqpPassword, which you must supply when you modify AmqpSettings (even if
you are not changing its value), is never returned when you retrieve AmqpSettings.

Response:

200 OK
Content-Type: application/[Link]+xml
...
<AmqpSettings

348 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

xmlns="[Link]
type="application/[Link]+xml"
href="[Link]
... >
<vcloud:Link
rel="test"
type="application/[Link]+xml"
href="[Link]
<vcloud:Link
rel="certificate:update"
type="application/[Link]+xml"

href="[Link]
/>
<vcloud:Link
rel="certificate:reset"

href="[Link]
/>
<vcloud:Link
rel="truststore:update"
type="application/[Link]+xml"

href="[Link]
/>
<vcloud:Link
rel="truststore:reset"

href="[Link] />

<AmqpHost />
<AmqpPort>5672</AmqpPort>
<AmqpUsername>guest</AmqpUsername>
<AmqpPassword />
<AmqpExchange>systemExchange</AmqpExchange>
<AmqpVHost>/</AmqpVHost>
<AmqpUseSSL>true</AmqpUseSSL>
<AmqpSslAcceptAll>false</vmext:AmqpSslAcceptAll>
<AmqpPrefix>myCloud</vmext:AmqpPrefix>
</AmqpSettings>

Note Link elements in the response are created by the server. See “System Truststore and Keytab
Maintenance,” on page 351 for information about using the action links in this section to manage the AMQP
service SSL certificates and truststore. The system must have a valid AMQP certificate and truststore to use
the secure sockets layer (https).

Test AMQP Settings

The settings/amqp/action/test link of the AmqpSettings element allows you to test AMQP settings before
configuring them for the cloud.

Prerequisites
n This operation is restricted to system administrators.

n Verify that you know the AMQP broker password.

VMware, Inc. 349

vCloud API Programming Guide for Service Providers

n Retrieve the SystemSettings element. See “Retrieve or Update System Settings,” on page 268.

Procedure
1 Examine the SystemSettings element to locate the link that you can use to retrieve the system's
AmqpSettings element.

This link has a rel attribute value of down and a type attribute value of
application/[Link]+xml as shown here:

<Link href="[Link]
rel="down"
type="application/[Link]+xml"/>

2 Retrieve the AmqpSettings element and locate the settings/amqp/action/test link it contains.

The response portion of “Example: Update AMQP Settings,” on page 348 includes this link.

3 Create a new AmqpSettings element that contains the values you want to test.

You can use the existing AmqpSettings element as a template. Whether you want to test the existing
values or create new ones, you must include the AMQP broker password in the AmqpPassword element.
This element is always returned empty when you retrieve the system's AmqpSettings.

4 Test the AMQP settings.

POST the AmqpSettings element to the settings/amqp/action/test link described in Step 2.

Example: Test AMQP Settings

This example tests the settings shown in the request portion of “Example: Update AMQP Settings,” on
page 348

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<AmqpSettings
xmlns="[Link]
type="application/[Link]+xml">
<AmqpHost />
<AmqpPort>5672</AmqpPort>
<AmqpUsername>guest</AmqpUsername>
<AmqpPassword>Pa55w0rd</AmqpPassword>
<AmqpExchange>systemExchange</AmqpExchange>
<AmqpVHost>/</AmqpVHost>
<AmqpUseSSL>true</AmqpUseSSL>
<AmqpSslAcceptAll>false</vmext:AmqpSslAcceptAll>
<AmqpPrefix>myCloud</vmext:AmqpPrefix>
</AmqpSettings>

The response is an AmqpSettingsTest element whose Valid element contains a Boolean indication of whether
the settings are valid. This response indicates that they are. If a value in the POSTed AmqpSettings element is
incorrect, the AmqpSettingsTest response has a Valid value of false.

Response:

200 OK
Content-Type: application/[Link]+xml
...
<vmext:AmqpSettingsTest

350 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

xmlns:vmext="[Link]
xmlns:vcloud="[Link]
type="application/[Link]+xml"
href="[Link]
... >
<vcloud:Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<vmext:Valid>true</vmext:Valid>
</vmext:AmqpSettingsTest>

System Truststore and Keytab Maintenance

You can use the vCloud API to upload and manage SSL certificates, keystores, and Kerberos keytabs for the
system LDAP and AMQP services. You can also use the vCloud API to configure SSPI, the Microsoft
Security Support Provider Interface, for use with Active Directory.

Valid SSL certificates and truststores are required if the system LDAP and AMQP services use the secure
sockets layer (https).

The SystemSettings element contains several elements that enable the system administrator to maintain
certificates and truststores for the system LDAP and AMQP services. Links in the LdapSettings element
allow the system administrator to manage the system LDAP truststore and keystore.

<SystemSettings ... >

...
<LdapSettings ... >
...
<vcloud:Link
rel="certificate:update"

href="[Link]
ficate"
type="application/[Link]+xml"/>
<vcloud:Link
rel="certificate:reset"

href="[Link]
icate"/>
<vcloud:Link
rel="keystore:update"

href="[Link]
ore"
type="application/[Link]+xml"/>
<vcloud:Link
rel="keystore:reset"

href="[Link]
re"/>
<vcloud:Link
rel="keytab:update"

href="[Link]
eytab"
type="application/[Link]+xml"/>

VMware, Inc. 351

vCloud API Programming Guide for Service Providers

<vcloud:Link
rel="keytab:reset"

href="[Link]
ytab"/>
...
</LdapSettings>
...
</SystemSettings>

The AmqpSettings element includes links that allow the system administrator to manage the system AMQP
truststore and certificate.

<SystemSettings ... >

...
<AmqpSettings>
...
<vcloud:Link
rel="certificate:update"

href="[Link]
type="application/[Link]+xml"/>
<vcloud:Link
rel="certificate:reset"

href="[Link]
<vcloud:Link
rel="truststore:update"

href="[Link]
type="application/[Link]+xml"/>
<vcloud:Link
rel="truststore:reset"

href="[Link]
...
</AmqpSettings>
...
</SystemSettings>

All of these links implement similar operations. They either upload a new certificate, keytab, or keystore, or
reset or remove an existing one. vCloud Director imposes limits on upload sizes.

Table 8‑2. Truststore, Certificate, and Keytab Upload Limits

Upload Type Maximum Size in Megabytes

vCenter truststore 10

LDAP certificate 2

LDAP keystore 2

LDAP SSPI keytab 2

AMQP certificate 2

AMQP truststore 10

352 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Determine whether the request requires a body.

Requests whose rel value includes the string reset do not require a body. For details about other
request bodies, see the schema reference.

2 POST the request to the request URL.

Include the request body if one is required.

3 Take any action that the response requires.

The response to an update request includes an uploadLocation parameter whose value is a URL to
which you can upload the certificate, keytab, or keystore with a PUT request. Requests whose rel value
includes the string reset return a No Content response and require no further action.

Example: Upload an SSL Certificate for the System LDAP Service

This example uploads an SSL certificate whose size is 892 bytes. The first step obtains an upload URL by
POSTing a CertificateUpdateParams element to the organization's
settings/ldap/action/updateLdapCertificate URL.

Request:

POST: [Link]
Content-type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<CertificateUpdateParams
fileSize="892"
xmlns="[Link]
</CertificateUpdateParams>

The response contains an uploadLocation parameter whose value is a URL to which you can upload the
certificate.

Response:

<CertificateUploadSocket
xmlns="[Link]
uploadLocation="[Link]
<Task
...
status="running"
operation="Updating LDAP certificate"
...
</Task>
</CertificateUploadSocket>

To upload the certificate, make a PUT request to the uploadLocation URL and supply the certificate in the
request body.

VMware, Inc. 353

vCloud API Programming Guide for Service Providers

Request:

PUT [Link]
Content-length: 892
...serialized contents of certificate...

EOF

Response:

200 OK

Retrieve the vSphere URL of an Object

If you know the VimObjectType and MoRef of an object represented in the vCloud API, you can use that
information to retrieve a URL that you can use to access the object with the vSphere Web Client.

Using the vSphere Web Client to examine an object vCloud Director uses can help a system administrator
diagnose problems with resource consumption and allocation. To retrieve the vSphere URL of an object, you
must construct a request URL in the following format.

API-URL/admin/extension/vimServer/id/vimObjType/vimObjMoref/vSphereWebClientUrl

n API-URL is a URL of the form [Link]

n id is a unique identifier in the form of a UUID, as defined by RFC 4122. The vimServer object that has
this id must be the one that hosts the object that vimObjType and vimObjMoref identify.

n vimObjType is the vSphere object type, expressed as one of the following strings:

n CLUSTER_COMPUTE_RESOURCE

n DATASTORE

n DATASTORE_CLUSTER

n DV_PORTGROUP

n DV_SWITCH

n FOLDER

n HOST

n NETWORK

n RESOURCE_POOL

n STORAGE_PROFILE (available from vCenter 5.1 and later)

n VIRTUAL_MACHINE

n vimObjMoref is the vSphere managed object reference of the object, as returned by the vCloud API.

For an example request URL, see the request portion of “Example: Retrieve the vSphere URL of a Resource
Pool,” on page 355. All of the information you need to construct the URL is available when you retrieve the
XML representation of any of the supported object types. See “Example: Retrieve a Resource Pool Set,” on
page 291, “Example: Retrieve a List of Available Portgroups and Switches from a vCenter Server,” on
page 274, and “Example: Retrieve a List of Storage Profiles from a vCenter Server,” on page 278.

Note See “Mapping a vCloud Director Object to a vSphere Object,” on page 355 for a list of
vCloud Director objects and corresponding vSphere objects.

Prerequisites
This operation is restricted to system administrators.

354 VMware, Inc.

Chapter 8 Managing and Monitoring a Cloud

Verify that the vSphere Web Client URL is enabled for all vCenter servers from which you want to retrieve
the vSphere URL of an object. You can manage this feature on the General tab of the vCenter Properties
page of the vCloud Director Web console.

Procedure
1 Retrieve the VimObjectType and MoRef elements of the object, and the VimServerRef element of the
vSphere server that hosts the object.

2 Construct a request URL that includes the VimServerRef, VimObjectType, and MoRef elements.

You can use the value of the href attribute of the VimServerRef element as the vimServer/id part of the
request URL.

3 Make a GET request to the URL you constructed in Step 2.

The response contains a URL you can use with the vSphere Web Client. See “Example: Retrieve the
vSphere URL of a Resource Pool,” on page 355.

Example: Retrieve the vSphere URL of a Resource Pool

This request retrieves the vSphere URL of one of the resource pools referenced in “Example: Retrieve a
Resource Pool Set,” on page 291.

Request:

GET
[Link]
lientUrl

Response:

<?xml version="1.0" encoding="UTF-8"?>

<vmext:VSphereWebClientUrl
xmlns:vmext="[Link]
...>
<vmext:URL>[Link]
</vmext:URL>
</vmext:VSphereWebClientUrl>

Use the URL that the vmext:URL element contains to access the object with the vSphere Web Client. The URL
is truncated in this example.

Mapping a vCloud Director Object to a vSphere Object

When using the vSphere Web Client to examine a vCloud Director object, you can use this table to map the
object to its representation in vSphere.

Table 8‑3. Mapping a vCloud Director Object to a vSphere Object

vCloud Director Object vSphere Object

Provider VDC:Hosts Host

Provider VDC:Datastores Datastore

Provider VDC:Storage Profiles Storage Profile

Provider VDC:External Network (portgroup-backed) Standard virtual switch

Provider VDC:External Network(VLAN-backed) Distributed virtual switch

Provider VDC:Resource Pool (root resource pool or Cluster

Cluster)

Provider VDC:Resource Pool (sub-resource pool only) Resource Pool

VMware, Inc. 355

vCloud API Programming Guide for Service Providers

Table 8‑3. Mapping a vCloud Director Object to a vSphere Object (Continued)

vCloud Director Object vSphere Object

External Network (Portgroup-backed) Standard virtual switch

Direct Org VDC Networks (Portgroup) Standard virtual switch

External Network (VLAN-backed) Distributed virtual switch

Direct Org VDC Networks (VLAN) Distributed virtual switch

Network Pool (VLAN-backed) Distributed virtual switch

Network Pools (Portgroup-backed) Standard virtual switch

vCenter vCenter Server

Resource Pool (root resource pool or Cluster) Cluster

Resource Pool (sub-resource pool only) Resource Pool

Host Host

Datastores Datastore

Datastore Clusters Datastore Cluster

Storage Profiles N/A

vDSwitch Distributed virtual switch

Port Group Standard virtual switch

Home:vApp Folder

vApp Folder

vApp:vApp Diagram Folder

vApp:vApp Diagram:VM VM

vApp:VM List:VM VM

vApp:Networking:vApp Networks Distributed Port Group

VM VM

Expired Items:vApps Folder

Expired Items:vApp Templates Folder

Catalog:vApp Template Folder

Catalog:vApp Template:VM VM

Catalog:vApp Template:Shadow VMs VM

Organization VDC:vApp Folder

Organization VDC:vApp Template Folder

Organization VDC:Storage Profiles Storage Profile

Organization VDC:Org VDC Networks (VLAN-backed) Distributed virtual switch

Organization VDC:Org VDC Networks (Portgroup-backed) Standard virtual switch

Organization VDC:Resource Pools (root resource pool or Cluster

Cluster)

Organization VDC:Resource Pools (sub-resource pool only) Resource Pool

356 VMware, Inc.

Working With Object Metadata 9
The vCloud API provides a general-purpose facility for associating user-defined metadata with an object.
An administrator or object owner can use the metadata link in the object's representation to access an object's
metadata.

Object metadata gives cloud operators and tenants a flexible way to associate user-defined properties
(name=value pairs) with objects. Object metadata is preserved when objects are copied, and can be included
in query filter expressions (see “Add a Metadata Filter to a Query,” on page 379).

vCloud API Object Metadata Links

The representation of any object that supports metadata includes a link that you can use to retrieve the
object's Metadata element. This example shows the metadata link from a VApp element.

<Link
rel="down"
type="application/[Link]+xml"
href="[Link]

The following elements can include a link to a Metadata element.

n Catalog

n CatalogItem

n Disk

n Media

n OrgVdcNetwork

n ProviderVdc

n ProviderVdcStorageProfile

n VApp

n VAppTemplate

n Vdc

n VdcStorageProfile

n Vm

A Metadata element can contain up to 1024 MetadataEntry elements (name=value pairs) that the object owner
or an administrator can create, retrieve, update, and delete. It also contains a group of name=value pairs that
are under the control of the system administrator.

VMware, Inc. 357

vCloud API Programming Guide for Service Providers

vCloud API Object Metadata Contents

Each MetadataEntry includes a single name=value pair, represented in its Key and TypedValue elements. Key
names are specified by Key element contents. A key name is a UTF-8 (Unicode) string encoded as described
in RFC3986 (pct-encoded).

The key name must be unique within the scope of the containing Metadata element. Because key names are
implicitly qualified by the Domain value of the containing MetadataEntry, the two key names in this example
are considered to be unique.

<Metadata
...
<MetadataEntry>
<Domain
visibility="READONLY">SYSTEM</Domain>
<Key>Foo</Key>
...
</MetadataEntry>
<MetadataEntry>
<Key>Foo</Key>
...
</MetadataEntry>
</Metadata>

See “Access Control for vCloud API Object Metadata,” on page 359 for more information about the Domain
element.

The type of a Value is expressed in the xsi:type attribute of the containing TypedValue element. Values have
various restrictions, based on their type.

Table 9‑1. Metadata TypedValue Types

Type Name Restrictions on Value Size of Value

MetadataStringValue UTF-8 character set. Strings Depends on length of string.

longer than 1000 characters
cannot be searched for in a
query.

MetadataNumberValue Must be a signed 8-byte integer. 8 bytes

MetadataDateTimeValue UTC date and time in the 8 bytes

format defined by
[Link]
ma-2/#dateTime. For example,
2012-06-18T[Link]-05:00
MetadataBooleanValue Must be one of: 1, 0, true, false 1 byte

The following rules apply when you update a Metadata element.

n When the content of a Key element in the update does not match the content of an existing Key element
in the same Domain, the MetadataEntry containing that Key is added to the Metadata element.

n When the content of Key element in the update matches the content of an existing Key element in the
same Domain, the MetadataEntry containing that Key is replaced.

358 VMware, Inc.

Chapter 9 Working With Object Metadata

Access Control for vCloud API Object Metadata

The Domain element of a MetadataEntry controls access to that entry by users and system administrators.
There are two access domains, only one of which can be specified explicitly.

GENERAL This is the default access domain for metadata, and cannot be explicitly
specified in a Domain element. A MetadataEntry that does not include a
Domain element is considered to be in the GENERAL domain. User access to
metadata in the GENERAL domain is controlled by the user's rights to the object
to which the Metadata is attached. The owner of the object can create, read,
update, or delete any MetadataEntry in the GENERAL domain.

SYSTEM To be placed in the SYSTEM domain, a MetadataEntry must include a Domain

element with a value of SYSTEM. Metadata in the SYSTEM domain can be
created, updated, and deleted only by a system administrator. User access to
metadata in the SYSTEM domain is controlled by the value of the visibility
attribute of the Domain element.

Table 9‑2. Domain Visibility Attribute Values

Value Meaning

PRIVATE The metadata is visible to system

administrators only.

READONLY the metadata is visible to system

administrators and the object owner.

VCENTER Object metadata in the VCENTER domain can be applied to Vm objects,

including Vm objects contained in VAppTemplate objects, by users in roles that
have the right vApp: Allow metadata mapping domain to vCenter. The
system uses metadata in this domain to deploy virtual machines on specific
ESXi hosts that have been configured by your service provider. Your service
provider establishes the set of legal values for metadata in this domain. See
“Using Metadata to Control Virtual Machine Placement,” on page 129.

Note Object metadata in the VCENTER domain is not displayed in the

vCloud Director Web Console.

vCloud API Object Metadata Limits

The following limits apply to vCloud API object metadata:

Metadata key size The contents of a Key element in a MetadataEntry cannot exceed 256 UTF-8
characters.

Metadata size The size of all Metadata for an object, computed as the sum of all Key and
TypedValue UTF-8 strings in all MetadataEntry elements in the GENERAL
domain, cannot exceed 128 KB. An additional 16KB of MetadataEntry content
can be created in the SYSTEM domain.

MetadataEntry limit The total metadata associated with an object cannot exceed 1024
MetadataEntry elements in the GENERAL domain and 128 MetadataEntry
elements in the SYSTEM domain.

VMware, Inc. 359

vCloud API Programming Guide for Service Providers

This chapter includes the following topics:

n “Retrieve or Update a Metadata Element,” on page 360

n “Retrieve or Update a Metadata Value,” on page 363

Retrieve or Update a Metadata Element

An administrator or the owner of an object can create, retrieve, or update the object's Metadata element. This
element contains all object metadata. Operations that modify it merge the modifications with existing
contents.

When you create an object, its representation contains an empty Metadata element. An administrator or the
object owner can add metadata by updating the Metadata element with new MetadataEntry elements. Each
of these elements contains a Key and a TypedValue. The contents of the Key element define the key name,
which must be unique within the scope of the object's metadata. You can modify the value associated with
an existing key. See “Retrieve or Update a Metadata Value,” on page 363.

Note The Key element cannot contain a semicolon character (;). In addition, several other character
sequences are not allowed, or not allowed in certain positions.

Table 9‑3. Content Restrictions for Key

Cannot Contain Cannot Start with Cannot End with

/../ ./ /.

/./ ../ /..

Prerequisites
n Verify that you are logged in to the vCloud API as an administrator or the object owner.

n Retrieve the object's Metadata element. See “Retrieve or Update a Metadata Element,” on page 360

Procedure
1 Retrieve the representation of the object.

Examine the response to find its metadata link. This example shows the metadata link from an AdminOrg.

<Link
rel="down"
type="application/[Link]+xml"
href="[Link]

2 Retrieve the Metadata element.

If the object has no metadata, the element contains only a rel="add" link that you can use to add
metadata and a rel="up" link that references the containing object, as shown in this example.

<Metadata
xmlns="[Link]
type="application/[Link]+xml"
href="[Link]
... >
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<Link

360 VMware, Inc.

Chapter 9 Working With Object Metadata

rel="add"
type="application/[Link]+xml"
href="[Link] />
</Metadata>

3 Modify the retrieved Metadata element.

You can add new MetadataEntry elements or modify existing ones. If you modify existing ones, your
modifications are merged into the object's Metadata following the rules listed in “vCloud API Object
Metadata Contents,” on page 358.

4 POST the Metadata element to the rel="add" link described in Step 2.

See “Example: Update a Metadata Element,” on page 361.

Example: Update a Metadata Element

This example updates the empty Metadata element shown in Step 2 to create two MetadataEntry elements.

In this example, the Metadata element contains MetadataEntry elements for which the Domain is SYSTEM. Only
the system administrator can update these elements.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Metadata
xmlns="[Link]
xmlns:xsi="[Link]
type="application/[Link]+xml">
<MetadataEntry
type="application/[Link]+xml">
<Domain
visibility="READONLY">SYSTEM</Domain>
<Key>Organization Web Page</Key>
<TypedValue
xsi:type="MetadataStringValue">
<Value>[Link]
</TypedValue>
</MetadataEntry>
<MetadataEntry
type="application/[Link]+xml">
<Domain
visibility="PRIVATE">SYSTEM</Domain>
<Key>LOS</Key>
<TypedValue
xsi:type="MetadataStringValue">
<Value>bronze</Value>
</TypedValue>
</MetadataEntry>
</Metadata>

The response is a Task.

VMware, Inc. 361

vCloud API Programming Guide for Service Providers

Response:

<Task
xmlns="[Link]
status="running"
...
operationName="metadataUpdate"
operation="Updating metadata for vApp (7)"
... >
...
</Task>

After the task is complete, the Metadata element is updated to contain the entries specified in the request,
along with links that you can use to retrieve or update individual MetadataEntry elements.

GET [Link]
...
<Metadata
xmlns="[Link]
type="application/[Link]+xml"
href="[Link]
... >
<Link
rel="add"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<MetadataEntry>
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link]
+Page" />
<Link
rel="remove"
type="application/[Link]+xml"
href="[Link]
+Page" />
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<Domain
visibility="READONLY">SYSTEM</Domain>
<Key>Organization Web Page</Key>
<TypedValue
xsi:type="MetadataStringValue">
<Value>[Link]
</TypedValue>
</MetadataEntry>
<MetadataEntry>
<Link
rel="edit"
type="application/[Link]+xml"

362 VMware, Inc.

Chapter 9 Working With Object Metadata

href="[Link] />
<Link
rel="remove"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<Domain
visibility="PRIVATE">SYSTEM</Domain>
<Key>LOS</Key>
<TypedValue
xsi:type="MetadataStringValue">
<Value>bronze</Value>
</TypedValue>
</MetadataEntry>
</Metadata>

Retrieve or Update a Metadata Value

Each name=value pair in an object's metadata is represented as a MetadataEntry element, which includes
links that an administrator or the object owner can use to retrieve or update the metadata value, or delete
the MetadataEntry.

Prerequisites
n Verify that you are logged in to the vCloud API as an administrator or the object owner.

n Retrieve the object's Metadata element. See “Retrieve or Update a Metadata Element,” on page 360

Procedure
1 Examine the retrieved Metadata element to find the MetadataEntry you want.

Each MetadataEntry contains a link of the following form, which you can use when updating the Value
of the entry:

<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />

For example:

<Link
...
href="[Link]

VMware, Inc. 363

vCloud API Programming Guide for Service Providers

2 Retrieve or update the value.

Make a request to the URL in the value of the href attribute of the MetadataEntry that contains the Key.

n To retrieve the value, make a GET request to URL in the value of the href attribute of the
MetadataEntry. The response is a MetadataValue element.

n To update the value, make a PUT request to the URL in the edit link described in Step 1, and
supply a MetadataValue element as the request body. See .“Example: Update a Metadata Value,” on
page 364

Note The href value of a MetadataEntry in the SYSTEM domain includes the SYSTEM qualifier. The href
value of a MetadataEntry in the GENERAL domain does not include a qualifier.

Example: Update a Metadata Value

This request updates the value of the metadata Key named LOS from the original value of bronze (shown in
“Example: Update a Metadata Element,” on page 361) to a new value of silver. Note that because this
MetadataValue is contained by a MetadataEntry where the Domain is SYSTEM and visibility is PRIVATE, only a
system administrator can update it.

Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<MetadataValue
xmlns="[Link]
xmlns:xsi="[Link]
<TypedValue
xsi:type="MetadataStringValue">
<Value>silver</Value>
</TypedValue>
</MetadataValue>

The response is a task.

Response:

<Task
xmlns="[Link]
status="running"
...
operationName="metadataUpdate"
operation="Updating metadata for vApp (7)"
... >
...
</Task>

364 VMware, Inc.

Using the Query Service 10
You can use the vCloud API query service to query the vCloud Director database for information about
objects in the cloud.

The query service provides the following kinds of queries:

n Typed queries, which require you to construct a query URL that specifies a query type and optional
parameters.

n Packaged queries, which have well-known URLs and can accept many of the same parameters used
with typed queries.

Both typed and packaged queries allow you to specify one of the following formats in which to display the
result set:

n A records format that returns name=value pairs for all properties of each matching object. This is the
default. A name can be either a static or dynamic. Static names are predefined object property names,
and are returned in an object-specific QueryRecordResultType element. For a list of these names, see the
Queries reference pages in the vCloud API Schema Reference. Dynamic names are user-defined metadata
key names. Dynamic name=value pairs are not returned unless the object includes a non-empty Metadata
element. See Chapter 9, “Working With Object Metadata,” on page 357.

n An idrecords format that is identical to the records format, except that object reference values are
returned in id format rather than href format. See “Objects, References, and Representations,” on
page 12.

n A references format that returns a reference in href format to each object that matches the query
criteria.

Query results are paginated, and include links to previous and next pages where needed. Page size can be
specified in the query request. Default and maximum page sizes are specified in the vCloud Director
configuration. You can also apply filter criteria to the list of items returned.
This chapter includes the following topics:

n “Typed Queries,” on page 366

n “Packaged Queries,” on page 370

n “Query Parameters,” on page 375

n “Add a Metadata Filter to a Query,” on page 379

VMware, Inc. 365

vCloud API Programming Guide for Service Providers

Typed Queries
Typed queries require you to construct a request URL that specifies an object type and optional parameters.
Use this URL with a GET request to return query results.

Query Syntax
Typed queries have the following syntax:

API-URL/query?type=name[&param][&param ... ][&filter]

n API-URL is a URL of the form [Link]

n name is the name of a query type. Type names are case-sensitive.

n param is an optional query parameter. Zero or more parameters are allowed. See “Query Parameters,”
on page 375.

n filter is an optional filter expression. At most one filter expression is allowed. See “Filter Expressions,”
on page 376.

Query Types
Each query type returns its result set as an XML document in which objects are represented as elements and
object properties are represented as attributes, pairing the name of the property with its value at the time the
request was made. By default, result sets are returned in the records format, which shows all database
records for each object. Most queries also support the references format, which returns a set of object
references, including name, type, and href attributes. All queries that support the records format also
support the idrecords format. For more information about the format parameter, see “Query Parameters,”
on page 375.

Query Reference
The vCloud API schema reference includes reference material for all queries.

Example: Listing All Queries

You can retrieve a summary list of all typed queries types accessible to the currently authenticated user by
making a request like this one:

GET [Link]

The response is a QueryList element that contains a Link for every query. The href value of each Link is a
URL you can GET to run the query specifying the default format.

<?xml version="1.0" encoding="UTF-8"?>

<QueryList
type="application/[Link]+xml"
href="[Link]
... >
<Link
rel="down"
type="application/[Link]+xml"
name="organization"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
name="organization"

366 VMware, Inc.

Chapter 10 Using the Query Service

href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
name="organization"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
name="adminOrgNetwork"
href="[Link] />
...
</QueryList>

If you make a query whose result set you do not have rights to view, a response code of
ACCESS_TO_RESOURCE_IS_FORBIDDEN (403) is returned.

Example: Simple Typed Query

This simple typed query retrieves a list of all users in your organization and returns a response in the
default (records) format.

GET [Link]

Response:

<QueryResultRecords
xmlns="[Link]
total="3"
pageSize="25"
page="1"
name="user"
type="application/[Link]+xml"
href="[Link]
type=user&amp;page=1&amp;pageSize=25&amp;format=records"
xmlns:xsi="[Link]
xsi:schemaLocation="[Link]
[Link]
<Link
rel="alternate"
type="application/[Link]+xml"
href="[Link]
type=user&amp;page=1&amp;pageSize=25&amp;format=references"/>
<UserRecord
deployedVMQuota="0"
fullName="User One"
identityProviderType="INTEGRATED"
isEnabled="true"
isLdapUser="false"
name="bob"
numberOfDeployedVMs="0"
numberOfStoredVMs="0"
storedVMQuota="0"
href="[Link]
storedVMQuotaRank="-1"
deployedVMQuotaRank="-1"/>
<UserRecord

VMware, Inc. 367

vCloud API Programming Guide for Service Providers

deployedVMQuota="0"
fullName="User Two"
identityProviderType="INTEGRATED"
isEnabled="true"
isLdapUser="false"
name="zorro"
numberOfDeployedVMs="0"
numberOfStoredVMs="0"
storedVMQuota="0"
href="[Link]
storedVMQuotaRank="-1"
deployedVMQuotaRank="-1"/>
<UserRecord
deployedVMQuota="0"
fullName="Example User"
identityProviderType="INTEGRATED"
isEnabled="true"
isLdapUser="false"
name="nobody"
numberOfDeployedVMs="0"
numberOfStoredVMs="0"
storedVMQuota="0"
href="[Link]
storedVMQuotaRank="-1"
deployedVMQuotaRank="-1"/>
</QueryResultRecords>

This simple typed query retrieves the same list of all users in your organization and returns a response in
the references format.

GET [Link]

Response:

<UserReferences
xmlns="[Link]
total="3"
pageSize="25"
page="1"
name="user"
type="application/[Link]+xml"
href="[Link]
type=user&amp;page=1&amp;pageSize=25&amp;format=references"
xmlns:xsi="[Link] ...
<Link
rel="alternate"
type="application/[Link]+xml"
href="[Link]
type=user&amp;page=1&amp;pageSize=25&amp;format=records" />
<UserReference
type="application/[Link]+xml"
name="bob"
href="[Link] />
<UserReference
type="application/[Link]+xml"
name="zorro"
href="[Link] />

368 VMware, Inc.

Chapter 10 Using the Query Service

<UserReference
type="application/[Link]+xml"
name="nobody"
href="[Link] />
</UserReferences>

Example: Query With Parameters

This query retrieves a list of all users in your organization and returns a response in the records format. The
query includes a sortAsc=name parameter, so the result set is sorted by object name.

GET [Link]

Response:

<UserReferences
xmlns="[Link]
total="3"
pageSize="25"
page="1"
name="user"
type="application/[Link]+xml"
href="[Link]
type=user&amp;page=1&amp;pageSize=25&amp;format=references"
xmlns:xsi="[Link] ... >
<Link
rel="alternate"
type="application/[Link]+xml"
href="[Link]
type=user&amp;page=1&amp;pageSize=25&amp;format=records" />
<UserReference
type="application/[Link]+xml"
name="bob"
href="[Link] />
<UserReference
type="application/[Link]+xml"
name="nobody"
href="[Link] />
<UserReference
type="application/[Link]+xml"
name="zorro"
href="[Link] />
</UserReferences>

This query retrieves a list of all users in your organization and returns a response in the records format. The
query includes a filter=ldapUser==true parameter, so the result set lists the subset of users who are
imported from LDAP. Note that you can filter on a record (attribute) value even though you specify the
references format.

GET [Link]

Response:

<?xml version="1.0" encoding="UTF-8"?>

<UserReferences
xmlns="[Link]
total="2"
pageSize="25"
page="1"

VMware, Inc. 369

vCloud API Programming Guide for Service Providers

name="user"
type="application/[Link]+xml"
href="[Link]
type=adminUser&amp;page=1&amp;pageSize=25&amp;format=references&amp;filter=ldapUser==true"
xmlns:xsi="[Link] ... >
<Link
rel="alternate"
type="application/[Link]+xml"

href="[Link]
cords&amp;filter=ldapUser==true" />
<UserReference
type="application/[Link]+xml"
name="bob"
href="[Link] />
<UserReference
type="application/[Link]+xml"
name="zorro"
href="[Link] />
</UserReferences>

Packaged Queries
Packaged queries have well-known URLs and can accept most of the parameters used with typed queries.

Query Syntax
Packaged queries have the following syntax:

API-URL/query-url[?param][&param ... ][&filter]

n API-URL is a URL of the form [Link]

n query-url is the packaged query URL.

n param is an optional query parameter. Zero or more parameters are allowed. See “Query Parameters,”
on page 375.

n filter is an optional filter expression. At most one filter expression is allowed. See “Filter Expressions,”
on page 376.

The response is a QueryList element that contains a Link for every query. The href value of each Link is a
URL you can GET to run the query specifying the default format.

Each query type returns its result set as an XML document in which objects are represented as elements and
object properties are represented as attributes, pairing the name of the property with its value at the time the
request was made. By default, result sets are returned in the records format, which shows all database
records for each object. Most queries also support the references format, which returns a set of object
references, including name, type, and href attributes. All queries that support the records format also
support the idrecords format. For more information about the format parameter, see “Query Parameters,”
on page 375.

370 VMware, Inc.

Chapter 10 Using the Query Service

Query Categories
Packaged queries are divided into the following categories:

User queries The queries have the form API-URL/object-type/query. Any user can run these
queries.

Administrator queries The queries have the form API-URL/admin/object-type/query. An organization

administrator can run these queries.

Extension queries The queries have the form API-URL/admin/extension/object-type/query. A

system administrator can run these queries.

Table 10‑1. Packaged Queries

Query URL Result Set

API-URL/catalogs/query All catalogs in your organization that you have rights to

view or modify

API-URL/mediaList/query All media that you can view or modify

API-URL/vAppTemplates/query All vApp templates that you can view or modify

API-URL/vApps/query All vApps that you can view or modify

API-URL/vms/query All virtual machines that you can view or modify

API-URL/admin/groups/query Groups in all organizations in the system

API-URL/admin/users/query Users in all organizations in the system

API-URL/admin/strandedUsers/query Stranded users in the organization. When you delete an

LDAP group, users who were imported from that group
become stranded and cannot log in.

API-URL/admin/roles/query All roles defined in the system

API-URL/admin/rights/query All rights defined in the system

API-URL/admin/orgs/query All organizations visible to you

API-URL/admin/vdcs/query All VDCs in the system

API-URL/admin/extension/hostReferences/query All hosts registered to the system

API-URL/admin/extension/datastores/query All datastores in the system

API- External networks in the system

URL/admin/extension/externalNetworkReferences/query

API-URL/admin/extension/networkPoolReferences/query All network pools in the system

API-URL/admin/extension/providerVdcReferences/query All provider VDCs in the system

API-URL/admin/extension/vimServerReferences/query All vCenter servers registered to the system

API-URL/admin/extension/orgNetworks/query All organization networks in the system

API-URL/admin/extension/vapps/query All vApps in the system

API-URL/admin/extension/orgVdcs/query All VDCs in the system

Examples
Simple packaged query using the records format, which is the default.

GET [Link]

VMware, Inc. 371

vCloud API Programming Guide for Service Providers

Response:

<QueryResultRecords
xmlns="[Link]
total="15"
pageSize="25"
page="1"
name="catalog"
type="application/[Link]+xml"
href="[Link]
xmlns:xsi="[Link] ... >
<Link
rel="alternate"
type="application/[Link]+xml"
href="[Link]
type=catalog&amp;page=1&amp;pageSize=25&amp;format=references" />
<CatalogRecord
ownerName="system"
organizationName="VMware"
numberOfTemplates="30"
numberOfMedia="3"
name="VAM"
isShared="true"
isPublished="true"
description=""
createdOn="2011-03-21T[Link].273-07:00"
href="[Link] />
<CatalogRecord
ownerName="system"
organizationName="QA"
numberOfTemplates="0"
numberOfMedia="1"
name="QA-Cat"
isShared="false"
isPublished="true"
description=""
createdOn="2011-03-24T[Link].130-07:00"
href="[Link] />
<CatalogRecord
ownerName="system"
organizationName="Org-d5443f6b-85e"
numberOfTemplates="0"
numberOfMedia="1"
name="Catalog-3f79780c-6b0"
isShared="true"
isPublished="true"
description=""
createdOn="2011-03-25T[Link].063-07:00"
href="[Link] />
<CatalogRecord
ownerName="system"
organizationName="Engineering"
numberOfTemplates="2"
numberOfMedia="4"
name="TestCat"
isShared="true"

372 VMware, Inc.

Chapter 10 Using the Query Service

isPublished="true"
description="New Catalog"
createdOn="2011-03-22T[Link].067-07:00"
href="[Link] />
<CatalogRecord
ownerName="system"
organizationName="Engineering"
numberOfTemplates="8"
numberOfMedia="1"
name="catalog1"
isShared="true"
isPublished="true"
description=""
createdOn="2011-03-22T[Link].360-07:00"
href="[Link] />
</QueryResultRecords>

Packaged query using references format.

GET [Link]

Response:

<CatalogReferences
xmlns="[Link]
total="15"
pageSize="25"
page="1"
name="catalog"
type="application/[Link]+xml"
href="[Link]
page=1&amp;pageSize=25&amp;format=references"
xmlns:xsi="[Link] ... >
<Link
rel="alternate"
type="application/[Link]+xml"
href="[Link]
type=catalog&amp;page=1&amp;pageSize=25&amp;format=records" />
<CatalogReference
type="application/[Link]+xml"
name="VAM"
href="[Link] />
<CatalogReference
type="application/[Link]+xml"
name="QA-Cat"
href="[Link] />
<CatalogReference
type="application/[Link]+xml"
name="Catalog-3f79780c-6b0"
href="[Link] />
<CatalogReference
type="application/[Link]+xml"
name="TestCat"
href="[Link] />
<CatalogReference

VMware, Inc. 373

vCloud API Programming Guide for Service Providers

type="application/[Link]+xml"
name="catalog1"
href="[Link] />
</CatalogReferences>

Packaged query with sorting and filtering. This query adds parameters and a filter expression to produce a
list of catalogs that contain one or more vApp templates. The query sorts the result set in ascending order by
number of vApp templates:

GET [Link]
format=records&sortAsc=numberOfTemplates&filter=numberOfTemplates!=0

Response:

<QueryResultRecords
xmlns="[Link]
total="3"
pageSize="25"
page="1"
name="catalog"
type="application/[Link]+xml"
href="[Link]
page=1&amp;pageSize=25&amp;format=records&amp;filter=numberOfTemplates!
=0&amp;sortAsc=numberOfTemplates"
xmlns:xsi="[Link] ... >
<Link
rel="alternate"
type="application/[Link]+xml"
href="[Link]
type=catalog&amp;page=1&amp;pageSize=25&amp;format=references&amp;filter=numberOfTemplates!
=0&amp;sortAsc=numberOfTemplates" />
<CatalogRecord
ownerName="system"
organizationName="Engineering"
numberOfTemplates="2"
numberOfMedia="4"
name="TestCatalog"
isShared="true"
isPublished="true"
description="New Catalog"
createdOn="2011-03-22T[Link].067-07:00"
href="[Link] />
<CatalogRecord
ownerName="system"
organizationName="Engineering"
numberOfTemplates="8"
numberOfMedia="1"
name="catalog1"
isShared="true"
isPublished="true"
description=""
createdOn="2011-03-22T[Link].360-07:00"
href="[Link] />
<CatalogRecord
ownerName="system"
organizationName="VMware"
numberOfTemplates="30"

374 VMware, Inc.

Chapter 10 Using the Query Service

numberOfMedia="3"
name="VAM"
isShared="true"
isPublished="true"
description=""
createdOn="2011-03-21T[Link].273-07:00"
href="[Link] />
</QueryResultRecords>

Query Parameters
Query parameters specify result set properties such as pagination, sort order, and filter criteria.

Query Parameters
Typed queries must include a type parameter, which specifies the type of query to run. Packaged queries
cannot specify a type parameter. All other parameters are optional. If a parameter is omitted, a default value
is assumed.

Table 10‑2. Query Parameters

Parameter Name Parameter Description Default

fields Comma-separated list of attribute names or metadata key Returns all static attribute
names to return. For example, fields=name,isEnabled or names. Returns metadata
fields=metadata:rank. See “Specifying Metadata in a only if the object has a non-
Query or a Filter Expression,” on page 377. empty Metadata element.

filter Filter expression. See Table 10-3 None

filterEncoded Specify whether the filter expression is encoded as described filterEncoded=false

in RFC3986 (pct-encoded). See “Encoding Filter
Expressions,” on page 378

format One of the following types: format=records

references Returns a reference to each object,

including its name, type, and href
attributes.

records Returns all database records for each

object, with each record as an attribute.

idrecords Identical to the records format, except

that object references are returned in id
format rather than href format.

links Boolean value specifying whether to include Link elements links=false

in the result set for certain object types.

offset Integer value specifying the first record to return. Record offset=0
numbers < offset are not returned.

page If the query results span multiple pages, return this page. page=1

pageSize Number of results per page, to a maximum of 128. pageSize=25

sortAsc=attribute-name Sort results by attribute-name in ascending order. attribute- Sorted by database ID

name cannot include metadata. See the vCloud API Schema
Reference for infomation about which attributes can be used
with sortDesc.

VMware, Inc. 375

vCloud API Programming Guide for Service Providers

Table 10‑2. Query Parameters (Continued)

Parameter Name Parameter Description Default

sortDesc=attribute-name Sort results by attribute-name in descending order. attribute- Sorted by database ID

name cannot include metadata. See the vCloud API Schema
Reference for infomation about which attributes can be used
with sortDesc.

type The type of the query. Type names are case-sensitive. See None. This parameter is
“Query Types,” on page 366. required for all typed
queries, and is not allowed
for any packaged query.

Filter Expressions
For queries that do not examine object metadata, you can filter results using string matching or numeric
comparison operations. A filter comprises one or more subexpressions drawn from the following set of
operators.

Table 10‑3. Query Filter Expressions

Operator Example Operation

== attribute==value Matches. The example evaluates to true if attribute

has a value that matches value in a case-sensitive
comparison.
Note Asterisk (*) characters that appear
anywhere in value are treated as wildcards that
match any character string. When value includes
wildcards, the comparison with attribute becomes
case-insensitive.

!= attribute!=value Does not match. The example evaluates to true if

attribute has a value that does not match value in a
case-sensitive comparison. Wildcard characters are
not allowed.

; attribute1==value1;attribute2!=value2 Logical AND. The example evaluates to true only if

attribute1 has a value that matches value1 and
attribute2 has a value that does not match value2 in
a case-sensitive comparison.

, attribute1==value1,attribute2==value2 Logical OR. The example evaluates to true if

attribute1 has a value that matches value1 or
attribute2 has a value that matches value2 in a case-
sensitive comparison.

=gt= attribute=gt=value Greater than. The example evaluates to true if

attribute has a value that is greater than value. Both
attribute and value must be of type int, long, or
dateTime.

=lt= attribute=lt=value Less than. The example evaluates to true if attribute

has a value that is less than value. Both attribute and
value must be of type int, long, or dateTime.

376 VMware, Inc.

Chapter 10 Using the Query Service

Table 10‑3. Query Filter Expressions (Continued)

Operator Example Operation

=ge= attribute=ge=value Greater than or equal to. The example evaluates to

true if attribute has a value that is greater than or
equal to value. Both attribute and value must be of
type int, long, or dateTime.

=le= attribute=le=value Less than or equal to. The example evaluates to

true if attribute has a value that is less than or equal
to value. Both attribute and value must be of type
int, long, or dateTime.

Not all attributes can be used in a filter expression. For details, see the reference pages for query result types
in the vCloud API Schema Reference.

Specifying Metadata in a Query or a Filter Expression

Because metadata values are dynamic and metadata names have an optional domain qualifier queries that
filter metadata must specify a qualified name, a value, and the type of the value.

n The domain must be specified for any MetadataEntry that is in the SYSTEM domain. If no DOMAIN is
specified, the query returns the value for key name in the GENERAL domain, if it exists.

n The type of the value must be specified, using one of the following keywords.

Table 10‑4. Metadata Type Specifiers in Query Filters

Type Name as Specified in TypedValue Type Name as a Filter Expression Keyword

MetadataStringValue STRING

MetadataNumberValue NUMBER

MetadataDateTimeValue DATETIME

MetadataBooleanValue BOOLEAN

For queries that examine object metadata, you can filter query results using numeric comparison operations
when a metadata value has type NUMBER or DATETIME. Because object metadata types are dynamic, filter
expressions for metadata queries require additional parameters that define the attribute part of the
expression as metadata, and specify the type of the value part of the expression.

Table 10‑5. Metadata Query Filter Expressions

Operator Example Operation

=gt= metadata:attribute=gt=[NUMBER | Greater than. The example evaluates to true if value

DATETIME]:value is of type NUMBER or DATETIME and the value of
the metadata key named attribute is greater than
value.

=lt= metadata:attribute=lt=[NUMBER | Less than. The example evaluates to true if value is

DATETIME]:value of type NUMBER or DATETIME and the value of
the metadata key named attribute is less than value.

=ge= metadata:attribute=ge=[NUMBER | Greater than or equal to. The example evaluates to

DATETIME]:value true if value is of type NUMBER or DATETIME and
the value of the metadata key named attribute is
greater than or equal to value.

=le= metadata:attribute=le=[NUMBER | Less than or equal to. The example evaluates to

DATETIME]:value true if value is of type NUMBER or DATETIME and
the value of the metadata key named attribute is
less than or equal to value.

VMware, Inc. 377

vCloud API Programming Guide for Service Providers

You can specify up to 8 metadata fields in a single query. You cannot use a metadata value as a sort key
when sorting query output.

The syntax for specifying metadata in a fields parameter is:

fields=metadata[@SYSTEM]:key-name

For example:

fields=metadata:rank

fields=metadata@SYSTEM:expiry

The syntax for specifying a metadata field in a filter expression is:

metadata[@SYSTEM]:key-name operator type-keyword:value

For example:

metadata:rank=ge=NUMBER:1

metadata@SYSTEM:expiry=le=DATETIME:2012-06-18T[Link]-05:00

Encoding Filter Expressions

When you are comparing a key with a literal value that includes characters that might be subject to
interpretation when used in a URL (often termed unsafe characters), the value must be encoded as described
in RFC3986 (pct-encoded). For example, to create a filter expression to match a hostName property whose
value is 12&345, encode the value as shown here:

filter=hostName==12%26345

When a filter expression includes metadata, you must encode both the key and the value this way. In
addition, if you specify filterEncoded=true as part of a query that includes metadata, you must encode the
% symbol as %25. For example, this query, which includes metadata would require this sort of additional
encoding if you specified filterEncoded=true.

[Link]
type=organization&format=records
&fields=metadata:rank,metadata@SYSTEM:expiry
&filter=metadata%40SYSTEM%3Aexpiry%3Dlt%3DDATETIME%3ADATETIME
%253A2012-05-01T00%253A00%253A00.000-04%253A00DATETIME
%253A2012-05-01T00%253A00%253A00.000-04%253A00&filterEncoded=true

If you did not specify filterEncoded=true, you would not need the additional encoding.

[Link]
type=organization&format=records
&fields=metadata:rank,metadata@SYSTEM:expiry
&filter=metadata@SYSTEM:expiry=lt=DATETIME:DATETIME%3A2012-05-01T00%3A00%3A00.000-04%3A00

Grouping Filter Subexpressions

Group filter subexpressions with parentheses. Separate grouped subexpressions with a semicolon (no
spaces).

(attribute1==value1;attribute2!=value2);(attribute3==value3;attribute4!=value4)...

For example:

[Link]
type=providerVdcResourcePoolRelation&format=records&filter=(numberOfVMs!=0;isPrimary==true)

378 VMware, Inc.

Chapter 10 Using the Query Service

Attribute Names and Values

Several parameters and all filter expressions require you to specify an attribute name. You can use the
schema reference to find the attribute names included in a particular result set.

1 In the vCloud API Schema Reference, select All Queries.

2 Type the query name (or any part of it) in the Quick Index window, then open the query reference
page.

3 On the query reference page, click the link in the Record Result section to open a page that shows the
name, type, description, and other information for each attribute returned by the query. Attributes that
can be used in a filter expression have a YES in the FILTER column. Attributes that can be used with
sortAsc or sortDesc have a YES in the SORT column.

Add a Metadata Filter to a Query

All packaged queries and most typed queries return object metadata if it exists for an object in the result set.
You can add metadata-specific filter criteria to a query.

To query an object's metadata, add a metadata field specifier to the query. This specifier follows the fields
parameter and consists of the string metadata: followed by the name of a metadata key.

Note You must use a metadata@SYSTEM parameter to specify metadata keys in the SYSTEM domain. Metadata
in the GENERAL domain does not require a qualifier. Up to eight metadata parameters can be included in a
query.

Procedure
1 Create the filter expression.

2 Add a fields parameter that specifies metadata.

The syntax for specifying a metadata field is:

fields=metadata:key-name [, metadata:key-name ] ...

3 Add a filter expression to the query.

All of the standard filter expressions are supported for metadata queries. In addition, a set of numeric
comparisons are available for values of type NUMBER or DATETIME.

Example: A Query With a Metadata Filter

Assume that the vApps in your organization have metadata like that shown in “Example: Update a
Metadata Element,” on page 361. To retrieve a list of all the vApps that have a key named PenTested whose
value is false, use a query and filter like this one.

Request:

GET [Link]
&fields=metadata:PenTested&filter="metadata:PenTested==false"

Note When a filter expression includes metadata, you must encode both the key and the value as described
in RFC3986. See “Encoding Filter Expressions,” on page 378.

VMware, Inc. 379

vCloud API Programming Guide for Service Providers

380 VMware, Inc.

Configuring and Using Blocking
Tasks and Notifications 11
vCloud Director allows a system administrator to configure many operations as blocking tasks, which are
suspended until a system administrator acts on them or a preconfigured timer expires. Blocking tasks
generate AMQP messages that you can use to automate the handling of the underlying user request. A
system administrator can also enable nonblocking AMQP notifications of all system events.

The system administrator can configure the vCloud Director AMQP service to provide a stream of
notifications about events in the cloud. By configuring specific tasks as blocking and writing AMQP clients
that process the messages generated when these tasks are launched, you can create a programmatic facility
for reviewing and acting on tenant requests. When a user requests an operation that has been configured as
a blocking task, the system sends a message about the task to the configured AMQP broker. The system also
creates a reference to the task in the cloud's BlockingTaskReferences container. A system administrator can
retrieve the list of BlockingTask elements by making a GET request to the system's blockingTasks link, or to
a URL included in the AMQP message.

For more information about the vCloud Director AMQP service, see “Configure the vCloud Director AMQP
Service,” on page 347.

Subscribing to Notifications
Notifications of system events are sent to the AMQP message broker that was configured in the system
AMQP settings. Notifications are always generated in two formats:
n An XML document, which is sent to the AMQP exchange specified in the system AmqpSettings.

n A JSON object, which is sent to an AMQP exchange whose name has the form prefix.notifications20,
where prefix is the value of the AmqpPrefix element in the system AmqpSettings.

See “Notification Message Format,” on page 393.

AMQP client programs can connect to the broker and specify components of the AMQP routing key to
indicate their interest in messages based on content. For example, a client can use the routing key to request
the broker to send it all messages from a specific organization, or all messages that indicate a failed task. See
“Routing Key Format,” on page 393.

Processing Messages from Blocking Tasks

Messages from blocking tasks are also sent to the configured message broker, and clients can use the routing
key to indicate their interest in these messages. See “Subscribing to Notifications,” on page 381. Messages
from blocking tasks contain additional information about the task itself. Clients that process these messages
can use the vCloud API to authenticate to the system and act on the blocked task.

VMware, Inc. 381

vCloud API Programming Guide for Service Providers

This chapter includes the following topics:

n “Configure Notifications,” on page 382

n “Retrieve or Update Blocking Task Settings,” on page 383

n “Monitor Blocking Tasks,” on page 388

n “Take Action on a Blocking Task,” on page 389

n “Extend The Timeout Expiration of an Active Task,” on page 392

n “Notification Message Format,” on page 393

Configure Notifications
The system administrator can enable or disable notification messages for events in a cloud.

Notifications are enabled by default. A system administrator can disable them.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the SystemSettings element.

2 Examine the response to locate the link that you can use to retrieve the system's NotificationsSettings
element.

This link has a rel attribute value of down and a type attribute value of
application/[Link]+xml, as shown here:

<Link href="[Link]
rel="down"
type="application/[Link]+xml"/>

3 Enable or disable notifications.

a Retrieve the NotificationsSettings element.

Make a GET request to the href value of the

application/[Link]+xml link.

b Modify the value of the EnableNotifications element to enable or disable notifications.

c Update the modified element with the new contents.

PUT the modified element to the href value of its rel="edit" link.

Example: Enable Notifications

This request sets the value of EnableNotifications to true. This is the default value, so you normally would
not need to make this request unless notifications had been disabled by a previous request.

Request:

<?xml version="1.0" encoding="UTF-8"?>

<vmext:NotificationsSettings
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
type="application/[Link]+xml">
<vmext:EnableNotifications>true</vmext:EnableNotifications>
</vmext:NotificationsSettings>

382 VMware, Inc.

Chapter 11 Configuring and Using Blocking Tasks and Notifications

The response contains information extracted from the request, and adds an edit link that you can use to
change the value of this element.

Response:

200 OK
...
<vmext:NotificationsSettings
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
href="[Link]
type="application/[Link]+xml">
<vcloud:Link
rel="edit"
href="[Link]
type="application/[Link]+xml" />
<vmext:EnableNotifications>true</vmext:EnableNotifications>
</vmext:NotificationsSettings>

Retrieve or Update Blocking Task Settings

Timeout settings, default actions, and related messages for blocking tasks are properties of a cloud. They
apply to all organizations in the cloud. Only a system administrator can view or modify them.

When a user requests an operation that is configured to create a blocking task, the system creates a reference
to the operation in the cloud's BlockingTaskReferences container. The system also sends a message about
the task to the configured AMQP broker. A system administrator can retrieve the list of
BlockingTaskReferences by making a GET request to the system's blockingTasks link. An AMQP client can
use information in the message to construct a URL that it can use to retrieve the task. See
“Example: Notification Message Format,” on page 394.

If no action is taken on the blocking task within a specified timeout interval, it is subject to a default action.
You can specify the timeout interval and default action for all blocking tasks by modifying the system's
BlockingTaskSettings element. To configure an operation as a blocking task, add the operation name to the
BlockingTaskOperations element contained by BlockingTaskSettings. See “Task Operations,” on page 385.

Prerequisites
n This operation is restricted to system administrators.

n Retrieve the SystemSettings element. See “Retrieve or Update System Settings,” on page 268.

Procedure
1 Examine the response to locate the link that you can use to retrieve the system's BlockingTaskSettings
element.

This link has a rel attribute value of down and a type attribute value of
application/[Link]+xml, as shown here:

<Link href="[Link]
rel="down"
type="application/[Link]+xml"/>

2 Retrieve the element.

Make a GET request to the href value of the link.

3 (Optional) Modify the element as needed to change the settings it controls.

See the schema reference.

VMware, Inc. 383

vCloud API Programming Guide for Service Providers

4 (Optional) Update the modified element with the new contents.

PUT the modified element to the href value of its rel="edit" link. See “Example: Update Blocking Task
Settings,” on page 384.

Example: Update Blocking Task Settings

This request modifies the blocking task settings for a cloud to set the time-out period to 24 hours and adds
media upload as an operation that creates a blocking task. See “Task Operations,” on page 385 for a list of
operation names.

Request:

PUT [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<BlockingTaskSettings
xmlns:vcloud="[Link]
xmlns="[Link]
<TimeoutAction>abort</TimeoutAction>
<BlockingTaskOperations>
<vcloud:Operation>vdcUploadMedia</vcloud:Operation>
</BlockingTaskOperations>
<TimeoutInMilliseconds>86400000</TimeoutInMilliseconds>
</BlockingTaskSettings>

The response contains information extracted from the request, and adds the href attributes and edit links
for the BlockingTaskSettings element and the BlockingTaskOperations element it contains.

Response:

200 OK
Content-Type: application/[Link]+xml
...
<BlockingTaskSettings
xmlns="[Link]
TimeoutInMilliseconds="86400000"
type="application/[Link]+xmll"
href="[Link]
xmlns:xsi="[Link] ... >
<Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<Link
rel="down"
type="application/[Link]+xml"
href="[Link]
<TimeoutAction>abort</TimeoutAction>
<BlockingTaskOperations
type="application/[Link]+xml"
href="[Link]
<Link
rel="edit"
type="application/[Link]+xml"

384 VMware, Inc.

Chapter 11 Configuring and Using Blocking Tasks and Notifications

href="[Link]
<Operation>vdcUploadMedia</Operation>
</BlockingTaskOperations>
</BlockingTaskSettings>

Task Operations
Requests that you can configure as blocking tasks are represented by task operation names.

To configure a request type as a blocking task, place the operation name in an Operation element and add
that element to the cloud's BlockingTaskOperations element. See “Retrieve or Update Blocking Task
Settings,” on page 383.

Note These operation names also appear in the operationName attribute of the Task element that tracks the
operation.

Table 11‑1. Blocking Task Operations for vApp Tasks

Operation Name Description

vappAttachDisk Attach an independent disk to any virtual machine in a vApp.

vappCheckVmCompliance Check the storage profile compliance of a virtual machine.

vappConsolidateVm Consolidate the disks of any virtual machine in a vApp.

vappCreateSnapshot Create a snapshot for the vApp

vappDeleteShadowVm Delete a shadow VM for any virtual machine in a vApp.

vappDeploy Deploy a vApp.

vappDetachDisk Detach an independent disk from any virtual machine in a vApp.

vappDiscardSuspendedState Discard the suspended state of any virtual machine in a vApp.

vappEjectCdFloppy Eject media from any virtual machine in a vApp.

vappInsertCdFloppy Insert media in any virtual machine in a vApp.

vappInstallTools Install VMware Tools on any virtual machine in a vApp.

vappMigrateVms Migrate the virtual machines in a vApp to a new host.

vappPowerOff Power-off a vApp.

vappRebootGuest Reboot any virtual machine in a vApp.

vappRelocateVm Relocate any virtual machine in a vApp.

vappRemoveAllSnapshots Remove all snapshots for this vApp

vappReset Reset any virtual machine in a vApp.

vappResume Resume any virtual machine in a vApp.

vappRevertToCurrentSnapshot Revert the vApp to its current snapshot

vappShutdownGuest Shut down any virtual machine in a vApp.

vappSuspend Suspend any virtual machine in a vApp.

vappUndeployPowerOff Undeploy any virtual machine in a vApp by powering it off.

vappUndeploySuspend Undeploy any virtual machine in a vApp by suspending it.

vappUpdateVm Modify one or more properties of a virtual machine.

vappUpgradeHwVersion Upgrade the hardware version of any virtual machine in a vApp.

reloadFromVc Reload certain properties of a virtual machine from the vCenter database.

VMware, Inc. 385

vCloud API Programming Guide for Service Providers

Table 11‑2. Blocking Task Operations for VDC Tasks

Operation Name Description

vdcCaptureTemplate Capture a vApp as a vApp template.

vdcComposeVapp Compose a vApp.

vdcCopyMedia Copy a media object.

vdcCopyTemplate Copy a vApp template.

vdcCopyVapp Clone a vApp.

vdcCreateDisk Create an independent disk.

vdcCreateVdc Create an organization VDC.

vdcDeleteDisk Delete an independent disk.

vdcDeleteMedia Delete a media object.

vdcDeleteTemplate Delete a vApp template.

vdcDeleteVapp Delete a vApp.

vdcDeleteVdc Delete an organization VDC.

vdcEnableDownload Enable a vApp template for download as OVF.

vdcInstantiateVapp Instantiate a vApp template.

vdcRecomposeVapp Recompose a vApp.

vdcRenameVdc Change the name or description of an existing VDC

vdcUpdateDisk Update an independent disk.

vdcUpdateMedia Update one or more properties of a media object.

vdcUpdateStorageProfiles Update the storage profiles of a VDC

vdcUpdateTemplate Update one or more properties of a vApp template.

vdcUpdateVapp Update any section of a vApp.

vdcUpdateVappNetworkSection Update the NetworkSection of a vApp.

vdcUpdateVdc Modify one or more properties of an organization VDC.

vdcUploadMedia Upload media.

vdcUploadOvfContents Upload other OVF package contents

vdcUploadOvfDescriptor Upload an OVF descriptor

Table 11‑3. Blocking Task Operations for Network Tasks

Operation Name Description

networkConvertOrgVdcNetworkToSubInterface Convert an existing organization VDC network interface to a

subinterface

networkCreateExternalNetwork Create an external network.

networkCreateNetworkPool Create a network pool.

networkCreateOrgNetwork Create an organization network.

networkCreateOrgVdcNetwork Create an organization VDC network.

networkCreateVappNetwork Create a vApp network.

networkDelete Delete a network.

networkDeleteNetworkPool Delete a network pool.

networkMergeNetworkPools Merge network pools.

386 VMware, Inc.

Chapter 11 Configuring and Using Blocking Tasks and Notifications

Table 11‑3. Blocking Task Operations for Network Tasks (Continued)

Operation Name Description

networkRepairNetworkPool Repair a network pool.

networkReset Reset any network.

networkResetOrgNetwork Reset an organization network.

networkResetOrgVdcNetwork Reset an organization VDC network.

networkSyncSyslogSettings Synchronize syslog settings for a network.

networkUpdateIpsecVpnTunnelStatus Update the status of a VPN tunnel

networkUpdateNetwork Modify one or more properties of a network object.

networkUpdateNetworkPool Modify one or more properties of a VlanPoolType network pool

object.

networkUpdateVlanPool Modify one or more properties of any network pool object.

networkGatewayFormFactorModify Modify the form factor of an Edge Gateway

networkGatewayUpgradeNetworking Convert an Edge Gateway to Advanced Networking

Table 11‑4. Blocking Task Operations for System Tasks

Operation Name Description

systemForceDisconnectVimserver Force disconnection of a vCenter server.

systemForceReconnectVimserver Force reconnection of a vCenter server.

systemPurgeAllStrandedItems Purge all stranded items.

systemPurgeStrandedItem Purge a specific stranded item.

systemRefreshStorageProfiles Refresh vCenter storage profiles.

systemRefreshVimserver Refresh a vCenter server.

systemRegisterLookupService Register with the vCenter lookup service.

systemRegisterVimserver Register a vCenter server.

systemUnregisterLookupService Unregister with the vCenter lookup service.

systemUnregisterVimserver Unregister a vCenter server.

systemUpdateAmqpCertificate Update the system AMQP certificate.

systemUpdateAmqpTruststore Update the system AMQP truststore.

systemUpdateLdapCertificate Update the system LDAP certificate.

systemUpdateLdapKeystore Update the system LDAP keystore.

systemUpdateLdapSspiKeytab Update the system LDAP SSPI keytab.

systemUpdateVcTruststore Update the vCenter truststore.

systemUpdateVimserver Update a vCenter server.

Table 11‑5. Blocking Task Operations for Resource Creation Tasks

Operation Name Description

rclCreateProviderVdc Create a provider VDC.

rclDeleteProviderVdc Delete a provider VDC.

rclDisableHost Disable a host.

rclEnableHost Enable a host.

rclEnableVxlanForProviderVdc Enable a VXLAN pool associated with a new Provider VDC.

VMware, Inc. 387

vCloud API Programming Guide for Service Providers

Table 11‑5. Blocking Task Operations for Resource Creation Tasks (Continued)
Operation Name Description

rclMergePvdc Merge Provider VDCs.

rclPrepareHost Prepare a host

rclRedeployAllVms Redeploy all virtual machines on this host.

rclRepairHost Repair a host.

rclUnprepareHost Unprepare a host

rclUpdateHost Update host operating system.

rclUpdateProviderVdcStorageProfiles Update provider VDC storage profiles in this cluster.

rclUpdateResourcePoolSet Update resource pools in this cluster.

rclUpgradeHostAgent Upgrade the host agent on a host.

Table 11‑6. Blocking Task Operations for Miscellaneous Tasks

Operation Name Description

commonPurgeDeletedItem Purge a deleted item.

importIntoExistingVapp Import a virtual machine from vCenter to an existing vApp.

importLocalizationResource Import external localization resources.

importMedia Import a media object from vSphere.

importSingletonTemplate Import a virtual machine from vCenter as a vApp template.

importSingletonVapp Import a virtual machine from vCenter as a vApp.

catalogDelete Delete a catalog.

catalogDeleteBacking Delete the file(s) representing a catalog item.

catalogItemEnableDownload Enable a catalog item for download

catalogSync Update a subscribed catalog item from its external source.

catalogSyncAll Update an externally subscribed catalog from its source.

metadataDelete Delete a metadata item.

metadataUpdate Update a metadata item.

orgUpdateLdapCertificate Update the SSL certificate for the system LDAP service.

orgUpdateLdapKeystore Update the SSL keystore for the system LDAP service.

orgUpdateLdapSspiKeyTab Update the SSPI keytab for the system LDAP service.

orgDeleteOrg Delete an organization.

Monitor Blocking Tasks

A system administrator can retrieve a list of all pending and active blocking tasks. Links in the returned
BlockingTask element allow the administrator to take action on the request.

In addition to being subject to programmatic action by an AMQP client (see “Notification Message Format,”
on page 393), blocking tasks can be monitored and managed by a system administrator using the vCloud
API.

Prerequisites
This operation is restricted to system administrators.

388 VMware, Inc.

Chapter 11 Configuring and Using Blocking Tasks and Notifications

Procedure
1 Retrieve the list of blocking tasks.

See the request portion of “Example: Retrieve a List of Blocking Tasks,” on page 389. If the
BlockingTaskReferences element contains no Reference elements, no blocking tasks are currently active
in the system.

2 Retrieve an individual blocking task from one of the Reference elements in the response.

See the request portion of “Example: Handling a Blocking Task,” on page 390.

3 Use one of the action links in the BlockingTask to take action on the task.

See the response portion of “Example: Handling a Blocking Task,” on page 390.

Example: Retrieve a List of Blocking Tasks

Request:

GET [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<vmext:BlockingTaskReferences
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
... >
<vcloud:Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Reference
type="application/[Link]+xml"
name="vdcUpdateTemplate"
href="[Link] />
<vcloud:Reference
type="application/[Link]+xml"
name="vdcComposeVapp"
href="[Link] />
<vcloud:Reference
type="application/[Link]+xml"
name="vdcUploadMedia"
href="[Link] />
</vmext:BlockingTaskReferences>

Take Action on a Blocking Task

The BlockingTask element includes links that you can use to take action on a blocking task.

A BlockingTask element is primarily a collection of Link elements that allow you to take action on the task.
When a user requests an operation that is configured to create a blocking task, the system sends a message
about the task to the configured AMQP broker, and also creates a reference to the task in the cloud's
BlockingTaskReferences container. A system administrator can retrieve the list of BlockingTask elements by
making a GET request to the system's extension/blockingTasks link. See “Monitor Blocking Tasks,” on
page 388.

VMware, Inc. 389

vCloud API Programming Guide for Service Providers

After authenticating to the cloud as a system administrator, the AMQP client can retrieve a blocking task.
The AMQP client makes a GET request to a URL that the task creates by appending the value of the id
attribute of the task to the entityResolver URL in the Notification. See “Example: Notification Message
Format,” on page 394.

The following actions are allowed:

resume Unblock the task and allow it to continue.

abort End the task, cleaning up any transient objects that it created. Task status is
set to ABORTED.

fail End the task, setting the status of any transient objects that it created to
ERROR. Task status is set to ERROR.

updateProgress Reset the timeout value and timeout action for an active task. Use this action
to keep the task alive when it might become subject to a timeout action.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the list of active blocking tasks.

See “Monitor Blocking Tasks,” on page 388. If you are using an AMQP client to handle blocking tasks,
skip this step. Each blocking task creates its own AMQP message, which contains a reference to the
BlockingTask.

2 Retrieve an individual BlockingTask.

See the request portion of “Example: Handling a Blocking Task,” on page 390.

3 Make a request.

Action Request
resume POST a BlockingTaskOperationParams element to the Link where
rel="resume"
abort POST a BlockingTaskOperationParams element to the Link where
rel="abort"
fail POST a BlockingTaskOperationParams element to the Link where
rel="fail"
updateProgress POST a BlockingTaskUpdateProgressParams element to the Link
where rel="updateProgress"

Example: Handling a Blocking Task

This request shows how to retrieve a blocking task without using an AMQP client. “Example: Notification
Message Format,” on page 394 shows how to retrieve the same task using information in the AMQP
message.

Request:

GET [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<vmext:BlockingTask

390 VMware, Inc.

Chapter 11 Configuring and Using Blocking Tasks and Notifications

xmlns:vmext="[Link]
xmlns:vcloud="[Link]
status="active"
timeoutDate="2011-05-07T[Link].857+03:00"
timeoutAction="abort"
createdTime="2011-05-02T[Link].857+03:00"
name="importSingletonTemplate"
id="urn:vcloud:blockingTask:25"
type="application/[Link]+xml"
href="[Link]
<vcloud:Link
rel="resume"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="abort"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="fail"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="updateProgress"
type="application/[Link]+xml"

href="[Link] />
<vcloud:Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Organization
type="application/[Link]+xml"
name="example"
href="[Link] />
<vcloud:User
type="application/[Link]+xml"
name="system"
href="[Link] />
<vcloud:TaskOwner
type="application/[Link]+xml"
name=""
href="[Link] />
</vmext:BlockingTask>

The following request allows the task to resume with a message indicating administrative approval.

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<BlockingTaskOperationParams
xmlns="[Link] >
<Message>Approved by system administrator.</Message>
</BlockingTaskOperationParams>

VMware, Inc. 391

vCloud API Programming Guide for Service Providers

Extend The Timeout Expiration of an Active Task

You can use the updateProgress link in a BlockingTask to extend the expiration time of an active task.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the list of active blocking tasks.

See “Monitor Blocking Tasks,” on page 388. If you are using an AMQP client to handle task extension
requests, skip this step. Each blocking task creates its own AMQP message, which contains a reference
to the BlockingTask mentioned in Step 1.

2 Retrieve an individual BlockingTask.

See the request portion of “Example: Handling a Blocking Task,” on page 390.

3 Provide a new timeout value, relative to now, for the task.

Create a BlockingTaskUpdateProgressParams element that specifies the number of milliseconds until the
task times out. See “Example: Extend The Timeout Expiration of an Active Task,” on page 392.

4 POST the BlockingTaskUpdateProgressParams to the updateProgress URL from the BlockingTask.

The new timeout value is set to now (the time when the updateProgress request is executed)
plusTimeoutValueInMilliseconds.

Example: Extend The Timeout Expiration of an Active Task

This request resets the expiration time of the BlockingTask shown in “Example: Handling a Blocking Task,”
on page 390 to ten minutes after the request is processed.

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<BlockingTaskUpdateProgressParams
xmlns="[Link]
<Message>Giving you ten more minutes...</Message>
<TimeoutValueInMilliseconds>600000</TimeoutValueInMilliseconds>
</BlockingTaskUpdateProgressParams>

The response includes the entire BlockingTask and shows the new value of the timeoutDate attribute. The
value assumes that the request was made at time 2011-05-11T[Link]. This example omits most of the
response.

Response:

200 OK
Content-Type: application/[Link]+xml
...
<vmext:BlockingTask
xmlns:vmext="[Link]
xmlns:vcloud="[Link]

392 VMware, Inc.

Chapter 11 Configuring and Using Blocking Tasks and Notifications

status="active"
timeoutDate="2011-05-11T[Link].857+03:00"
...
</vmext:BlockingTask>

Notification Message Format

All messages that the vCloud Director AMQP service sends contain an AMQP routing key and a body
formatted as a JSON object or an XML Notification element.

The XML Notification element is defined in the vCloud API schema. The routing key format is defined by
the AMQP specification.

Routing Key Format

The routing key for a vCloud Director AMQP message has the following form:

[Link].subType1.subType2...subTypeN.[taskName]

Routing key components include:

operationSuccess A Boolean value denoting whether the operation that triggered the
notification succeeded or failed.

entity The object identifier of the object on which an operation, an event of type
com/vmware/vcloud/event/, triggered the notification. For more information
about object identifiers, see “Objects, References, and Representations,” on
page 12.

org The object identifier of the organization that owns the affected object.

user The object identifier of the user who made the request.

subType1-subTypeN Each subType is a single component of the event type name. See “Notification
Types,” on page 394.

taskName If entity is a task or blocking task, the task name is appended to the routing
key.

The following routing key, in which the object identifiers are truncated to save space, is an example of a
routing key that might have been created for a successful com/vmware/vcloud/event/vapp/create event:

[Link]

Notification Headers
The vCloud API defines these AMQP notification headers.

Table 11‑7. Notification Headers

Header Value

[Link] See “Notification Types,” on page 394.

[Link] The type of vCloud entity is associated with this

notification. For example, vm.

[Link] The object identifier of the object on which an operation, an

event of type com/vmware/vcloud/event/, triggered the
notification.

[Link] The object identifier of the organization that owns the

affected object.

[Link] The object identifier of the user who made the request.

VMware, Inc. 393

vCloud API Programming Guide for Service Providers

Table 11‑7. Notification Headers (Continued)

Header Value

[Link] A Boolean value denoting whether the operation that

triggered the notification succeeded or failed.

[Link] The object identifier of the task that triggered the

notification. This header is present only when a task is a
child of another task. Use it to correlate events across a set
of tasks.

[Link] The object identifier of the vCloud Director cell executing

the task that triggered the notification. Present only when
the [Link] header is present.

Example: Notification Message Format

Each notification message is delivered as both XML and JSON.

Important XML NotificationType is deprecated in favor of the JSON format. vCloud Director AMQP
notifications in XML format may be removed in a future release.

JSON notifications are published on an exchange created by vCloud Director with a name of the form
prefix.notifications20 where prefix is the value of the AmqpPrefix element in the system AmqpSettings.
XML notifications are published on the AMQP exchange specified in the system AMQP settings.

Here is an example of a message generated by a blocking task, formatted as a JSON object.

{
"eventId" : "a1440dd8-60ae-46c7-b216-44693bc00c90",
"type" : "com/vmware/vcloud/event/blockingtask/create",
"timestamp" : "2011-06-18T[Link].787+03:00",
"operationSuccess" : true,
"user" : "urn:vcloud:user:44",
"userName" : "Bob",
"org" : "urn:vcloud:org:70",
"orgName" : "Finance",
"entity" : "urn:vcloud:blockingTask:25",
"entityName" : "vdcComposeVapp",
"entityType" : "[Link]",
"taskOwner" : "urn:vcloud:vapp:26"
}

To get more information about the blocking task that generated the notification, a system administrator use
the value of the entity key in a request to the entityResolver URL. See “Retrieve an Object as an Entity,” on
page 444.

This request retrieves the blocking task that generated this notification.

GET [Link]

The response to this request is identical to the one shown in the response portion of “Example: Handling a
Blocking Task,” on page 390.

Notification Types
The value of the type attribute of a vCloud Director notification is a string of the form
com/vmware/vcloud/event/object-type/event-type. Notification types can be grouped based on the object
type affected by the event.

394 VMware, Inc.

Chapter 11 Configuring and Using Blocking Tasks and Notifications

User, Group, Role, and Session Events

Table 11‑8. User, Group, Role, and Session Events
Type (com/vmware/vcloud/event/) Description

session/login A login session was created.

user/import A user was imported from LDAP.

user/remove An imported user was removed from the organization.

user/modify One or more properties of a user were modified.

user/lockout An account was locked based on the organization's

password policy settings.

user/unlock A locked account was unlocked.

user/lock_expired The lock on an account has expired.

user/create A local user was created in an organization.

user/delete A local user was removed from the organization.

group/import A group was imported from LDAP.

group/remove A group was removed from an organization.

role/create A new role was created.

role/modify An existing role was modified.

role/delete A role was deleted.

Organization, Network, Catalog, and VDC Events

Table 11‑9. Organization, Network, Catalog, and VDC Events
Type (com/vmware/vcloud/event/) Description

org/create An organization was created.

org/modify An organization was modified.

org/delete An organization was deleted.

network/create A network was created.

network/modify A network was modified.

network/delete A network was deleted.

network/deploy A network was deployed.

network/undeploy A network was undeployed.

catalog/create A catalog was created.

catalog/delete A catalog was deleted.

catalog/modify One or more properties of a catalog were modified

catalog/publish A catalog was published.

catalogItem/create An item was added to a catalog.

catalogItem/delete An item was removed from a catalog.

vdc/create_request A request to create a VDC was blocked pending

administrative action.

vdc/create A VDC was created.

vdc/modify One or more properties of a VDC was modified.

VMware, Inc. 395

vCloud API Programming Guide for Service Providers

Table 11‑9. Organization, Network, Catalog, and VDC Events (Continued)

Type (com/vmware/vcloud/event/) Description

vdc/delete_request A request to delete a VDC was blocked pending

administrative action.

vdc/delete A VDC was deleted.

vdc/fast_provisioning/modify The UsesFastProvisioning value of a VDC was

modified.

vdc/thin_provisioning/modify The IsThinProvision value of a VDC was modified.

vApp, vApp Template, Vm, and Media Events

Table 11‑10. vApp, vApp Template, Vm, and Media Events
Type (com/vmware/vcloud/event/) Description

vappTemplate/create A vApp template was created.

vappTemplate/import A virtual machine was imported from vSphere as a vApp

template.

vappTemplate/modify One or more properties of a vApp template were modified.

vappTemplate/delete A vApp template was deleted.

vappTemplate/create_request A request to create a vApp template was blocked pending

administrative action.

vappTemplate/import_request A request to import a vApp template was blocked pending

administrative action.

vappTemplate/modify_request A request to modify a vApp template was blocked pending

administrative action.

vappTemplate/delete_request A request to delete a vApp template was blocked pending

administrative action.

vapp/create A vApp was created (instantiated)

vapp/import A virtual machine was imported from vSphere as a vApp.

vapp/modify One or more properties of a vApp were modified.

vapp/delete A vApp was deleted.

vapp/deploy A vApp was deployed.

vapp/undeploy A vApp was undeployed.

vapp/runtime_lease_expiry The runtime lease of a vApp has expired.

vapp/create_request A request to instantiate a vApp template was blocked

pending administrative action.

vapp/import_request A request to import a vApp was blocked pending

administrative action.

vapp/modify_request A request to modify a vApp was blocked pending

administrative action.

vapp/delete_request A request to delete a vApp was blocked pending

administrative action.

vapp/deploy_request A request to deploy a vApp was blocked pending

administrative action.

vapp/undeploy_request A request to undeploy a vApp was blocked pending

administrative action.

vm/create_request A request to create a virtual machine was blocked pending

administrative action.

396 VMware, Inc.

Chapter 11 Configuring and Using Blocking Tasks and Notifications

Table 11‑10. vApp, vApp Template, Vm, and Media Events (Continued)
Type (com/vmware/vcloud/event/) Description

vapp/quarantine_reject An uploaded OVF was rejected after quarantine.

vapp/upload_timeout An OVF upload has timed out.

vapp/lease_expiration_changed The lease expiration of a vApp has changed.

vm/ip_address_changed The IP address of a virtual machine has changed.

vm/create A virtual machine was created by instantiating a vApp.

vm/modify_request A request to modify a virtual machine was blocked

pending administrative action.

vm/modify One or more properties of a virtual machine were

modified.

vm/delete A virtual machine was deleted.

vm/change_state The power state of a virtual machine has changed.

vm/deploy_request A request to deploy a virtual machine was blocked

pending administrative action.

vm/deploy A virtual machine was deployed.

vm/undeploy_request A request to undeploy a virtual machine was blocked

pending administrative action.

vm/undeploy A virtual machine was undeployed.

vm/consolidate_request A request to consolidate a virtual machine was blocked

pending administrative action.

vm/consolidate A virtual machine was consolidated.

vm/relocate_request A request to relocate a virtual machine was blocked

pending administrative action.

vm/relocate A virtual machine was relocated.

media/create A media object was created by upload or import.

media/import A media object was imported.

media/modify One or more properties of a media object were modified.

media/delete A media object was deleted.

media/create_request A request to create a media object was blocked pending

administrative action.

media/import_request A request to import a media object was blocked pending

administrative action.

media/modify_request A request to modify a media object was blocked pending

administrative action.

media/delete_request A request to delete a media object was blocked pending

administrative action.

media/upload_timeout A media upload has timed out.

media/quarantine_reject An uploaded media object was rejected after quarantine.

VMware, Inc. 397

vCloud API Programming Guide for Service Providers

Other System Events

Table 11‑11. Other System Events
Type (com/vmware/vcloud/event/) Description

providerVdc/create_request A request to create a provider VDC was blocked pending

administrative action.

providerVdc/create A provider VDC was created.

providerVdc/modify One or more properties of a provider VDC were modified.

providerVdc/delete_request A request to delete a provider VDC was blocked pending

administrative action.

providerVdc/delete A provider VDC was deleted.

vc/create A vCenter server was registered.

vc/modify One or more properties of a registered vCenter server were

modified.

vc/delete A registered vCenter server was registered.

task/create A task was created.

task/start A non-blocking task has started or a blocking task has

resumed.

task/abort A task was aborted.

task/complete A task has completed.

task/fail A task has failed.

task/update Task progress was updated.

blockingtask/create A task was blocked and a notification created.

blockingtask/resume A blocking task was resumed.

blockingtask/abort A blocking task was aborted.

blockingtask/fail A blocking task was failed.

datastore/modify One or more properties of a datastore object were

modified.

datastore/delete A datastore object was deleted.

398 VMware, Inc.

Extending vCloud Director 12
vCloud Director provides two extension mechanisms. Extension services can populate vCloud Director
objects with service-specific links. Object extensions can register interest in specific vCloud Director
operation and become part of the processing logic employed by those operations.

vCloud Director object extensions are similar to vCloud Director extension services in that both make use of
the same AMQP-based message-queuing mechanisms. But where extension services typically operate by
inserting service-specific links in vCloud Director objects, object extensions operate by registering interest in
one or more phases of a vCloud Director procedure such as vApp placement or instantiation and, using
information from the system, influencing the outcome of those processes in ways that reflect site-specific or
customer-specific requirements.

This chapter includes the following topics:

n “vCloud Director Object Extensions,” on page 399

n “vCloud Director Extension Services,” on page 409

vCloud Director Object Extensions

vCloud Director object extensions are external applications that can participate in, influence, or override the
logic that vCloud Director applies to workflows like vApp instantiation and placement.

An object extension can participate as a peer of the system in the logic that determines the outcome of these
workflows. For example, an object extension might use information provided by the system to place a VM
on a specific host or assign it a specific storage profile. Operation of object extensions is transparent to
system users. An extension can also allow the vCloud Director procedures in which it participates to run to
completion unmodified.

Object Extensibility Framework

vCloud Director object extensions are implemented in a framework that has three components:
n The vCloud API supports vCloud Director object extensions with two kinds of operations:
n Object registration requests, which register an object extension with the system.

n Selector extension requests, which select system objects to extend and specify the extension points
and execution phases in which the extension participates.

n Communication between the system and an object extension is handled using the system AMQP service
described in “Configure the vCloud Director AMQP Service,” on page 347. Extensions must create their
own exchanges.

VMware, Inc. 399

vCloud API Programming Guide for Service Providers

n Extension points themselves are defined in the system. When an object extension registers with
vCloud Director, it can specify one more of these extension points, expressed as a URN:

n urn:selector:providerVdc

n urn:selector:organizationVdc

n urn:selector:organization

An object extension that operates on a subset of these extension points can specify that subset at registration
to prevent it from being associated with extension points outside the subset. An object extension that
operates on all extension points does not need to specify any of them at registration.

All other operations are implemented by the extensions themselves, which read messages from their AMQP
exchange and provide responses, as AMQP messages, to vCloud Director.

For additional information and code examples, see VMware Sample Exchange at
[Link]

Extensibility Phases
Extensible operations are distinguished by having life cycle events such as create, update, and delete
mapped to an extensibility phas e. An object extension can participate in zero or more phases of an
extensible vCloud Director operation. Each phase is identified by a URN.

The system collects the internal information that it uses when executing a phase and sends it to the
extension as an AMQP message. If specified by the extension, the phase waits for a reply before proceeding
(see “Message Handling,” on page 401). By sending a reply that modifies values that the phase supplies, the
extension can affect the outcome of the phase. XML schema definition files for the messages sent by each
phase are available on the VMware Sample Exchange at [Link]

Each phase has an inherent cardinality that establishes the number of extensions that can participate in
phase operations. Some operations such as VM placement, which must take into account factors such as host
configuration, affinities, and storage capabilities, can accommodate participation by multiple extensions and
have a cardinality greater than 1. Others, such as creation of a VM, are not candidates for participation from
multiple extensions, and have a cardinality of exactly 1.

Table 12‑1. Extensibility Phases

Name Cardinality Timeout in Seconds Summary

urn:extensionPoint:vm:g 1-n 5 Gathers virtual machine placement

atherRequirements requirements, including CPU and memory
configurations, storage IOPS, and datastore
affinity and provides them to the extension

urn:extensionPoint:vm:c 1-n 60 Calculates a placement solution and provides

alculateSolution it to the extension

urn:extensionPoint:vm:c 1 60 Creates a virtual machine

reate

400 VMware, Inc.

Chapter 12 Extending vCloud Director

Message Handling
An object extension can specify how it wants to handle messages sent by a phase. Three types of message
handling are supported.

async async messages provide a stream of information as the system proceeds with
phase execution. Extensions that specify async message handling are
informed of phase operations but cannot influence the outcome of a phase.

blocking blocking messages force the execution of the phase to block until the
extension takes some action. Extensions that specify blocking message
handling must reply to each message within the specified timeout interval or
the system proceeds with the operation.

needsApproval needsApproval messages force the execution of the phase to block until
approved by a system administrator.

Selector Associations and Extension Policies

When it creates a SelectorExtension, an object extension can express interest in all objects of a certain type,
or in a specific object. An object extension that selects an object type affects all instances of that type. Object
extensions that select an object instance affect only that instance, and override the operations of any
extension that might be in place for that instance's type.

Selector extension request URLs have one of the following forms, where type is one of:

n providervdcs

n vdcs

n orgs

In this table:

n API-URL is a URL of the form [Link]

n id is a unique identifier in the form of a UUID, as defined by RFC 4122.

Table 12‑2. Selector Extension Request URLs

HTTP
Verb Request URL Prototype Summary

GET API-URL/admin/type/extension Retrieve all extensions that are associated with the default
selector policy for type.

POST API-URL/admin/type/extension Add a selector extension to the default policy for type.

GET API-URL/admin/type/extension/extension-ID Retrieve extension extension-ID associated with the default

selector policy for type.

PUT API-URL/admin/type/extension/extension-ID Update extension extension-ID associated with the default

selector policy for type.

DELETE API-URL/admin/type/extension/extension-ID Delete extension extension-ID from the default selector

policy for type.

GET API-URL/admin/type/selector-ID/extension/ Retrieve all extensions associated with the specified

selector-ID and type.

POST API-URL/admin/type/selector-ID/extension/ Add a selector extension to the specified selector-ID to

update the default selector policy for type.

VMware, Inc. 401

vCloud API Programming Guide for Service Providers

Extension Workflow
A typical extension implements a workflow similar to this one:

1 Use the vCloud API to create an extension-specific exchange on the system AMQP service. See
“Configure the vCloud Director AMQP Service,” on page 347.

2 Set up a listener for that exchange.

3 Use the vCloud API to register with the system. See “Register an Object Extension,” on page 402.

4 Use the vCloud API to create one or more selector extensions for specific objects or types of objects. See
“Create a Selector Extension,” on page 405.

5 Listen on the AMQP exchange for messages from extension points, and take appropriate actions. For
example:

n Reply to the extension point with a message that modifies some of the values included in a
previous message

n Use the vCloud API to create or update objects based on the results of message analysis or
processing

An extension continues handling the stream of messages from extension points if the system or the
extension is active.

Register an Object Extension

Register an object extension to specify its namespace, vendor, and AMQP exchange name.

An object extension typically authenticates with the vCloud API as a system administrator, then registers
with vCloud Director by POSTing an ObjectExtension element to the
system's .../api/admin/extension/object URL. An ObjectExtension element must include the following
elements.

Namespace The object extension namespace.

Vendor The object extension vendor.

Important The combination of Namespace and Vendor must be unique

among all extension services and object extensions registered in the system.
If a service tries to register an object extension that specifies a Namespace and
Vendor that are already registered with this vCloud Director installation,
registration fails. Vendor and namespace names that follow the naming
convention used for Java packages are more likely to be unique.

Selectors Zero or more Selector elements that specify the extension points in which
the extension has an interest. If you register an object extension with no
Selectors, the system assumes that the extension is interested in all
extension points.

Exchange The AMQP exchange name that vCloud Director must use when routing
messages to the extension. The extension must create the specified exchange
on the AMQP service that vCloud Director uses. The exchange type must be
direct. Exchange names must be globally unique.

Prerequisites
This operation is restricted to system administrators.

402 VMware, Inc.

Chapter 12 Extending vCloud Director

Procedure
1 Retrieve the XML representation of the cloud.

Use a request like this one:

GET [Link]

2 Examine the response to find the Link for adding object extensions.

This Link is present in the VMWExtension element, and has the following form.

<vcloud:Link
rel="add"
href="[Link]
type="application/[Link]+xml" />

3 Construct an ObjectExtension element.

See the request portion of “Example: Register an Object Extension,” on page 403.

4 POST the ObjectExtension element to the URL described in Step 2.

See the request portion of “Example: Register an Object Extension,” on page 403.

Example: Register an Object Extension

This example registers an object extension for the providerVdc extension point but does not enable it. The
example assumes that an AMQP exchange named example-exchange has been created.

Request:

POST [Link]
Content Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<ObjectExtension
xmlns="[Link]
xmlns:vcloud_v1.5="[Link]
<Namespace>[Link]</Namespace>
<Enabled>false</Enabled>
<Exchange>example-exchange</Exchange>
<Vendor>[Link]</Vendor>
<Selectors>
<Selector name="urn:selector:providerVdc" />
</Selectors>
</ObjectExtension>

The system registers the extension and returns an ObjectExtension element that includes information
derived from the contents you POSTed, and a set of Link elements that you can use to access or modify the
new object extension. The AMQP message ContentType, which was not specified in the request, is returned
with the default value, XML.

Response:

201 Created
Content Type: application/[Link]+xml
...

<vmext:ObjectExtension
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
id="83...0d39"

VMware, Inc. 403

vCloud API Programming Guide for Service Providers

href="[Link] >
<vcloud:Link
rel="up"
href="[Link]
type="application/[Link]+xml" />
<vcloud:Link
rel="remove"
href="[Link]
type="application/[Link]+xml" />
<vcloud:Link
rel="edit"
href="[Link]
type="application/[Link]+xml" />
<vcloud:Link
rel="down"
href="[Link]
type="application/[Link]+xml" />
<vmext:Namespace>example-object</vmext:Namespace>
<vmext:Enabled>false</vmext:Enabled>
<vmext:Exchange>example-exchange</vmext:Exchange>
<vmext:ContentType>XML</vmext:ContentType>
<vmext:Vendor>[Link]</vmext:Vendor>
<vmext:Selectors>
<vmext:Selector name="urn:selector:providerVdc" />
</vmext:Selectors>
</vmext:ObjectExtension>

Retrieve or Update an Object Extension

You can update an object extension registration by making a PUT request to its edit URL and supplying a
modified an ObjectExtension in the request body.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the object extension.
Use a request like this one, where ID is the ID of the extension that you want to retrieve.

GET [Link]

If you do not know the ID of the object extension, you can retrieve a list of all registered object
extensions with a request like this one:

GET [Link]

2 Examine the response to find the object extension's edit link.

<vcloud:Link
rel="edit"
href="[Link]
type="application/[Link]+xml" />

3 Update the retrieved ObjectExtension.

4 Make a PUT request to the URL in the edit link, supplying the modified ObjectExtension in the request
body. See “Example: Update an Object Extension,” on page 405

404 VMware, Inc.

Chapter 12 Extending vCloud Director

Example: Update an Object Extension

This example updates the object extension created in “Example: Register an Object Extension,” on page 403
to enable it by setting the value of Enabled to true.

Request:

PUT [Link]
Content Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<ObjectExtension
xmlns="[Link]
xmlns:vcloud_v1.5="[Link]
<Namespace>[Link]</Namespace>
<Enabled>true</Enabled>
<Exchange>example-exchange</Exchange>
<Vendor>[Link]</Vendor>
<Selectors>
<Selector name="urn:selector:providerVdc" />
</Selectors>
</ObjectExtension>

The system updates the extension and returns an updated ObjectExtension element similar to the one
shown in “Example: Register an Object Extension,” on page 403.

Response:

200 OK
Content Type: application/[Link]+xml
...
<vmext:ObjectExtension
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
id="83...0d39"
href="[Link] >
...
<vmext:Namespace>example-object</vmext:Namespace>
<vmext:Enabled>true</vmext:Enabled>
<vmext:Exchange>example-exchange</vmext:Exchange>
<vmext:ContentType>XML</vmext:ContentType>
<vmext:Vendor>[Link]</vmext:Vendor>
...
</vmext:ObjectExtension>

Create a Selector Extension

A selector extension associates a registered object extension with one or more of the phases of an extensible
object type.

Associating a selector extension with an object type or instance and registered object extension enables the
object extension to receive messages when an operation on the type or instance reaches an extensible phase
of its execution. A selector extension can be associated with one or more object extensions.

Prerequisites
This operation is restricted to system administrators.

VMware, Inc. 405

vCloud API Programming Guide for Service Providers

You must provide the ID of a registered object extension as part of the request to create a selector extension.
That ID is returned when you create the object extension. If you don't know the ID of the object extension,
you can retrieve a list of all registered object extensions with a request like this one:

GET [Link]

Procedure
1 Construct an ObjectExtension element.

The ObjectExtensionId element in the request must specify the ID of the object extension for which you
are creating this selector extension. See the request portion of “Example: Create a Selector Extension for
a Registered Object Extension,” on page 406.

2 POST the ObjectExtension element to the URL for the object that you wish to extend.

The URL can refer to a specific object or all objects of a certain type. See the request portion of
“Example: Create a Selector Extension for a Registered Object Extension,” on page 406.

Example: Create a Selector Extension for a Registered Object Extension

This example adds a selector extension to the object extension registered in “Example: Register an Object
Extension,” on page 403. This request is appropriate for an extension that must gather and analyze Provider
VDC requirements associated with the creation of a virtual machine, but not influence the operation of the
phase. The selector specifies the urn:extensionPoint:vm:gatherRequirements phase and async execution, so
the system does not block awaiting a response. Because the phase has an optional attribute with a value of
true phase execution continues even if the extension fails.

If the extension is to influence the outcome of the phase by replying with modified requirements, it must set
type to blocking and be prepared to reply within the specified time-out interval.

In this example, the selector extension sets Priority to 1. The system uses the Priority value to control the
order of execution when multiple extensions have registered interest in a phase. Note that a Priority of 1
does not always mean that the extension is called first. For some extensions, such as those that select the
urn:extensionPoint:vm:calculateSolution phase and affect placement, the highest priority position in the
execution order is the final one. This approach ensures that any placement solution offered by the extension
cannot be superseded by a solution offered by a different extension.

A request like this one sets this SelectorExtension as the default extension policy for all Provider VDCs in
the system.

Request:

POST [Link]
Content Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<SelectorExtension
xmlns="[Link] >
<Enabled>false</Enabled>
<Priority>1</Priority>
<ObjectExtensionId>83...0d39</ObjectExtensionId>
<Phases>
<Phase
name="urn:extensionPoint:vm:gatherRequirements"
type="async"
optional="true" />
</Phases>
</SelectorExtension>

406 VMware, Inc.

Chapter 12 Extending vCloud Director

To apply this policy to a single Provider VDC, use a request of the following form:

POST [Link]

The system creates the selector extension and returns a SelectorExtension element that includes
information derived from the contents you POSTed, and a set of Link elements that you can use to access or
modify the new object extension.

Response:

201 Created
Content Type: application/[Link]+xml
...
<SelectorExtension
xmlns="[Link]
id="b3...f8ee"
href="[Link]
... >
<Link
rel="remove"
href="[Link] />
<Link
rel="edit"
href="[Link]
type="application/[Link]+xml" />
<Link
rel="up"
href="[Link]
type="application/[Link]+xml" />
<Enabled>false</Enabled>
<Priority>1</Priority>
<ObjectExtensionId>83...0d39</ObjectExtensionId>
<Phases>
<Phase
name="urn:extensionPoint:vm:gatherRequirements"
optional="true"
type="ASYNC" />
</Phases>
</SelectorExtension>

The selector extension is added to the set of selector extensions associated with the specified object
extension. You can retrieve a list of those selector extensions with a request to the object extension's
[Link] link.

GET [Link]
...
<SelectorExtension
xmlns="[Link]
id="b3...f8ee"
href="[Link] ...>
...
</SelectorExtension>

VMware, Inc. 407

vCloud API Programming Guide for Service Providers

Retrieve or Update a Selector Extension

You can update a selector extension by making a PUT request to its edit URL and supplying a modified
SelectorExtension in the request body.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the selector extension.

Use a request like this one, where ID is the ID of the extension that you want to retrieve.

GET [Link]

2 Examine the response to find the object extension's edit link.

<vcloud:Link
rel="edit"
href="[Link]
type="application/[Link]+xml" />

3 Update the retrieved SelectorExtension.

4 Make a PUT request to the URL in the edit link, supplying the modified SelectorExtension in the
request body. See “Example: Update a Selector Extension,” on page 408

Example: Update a Selector Extension

This example updates the selector extension created in “Example: Create a Selector Extension for a
Registered Object Extension,” on page 406 to enable it by setting the value of Enabled to true.

Request:

PUT [Link]
Content Type: application/[Link]+xml
...
Content Type: application/[Link]+xml
<?xml version="1.0" encoding="UTF-8"?>
<SelectorExtension
xmlns="[Link] >
<Enabled>true</Enabled>
<Priority>1</Priority>
<ObjectExtensionId>83...0d39</ObjectExtensionId>
<Phases>
<Phase
name="urn:extensionPoint:vm:gatherRequirements"
type="async"
optional="true" />
</Phases>
</SelectorExtension>

The system updates the extension and returns an updated SelectorExtension element similar to the one
shown in “Example: Create a Selector Extension for a Registered Object Extension,” on page 406.

408 VMware, Inc.

Chapter 12 Extending vCloud Director

Response:

200 OK
Content Type: application/[Link]+xml
...
<SelectorExtension
xmlns="[Link]
id="b3...f8ee"
href="[Link]
... >
<Link
rel="remove"
href="[Link] />
<Link
rel="edit"
href="[Link]
type="application/[Link]+xml" />
<Link
rel="up"
href="[Link]
type="application/[Link]+xml" />
<Enabled>true</Enabled>
<Priority>1</Priority>
<ObjectExtensionId>83...0d39</ObjectExtensionId>
<Phases>
<Phase
name="urn:extensionPoint:vm:gatherRequirements"
optional="true"
type="ASYNC" />
</Phases>
</SelectorExtension>

vCloud Director Extension Services

vCloud Director and the vCloud API include a framework for integration of extension services that a
vCloud API client can access as though they were native services. In addition to service-specific objects or
operations they provide, extension services can implement new operations for existing API objects.
A vCloud Director extension service is a program that presents a REST interface to vCloud API clients.
When you register an extension service with the vCloud API, you specify one or more URL patterns that the
vCloud Director REST service treats as extension requests. When it receives an extension request, the
vCloud Director REST service creates an AMQP notification with a service-specific exchange and routing
key, and sends it to the vCloud Director AMQP service. Each extension service subscribes to AMQP
notifications that have its service-specific routing key. A service processes its notifications, takes whatever
actions they require, and returns a response to the AMQP service, where the vCloud Director REST service
retrieves it and uses its contents to generate a response to the client that made the request.

Message Routing
Extension services use the vCloud Director AMQP service to communicate with vCloud Director. Every
extension service must register a unique AMQP routing key, which vCloud Director prepends to AMQP
messages destined for that service. To collect replies from services, vCloud Director creates a single reply
exchange for all services, creates a separate reply queue for each cell, and binds each of those queues to the
reply exchange.

VMware, Inc. 409

vCloud API Programming Guide for Service Providers

vCloud Director extension services can also be vCloud API clients, authenticating to the vCloud API and
making their own REST requests to the vCloud API URL. This type of interaction is required when creating
tasks and events that track the progress of requests made to the service. It is also required by services that
operate on vCloud Director objects like vApps and virtual machines.

Creating Events and Tasks

The vCloud API extension framework implements operations that allow an extension service to create and
update an organization's lists of tasks and events, so the status of asynchronous events running in extension
services can be displayed with the same kinds of information posted by native services.

Authorization Framework
All requests to extension services are processed through the vCloud Director authentication framework. A
user making a request to an extension service must be authenticated by vCloud Director as a system
administrator or a member of a vCloud Director organization.

An extension service can add service-specific rights and associate those rights with operations on its own
objects or with operations it adds to vCloud API objects .

Service APIs
An extension service can define its own request and response body elements if it needs to. API schema files
can be specified as part of service registration or can be added later. Schema files can reside at any location
that is reachable by the extension service.

Support for Idempotent Operations

Most requests to extension services can include an operationKey attribute, which is a string meant to
uniquely identify the operation so that if it is invoked multiple times, the result will be the same as if it had
been invoked only once. The following types support use of the operationKey attribute:

n AclRuleType

n ApiDefinitionType

n ApiFilterType

n FileDescriptorType

n ResourceClassActionType

n ResourceClassType

n ServiceLinkType

n ServiceResourceType

n ServiceType

410 VMware, Inc.

Chapter 12 Extending vCloud Director

Register an Extension Service

Register an extension service to specify its namespace, AMQP exchange and routing key, and URL patterns.
You can specify additional service properties during registration or update them later.

An extension service typically authenticates with the vCloud API as a system administrator, then registers
itself with vCloud Director by POSTing a Service element to the system's .../api/admin/extension/service
URL. A Service element must include the following elements.

Namespace The service namespace, which must be unique among all registered
extension services. Service namespace names that follow the naming
convention used for Java packages (for example,
[Link]) are more likely to be unique. If a service tries
to register a namespace that is already registered with this vCloud Director
installation, registration fails.

RoutingKey The AMQP routing key that vCloud Director must use when routing
messages to the service.

Exchange The AMQP exchange name that vCloud Director must use when routing
messages to the service. The service must create the specified exchange on
the AMQP service that vCloud Director uses. The exchange type must be
direct.

ApiFilters Specifies one or more URL patterns that the vCloud Director REST service
must treat as extension requests. URL patterns can include regular
expressions that [Link] recognizes. See “Create an API
Filter for an Extension Service,” on page 433.

Registration can also specify the following optional properties:

n Definitions of Link elements that the service adds to the representations of vCloud API objects. See
“Service-Specific Links,” on page 414.

n Authorization framework for controlling access to the service's objects and operations. See
“Authorization Framework for Extension Service Operations,” on page 421.

n Locations of schema files if the service provides its own API. See “REST APIs for Extension Services,”
on page 432

You can also create or update these properties after you register the service.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the cloud.

Use a request like this one:

GET [Link]

2 Examine the response to find the Link for adding extension services.

This URL is present in the VMWExtension element, and has the following form.

<vcloud:Link
rel="down"
type="application/[Link]+xml"
href="[Link]

VMware, Inc. 411

vCloud API Programming Guide for Service Providers

3 Construct a Service element.

See the request portion of “Example: Register an Extension Service,” on page 412.

4 POST the Service element to the URL described in Step 2.

See the request portion of “Example: Register an Extension Service,” on page 412.

Example: Register an Extension Service

This request registers an extension service named SDK-BackupExtension. The request specifies the service
namespace and routing key, and several URL patterns to be used as API filters. Messages for the service are
sent to the AMQP exchange named sdkext with routing key sdkbackup.

Note If the specified exchange does not exist on the AMQP service that vCloud Director uses, an internal
server error occurs whenever vCloud Director receives a request that matches one of the service's API filters.

This request also includes several ServiceLink elements. For information about the contents of these
elements, see “Service-Specific Links,” on page 414.

Request:

POST [Link]
Content Type: application/[Link]+xml
<?xml version="1.0" encoding="UTF-8"?>
<vmext:Service
xmlns="[Link]
xmlns:vmext="[Link]
name="SDK-BackupExtension">
<vmext:Namespace>[Link]</vmext:Namespace>
<vmext:Enabled>true</vmext:Enabled>
<vmext:AuthorizationEnabled>true</vmext:AuthorizationEnabled>
<vmext:RoutingKey>backup</vmext:RoutingKey>
<vmext:Priority>50</vmext:Priority>
<vmext:Exchange>sdkext</vmext:Exchange>
<vmext:ApiFilters>
<vmext:ApiFilter>
<vmext:UrlPattern>(/api/org/.*/backups)|(/api/vApp/vapp-.*/backups)|
(/api/vApp/vapp-.*/action/backup)|(/api/backup/.*)</vmext:UrlPattern>
</vmext:ApiFilter>
</vmext:ApiFilters>
<vmext:ServiceLinks>
<vmext:ServiceLink>
<vmext:LinkHref>{baseUri}org/{resourceId}</vmext:LinkHref>
<vmext:MimeType>application/[Link]+xml</vmext:MimeType>
<vmext:Rel>down</vmext:Rel>
<vmext:ResourceType>application/[Link]+xml</vmext:ResourceType>
</vmext:ServiceLink>
<vmext:ServiceLink>
<vmext:LinkHref>{baseUri}api/vApp/vapp-{resourceId}/backups</vmext:LinkHref>
<vmext:MimeType>application/[Link]+xml</vmext:MimeType>
<vmext:Rel>down</vmext:Rel>
<vmext:ResourceType>application/[Link]+xml</vmext:ResourceType>
</vmext:ServiceLink>
<vmext:ServiceLink>
<vmext:LinkHref>{baseUri}vApp/vapp-{resourceId}/action/backup</vmext:LinkHref>
<vmext:MimeType>application/[Link]
+xml</vmext:MimeType>

412 VMware, Inc.

Chapter 12 Extending vCloud Director

<vmext:Rel>backup</vmext:Rel>
<vmext:ResourceType>application/[Link]+xml</vmext:ResourceType>
</vmext:ServiceLink>
</vmext:ServiceLinks>
</vmext:Service>

The server registers the service and returns a Service element that includes information derived from the
contents you POSTed, and a set of Link elements that you can use to access, remove, disable, or modify the
extension service.

Response:

201 Created
Content Type: application/[Link]+xml
...
<vmext:Service
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
name="SDK-BackupExtension"
id="urn:vcloud:externalService:45"
type="application/[Link]+xml"
href="[Link]
... >
<vcloud:Link
rel="remove"
href="[Link] />
<vcloud:Link
rel="edit"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="rights"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="down:serviceLinks"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="bundle:upload"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="add"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="down:apiFilters"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="add"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="add"
type="application/[Link]+xml"

VMware, Inc. 413

vCloud API Programming Guide for Service Providers

href="[Link] />
<vcloud:Link
rel="down:apiDefinitions"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="add"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="down:resourceClasses"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="authorization:check"
type="application/[Link]+xml"
href="[Link] />
...
</vmext:Service>

The following elements are never returned as part of a response body. Instead, they are returned as Link
elements in the body of their container.

n AclRules

n ApiDefinitions and Files

n ApiFilters

n ResourceClassActions

n ResourceClasses

n ServiceLinks

n ServiceResources

For example, to retrieve the contents of the ServiceLinks element POSTed with the request body in this
example, GET the URL in this Link:

<vcloud:Link
rel="down:serviceLinks"
type="application/[Link]+xml"
href="[Link] />

Service-Specific Links
A service can add its own Link elements to the representations of vCloud API objects. You can create these
service links when you register a service. You can also add or remove the links after you register the service.

You can create multiple service-specific links as part of registering a service. After you register a service, you
can add or remove individual links. Service links typically appear in the representations of all objects of a
specific type, but you can constrain them to appear in a particular object of that type. Service links are not
included in object representations unless the service that created them is enabled.

Note You cannot update a service link, but you can remove existing links and create new ones.

414 VMware, Inc.

Chapter 12 Extending vCloud Director

Add a Service Link

You can add a service link to an existing service.

A ServiceLink element must contain the following child elements:

LinkHref The value of href attribute of the Link. This can be any URI, and can include
the variables {baseUri} and {resourceId}. When constructing the href value
of the Link, vCloud Director replaces {baseUri} with the vCloud Director
REST API base URL, and replaces {resourceId} with the UUID portion of
the id attribute value of the resource in which the Link is inserted. The
following example might expand to the string
[Link]

<LinkHref>
{baseUri}/org/{resourceId}
</LinkHref>

MimeType The value, specified as a MIME content type, of the type attribute of the Link.

Rel Defines the relationship of the link to the object that contains it. A
relationship can be the name of an operation on the object, a reference to a
contained or containing object, or a reference to an alternate representation of
the object. The relationship value implies the HTTP verb to use when you use
the link's href value as a request URL.

ResourceType The object type, specified as a MIME content type, of the object in which the
Link appears.

Note You can constrain the Link to appear in a specific resource by including a ResourceId element in the
ServiceLink. This element contains the id of the resource in which the Link will appear. This resource must
be of the type specified in the ResourceType element of the ServiceLink.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the service.
This request retrieves the XML representation of the service created in “Example: Register an Extension
Service,” on page 412:

GET [Link]

2 Examine the response to find the Link for adding service links.

This Link has the following form:

<vcloud:Link
rel="add"
type="application/[Link]+xml"
href="[Link] />

3 Create a ServiceLink element that specifies the properties of the new link.

4 POST the ServiceLink element to the URL described in Step 2

See “Example: Add a Service Link,” on page 416.

VMware, Inc. 415

vCloud API Programming Guide for Service Providers

Example: Add a Service Link

This request adds a ServiceLink to the service created in “Example: Register an Extension Service,” on
page 412

Request:

POST [Link]
Content-type: application/[Link]+xml
<?xml version="1.0" encoding="UTF-8"?>
<vmext:ServiceLink
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
type="application/[Link]+xml">
<vmext:LinkHref>{baseUri}vApp/vapp-{resourceId}/action/deleteBackup</vmext:LinkHref>
<vmext:MimeType>application/[Link]+xml</vmext:MimeType>
<vmext:Rel>deleteBackup</vmext:Rel>
<vmext:ResourceType>application/[Link]+xml</vmext:ResourceType>
</vmext:ServiceLink>

Response:

200 OK
Content-type: application/[Link]+xml
...
<vmext:ServiceLink ...>
...
</vmext:ServiceLink>

Delete a Service Link

Delete a service link when you no longer want it to appear in the representation of an vCloud API objects, or
when you want to replace it with a new service link.

When you retrieve the list of service links associated with a service, the response is a QueryResultRecords
element in which each service link is represented as a ServiceLinkRecord element. The value of the href
attribute of a ServiceLinkRecord is a URL you can use to retrieve or delete the service link.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the service.

This request retrieves the XML representation of the service created in “Example: Register an Extension
Service,” on page 412:

GET [Link]

2 Examine the response to find the Link for listing service links.

This Link has the following form:

<vcloud:Link
rel="down:serviceLinks"
type="application/[Link]+xml"
href="[Link] />

3 Make a GET request to the link described in Step 2.

4 Examine the response to find the ServiceLinkRecord that represents the service link to delete.

416 VMware, Inc.

Chapter 12 Extending vCloud Director

5 Make a DELETE request to the URL in the href attribute value of that ServiceLinkRecord.

Example: Delete a Service Link

Start by getting the service's list of service links.
Request:

GET [Link]

Response:

<?xml version="1.0" encoding="UTF-8"?>

<QueryResultRecords
total="3"
pageSize="25"
page="1"
name="serviceLink"
type="application/[Link]+xml"
... >
...
<ServiceLinkRecord
service="[Link]
resourceType="application/[Link]+xml"
rel="down"
mimeType="application/[Link]+xml"
linkHref="{baseUri}api/vApp/vapp-{resourceId}/backups"
href="[Link] />
<ServiceLinkRecord
service="[Link]
resourceType="application/[Link]+xml"
rel="down"
mimeType="application/[Link]+xml"
linkHref="{baseUri}org/{resourceId}"
href="[Link] />
<ServiceLinkRecord
service="[Link]
resourceType="application/[Link]+xml"
rel="backup"
mimeType="application/[Link]+xml"
linkHref="{baseUri}vApp/vapp-{resourceId}/action/backup"
href="[Link] />
</QueryResultRecords>

Note Link id values are truncated in this example.

Using this information, find the ServiceLinkRecord that represents the service link you want to delete, and
make a DELETE request to that URL.

DELETE [Link]

VMware, Inc. 417

vCloud API Programming Guide for Service Providers

Service-Specific Tasks and Events

An extension service can create Task objects in a vCloud Director organization, and can post events to the
organization's event stream.

Tasks and events are created in the context of an organization. Each task or event is associated with exactly
one user, who must be a system administrator or a member of the organization in which the task or event is
created. Tasks and events can also have an owner, which is a reference to the subject of the task or event (for
example, an object being created or updated by a task).

Task and Event Workflow

vCloud Director native services typically create Task objects to track the progress of asynchronous events.
These objects are returned to clients as Task elements, which can be embedded in a container that represents
an object under construction, or simply returned in Task form.

Tasks are also reported in the organization's event stream. A service can also add its own events to this
stream, in addition to the ones added as a side-effect of creating a task.

Extension services act as vCloud API clients when creating tasks and events, even if those tasks and events
are created to track service-specific objects or operations. After a task is created in vCloud Director, an
extension service can use its AMQP connection to vCloud Director to return a Task as the response, or part
of the response, to a client request.

Localizing Task and Event Message Content

Message strings included in tasks and events can be localized. See “Localization Framework for Extension
Services,” on page 429.

Create or Update a Service-Specific Task

When a user requests an asynchronous operation from an extension service, the service can create a task
object and add it to an organization's tasks list.

Every vCloud Director organization has a tasks list and accepts requests to add a task to the list. When a
client requests an asynchronous operation from a service, the service starts to process the request and also
POSTs a Task element to the organization's tasksList URL. vCloud Director adds information such as an id
and startTime to the Task, places it on the organization's TasksList, creates an event in the organization's
event stream, and returns the Task to the service. The service can then send the Task, as an AMQP message,
to vCloud Director, which sends it as a response to the client that made the original request.

Note Because of the diversity of sources from which an extension service can draw references to the User,
Owner, and Organization elements of a Task, it may not always be possible for every client to resolve such
references. For example, if a service creates an object in an organization of which you are not a member, you
will not be able to resolve the reference to the object in the Owner element of the Task.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the organization in which you want to create the Task.

Use a request like this one:

GET [Link]

418 VMware, Inc.

Chapter 12 Extending vCloud Director

2 Examine the response to locate the Link element that contains the URL for adding tasks to the
organization's tasks list.

This element has a rel attribute value of task:create and a type attribute value of
application/[Link]+xml, as shown here:

<Link
rel="task:create"
type="application/[Link]+xml"
href="[Link] />

3 Create a Task element that specifies the details of the task.

4 POST the Task element to the organization's tasksList URL.

The server creates a task object and adds it to the organization's tasks list, and returns the representation of
the object to the service. To return the XML representation of the task object to the client that made the
original request, the service must create a JSON representation of the Task and return it to vCloud Director
AMQP service.

Example: Add a Task to an Organization's Tasks List

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Task
xmlns="[Link]
status="running"
serviceNamespace="[Link]"
type="application/[Link]+xml"
operation="Backup in progress for virtual machine with id 7b91b053-2b..."
operationName="backupInProgress"
name="task">
<Owner
type="application/[Link]+xml"
name="Finance"
href="[Link]
id="26" />
<User
type="application/[Link]+xml"
name="bob"
href="[Link] />
<Progress>10</Progress>
</Task>

Response:

200 OK
Content-Type: application/[Link]+xml
...
<Task
href="[Link]
...
operationName="backupInProgress"
... >
...
</Task>

VMware, Inc. 419

vCloud API Programming Guide for Service Providers

Create a Service-Specific Event

An extension service can request that vCloud Director add an event message to the event stream of an
organization.

The system always creates an event message when a service posts a Task to an organization's tasks list. To
create additional event messages, a service can POST an Event element to an organization's events URL.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the organization in which you want to create the event.

Use a request like this one:

GET [Link]

2 Examine the response to locate the Link element that contains the URL for adding events to the
organization's events stream.

This element has a rel attribute value of event:create and a type attribute value of
application/[Link]+xml, as the following example shows:

<Link
rel="event:create"
type="application/[Link]"
href="[Link] />

3 Create an Event element that specifies the details of the task.

4 POST the Event element to the organization's events URL.

Example: Add an Event to an Organization's Event Stream

Request:

POST [Link]
Content-Type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Event
success="true"
serviceNamespace="[Link]"
type="backupComplete">
<Owner
type="application/[Link]+xml"
name="Finance"
href="[Link] />
<User
type="application/[Link]+xml"
name="bob"
href="[Link] />
</Event>

Response:

204 No Content

420 VMware, Inc.

Chapter 12 Extending vCloud Director

Authorization Framework for Extension Service Operations

All requests to extension services must be authenticated through the vCloud API. Extension services can
participate in vCloud API REST authorization by controlling access to their objects and operations through
new or existing rights and roles.

An extension service that does not enable the use of vCloud Director REST authorization implicitly grants
permission for all users to perform all operations that the service uses. A service can use the native
vCloud Director REST authorization model by taking the following steps:

1 Define resource classes that represent references to service-specific object types.

2 Define resource class actions that specify the actions that are implemented for those object types.

3 Define ACL rules specifying the rights required to perform an operation on objects of a specific type.

Participation in the Authorization Framework

To participate in the authorization framework, a service must include an AuthorizationEnabled element
with a value of true in its registration request.

<vmext:AuthorizationEnabled>true</vmext:AuthorizationEnabled>

It must also define at least one resource class, specify at least one action for that class, and define an ACL
rule that constrains use of the action on the class.

Resource Classes and Actions

A service uses the following constructs to define the objects, operations, and permissions that constitute its
authorization model.

Resource Classes Set of rules for creating references to service-specific objects. Like other object
references in the vCloud API, resource classes are a Link element that
specifies the MIME type of the resource and includes an href (URL) that can
be used to retrieve the resource. The rules include a MIME type, a URL
pattern, and a template for creating an id attribute value in URN form.

Resource Class Actions Combination of a URL pattern that specifies a resource class and an HTTP
method that implements an action on a resource of that class. The action uses
the specified method in a request to a URL that matches the specified pattern.

ACL Rules Specifies the rights that an organization or user have to an operation defined
as a resource class action.

Service Resource A member of a resource class distinguished by a specific id. If an extension

service needs to define a resource class action or an ACL rule that applies to
a specific resource, the service must create it as a ServiceResource and give it
a UUID or other unique identifier.

Querying for Organization and User Rights

The vCloud API query service implements several queries that return a list of rights that a specified user or
organization is granted. A user can make a request that specifies one or more entity references and returns a
summary of user rights to the specified entities.

VMware, Inc. 421

vCloud API Programming Guide for Service Providers

Create an Extension Service Resource Class

To configure your extension service to provide access control for the objects it creates, define a resource class
for each of its object types.

A ResourceClass element contains the information needed to construct a URL that a client can use to access
the resource in a specific context. It must contain the following child elements:

MimeType The MIME content type of all instances of the resource class.

UrlTemplate The value of href attribute value for resources of this class. This can be any
URI, and can include the variables {baseUri} and {resourceId}. When
constructing the href value, vCloud Director replaces {baseUri} with the
vCloud Director REST API base URL, and replaces {resourceId} with the
UUID portion of the id attribute value of the resource.

Nid The Namespace Identifier for resources of this type, as specified in

[Link]

UrnPattern The Namespace Specific String for resources of this type, as specified in
[Link] You can provide a string or a named
regular expression, where (?<id>) matches the resource identifier.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the service.

Use a request like this one:

GET [Link]

2 Examine the response to find the Link for adding resource classes.

This Link has the following form:

<vcloud:Link
rel="add"
type="application/[Link]+xml"
href="[Link] />

3 Construct a ResourceClass element.

See the request portion of “Example: Create an Extension Service Resource Class,” on page 422 for
information about the contents of this element.

4 POST the ResourceClass element to the URL described in Step 2.

Example: Create an Extension Service Resource Class

This request defines a resource class named Backup.

n The MimeType is specified using the standard form for vnd type names.

n The UrlTemplate uses the {baseUri} and {resourceId} variables, and could expand to a URL like
[Link]

n The Nid and UrnPattern elements provide rules for constructing an URN of the form:

urn:vcloud:backup:id

as shown in the response.

422 VMware, Inc.

Chapter 12 Extending vCloud Director

Request:

POST [Link]
Content-type:application/[Link]+xml
<?xml version="1.0" encoding="UTF-8"?>
<vmext:ResourceClass
name="Backup"
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
<vmext:MimeType>application/[Link]+xml</vmext:MimeType>
<vmext:UrlTemplate>{baseUri}backup/{resourceId}</vmext:UrlTemplate>
<vmext:Nid>vcloud</vmext:Nid>
<vmext:UrnPattern>^backup(?&lt;id&gt;[0-9]*)</vmext:UrnPattern>
</vmext:ResourceClass>

Response:

201 Created
Content-Type: application/[Link]+xml
...
<vmext:ResourceClass
name="Backup"
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
id="urn:vcloud:backup:83"
type="application/[Link]+xml"
href="[Link]
...>
<vcloud:Link
rel="remove"
href="[Link] />
<vcloud:Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="down:resourceClassActions"
type="application/[Link]+xml"

href="[Link]
s" />
<vcloud:Link
rel="down:serviceResources"
type="application/[Link]+xml"

href="[Link]
/>
<vmext:MimeType>BackupType+xml</vmext:MimeType>
<vmext:UrlTemplate>{baseUri}backup/{resourceId}</vmext:UrlTemplate>
<vmext:Nid>nidBackup</vmext:Nid>
<vmext:UrnPattern>^myNssBackup(?&lt;id&gt;[0-9]*)</vmext:UrnPattern>
</vmext:ResourceClass>

VMware, Inc. 423

vCloud API Programming Guide for Service Providers

Define an Action for a Resource Class

After you define a resource class, you can specify the actions that are permitted on resources of that class.

A ResourceClassAction object defines an HTTP method that is allowed on a specific UrlPattern. The
UrlPattern can be any of the following URL forms:

n An explicit URL like/backup/restore/vm/27. A UrlPattern of this form defines an action for a resource
that has a specific URL.

n A URL that contains a regular expression, like /backup/restore/vm[-,a-z,0-9]*. A UrlPattern of this

form defines an action for any resource in the class that matches the regular expression.

n A URL that contains a service resource id, which is expressed as <id>. In a UrlPattern, the delimiters
must be written as the XML entities &lt; and &gt;. The id can stand alone, as
in /backup/restore/vm/&lt;id&gt;, or appear as part of a regular expression like/backup/restore/vm/?
&lt;id&gt;[-,a-z,0-9]*). A UrlPattern of this form targets a specific ServiceResource, which must the
service must define and register.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the service.

Use a request like this one:

GET [Link]

2 Examine the response to find the Link for specifying resource class actions.

This Link has the following form:

<vcloud:Link
rel="add"
type="application/[Link]+xml"

href="[Link] />

3 Construct a ResourceClassAction element.

For information about the contents of this element, see the request portion of “Example: Define an
Action for a Resource Class,” on page 424.

4 POST the ResourceClassAction element to the URL described in Step 2.

Example: Define an Action for a Resource Class

This example defines a resource class action for a GET request to a UrlPattern that could match URLs
including [Link] or [Link]
backup-2013-04-25T[Link].000Z.

Request:

POST [Link]
Content-type:application/[Link]+xml
<?xml version="1.0" encoding="UTF-8"?>
<vmext:ResourceClassAction
xmlns:vmext="[Link]
xmlns:vcloud="[Link]

424 VMware, Inc.

Chapter 12 Extending vCloud Director

name="Read backups">
<vmext:HttpMethod>GET</vmext:HttpMethod>
<vmext:UrlPattern>/api/backup/[-,a-z,0-9]*)</vmext:UrlPattern>
</vmext:ResourceClassAction>

The response is a ResourceClassAction element that includes information derived from the contents you
POSTed , along with a set of Link elements that you can use to remove the ResourceClassAction or add ACL
rules that control access to the resource class through the action.

Response:

201 Created
Content-Type: application/[Link]+xml
...
<vmext:ResourceClassAction
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
name="Read backups"
id="urn:vcloud:resourceClassAction:268"
type="application/[Link]+xml"
href="[Link]
... >
<vcloud:Link
rel="remove"
href="[Link] />
<vcloud:Link
rel="up"
type="application/[Link]+xml"
href="[Link] />
<vcloud:Link
rel="down:aclRules"
type="application/[Link]+xml"

href="[Link] />
<vmext:HttpMethod>GET</vmext:HttpMethod>
<vmext:UrlPattern>/api/backup/[-,a-g,0-9]*)</vmext:UrlPattern>
</vmext:ResourceClassAction>

Define an ACL Rule for a Resource Class Action

Permission to execute an extension service operation is controlled by an AclRule contained in the
ResourceClassAction.

An ACL rule specifies the access controls that apply to a ResourceClassAction. Access controls can be
defined for any of the following principals:

n an individual user

n a member of a specified organization

n any user whose role includes a specific right

n any resource defined by the service that created the ACL rule

VMware, Inc. 425

vCloud API Programming Guide for Service Providers

Rights for specific entity types are specified in the following container elements:

ServiceResourceAccess This specification is optional.

OrganizationAccess Access for the organizations. This specification is required.

PrincipalAccess Access control for users, or for any role that includes a specified right. This
specification is required.

If the Access element in any of these containers has the value Entity, the container must also include an
Entity element that provides a reference to a resource entity, organization, user, or right.

Table 12‑3. ACL Rules

Container Element Access Comments

ServiceResourceAccess Shared The action is authorized for all resources in this resource class

Entity The action is authorized for the service resource referenced in the Entity
element in this container.

OrganizationAccess Shared The action is authorized for all members of the organization that owns the
resource.

Published The action is authorized for all members of any organization in the cloud.

Entity The action is authorized for members of the organization referenced in the
Entity element in this container.

PrincipalAccess Shared The action is authorized for all users

Entity The action is authorized for the User referenced in the Entity element in
this container, or for any role that includes the Right referenced in the
Entity element in this container.

A ResourceClassAction can include an arbitrary number of AclRule elements. The action is permitted if the
user or resource attempting the action matches any rule.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the resource class action.

This request retrieves the XML representation of the resource class action created in “Example: Define
an Action for a Resource Class,” on page 424:

GET [Link]

2 Examine the response to find the Link for specifying ACL rules for the resource class action.

This Link has the following form:

<vcloud:Link
rel="add"
type="application/[Link]+xml"

href="[Link]
" />

3 Construct an AclRule element.

See the request portion of “Example: Define an ACL Rule for a Resource Class Action,” on page 427 for
information about the contents of this element.

4 POST the AclRule element to the URL described in Step 2.

426 VMware, Inc.

Chapter 12 Extending vCloud Director

Example: Define an ACL Rule for a Resource Class Action

This example adds an ACL rule to the resource class action created in “Example: Define an Action for a
Resource Class,” on page 424. The rule specifies that all members of a specific organization who have a role
that includes a specific right can execute the action.
Request:

POST [Link]
Content-type: application/[Link]+xml
<?xml version="1.0" encoding="UTF-8"?>
<vmext:AclRule
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
xmlns:xsi="[Link]
name="ACL rule for read backups">
<Description>Only users in org/26 who have right/2 can read backups</Description>
<vmext:ServiceResourceAccess>
<vmext:Access>Shared</vmext:Access>
</vmext:ServiceResourceAccess>
<vmext:OrganizationAccess>
<vmext:Access>Entity</vmext:Access>
<vmext:Entity
xsi:type="vcloud:ResourceReferenceType"
type="application/[Link]+xml"
href="[Link] />
</vmext:OrganizationAccess>
<vmext:PrincipalAccess>
<vmext:Access>Entity</vmext:Access>
<vmext:Entity
xsi:type="vcloud:ResourceReferenceType"
type="application/[Link]+xml"
href="[Link] />
</vmext:PrincipalAccess>
</vmext:AclRule>

The response contains information supplied in the request, along with several Link elements created by the
server.

Response:

201 Created
Content-Type: application/[Link]+xml
...
<vmext:AclRule
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
name="ACL rule for read backups"
id="urn:vcloud:aclRule:5"
type="application/[Link]+xml"
href="[Link]
<Description>Only users in org/26 who have right/2 can read backups</Description><vcloud:Link
<vcloud:Link
rel="remove"
href="[Link] />
...
</vmext:AclRule>

VMware, Inc. 427

vCloud API Programming Guide for Service Providers

Create a Service-Specific Right

A service can create rights that apply to its operations. You can add these rights to existing roles or new
roles.

In the vCloud API, a right is simply a name that a service attaches to a privilege. When a service specifies an
ACL rule for a resource class action, the rule can reference a right. A user who is assigned a role that
includes the right is authorized to take the specified action.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the service.

Use a request like this one:

GET [Link]

2 Examine the response to find the Link for adding or listing service-specific rights

This Link has the following form:

<vcloud:Link
rel="rights"
type="application/[Link]+xml"
href="[Link] />

3 Construct a Right element.

For information about the contents of this element, see the request portion of “Example: Create a
Service-Specific Right,” on page 428.

4 POST the Right element to the URL described in Step 2.

Example: Create a Service-Specific Right

This request creates a right named DeleteBackup. The name attribute and Category element are required, and
can have any string value. Include a BundleKey if any messages associated with the right appear in a
localization bundle.

Request:

POST [Link]
Content-type:application/[Link]+xml
<?xml version="1.0" encoding="UTF-8"?>
<Right
xmlns="[Link]
name="DeleteBackup">
<Description>Right to remove a backup object</Description>
<Category>VcdBackup</Category>
<BundleKey>BackupBundle</BundleKey>
</Right>

The response is a Right element that includes information derived from the contents you POSTed. The
service namespace name is prepended to the name of the right.

428 VMware, Inc.

Chapter 12 Extending vCloud Director

Response:

201 Created
Content-Type: application/[Link]+xml
...
<Right
xmlns="[Link]
name="{[Link]}:DeleteBackup"
id="urn:vcloud:right:99"
type="application/[Link]+xml"
href="[Link]
... >
<Description>Right to remove a backup object</Description>
<Category>VcdBackup</Category>
<BundleKey>BackupBundle</BundleKey>
</Right>

Localization Framework for Extension Services

Extension service developers can provide localized content for service-specific tasks and events by creating
and uploading a localization bundle.
An extension service localization bundle is a file in zip format that contains one or more properties files.
Each file in the bundle has a name that indicates the locale to which it applies, and contains an arbitrary
number of key=value pairs, where the key is the value of an attribute of a service-specific task operation or
event, and the value is a localized string to display in log messages posted by the service.

Upload or Update a Localization Bundle

Each service provides a link that an administrator can use to upload a new or modified localization bundle
for the service.

A localization bundle is a file in ZIP format that contains one or more localized message files that your
service uses. Each line in one of these files provides localized text that replaces the text that your service
posts in the values of certain attributes for service-specific events and tasks. See “Message File Content,” on
page 430.

Prerequisites
n This operation is restricted to system administrators.

n Create a localization bundle.

Procedure
1 Create a localization bundle.

2 Find the localizationbundles URL for your service.

a Retrieve the XML representation of the service.

b Examine the representation for a Link of the following form:

<vcloud:Link
rel="bundle:upload"
type="application/[Link]+xml"

href="[Link] />
The localizationbundles URL is the value of the href attribute of this link.

VMware, Inc. 429

vCloud API Programming Guide for Service Providers

3 Create a BundleUploadParams element that specifies the size of the bundle and the service namespace of
the service.

4 POST the BundleUploadParams element to the localizationbundles URL of your service.

Example: Upload a Localization Bundle

This example uploads a localization bundle for the service created in “Example: Register an Extension
Service,” on page 412. The initial request specifies the size of the ZIP file in bytes and the name of the service
namespace.

Request:

POST [Link]
Content-type: application/[Link]+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<vmext:BundleUploadParams
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
fileSize="537"
serviceNamespace="[Link]">
</vmext:BundleUploadParams>

The response body includes an uploadLocation URL. You can use a procedure similar to the one in
“Example: Uploading File Data,” on page 70 to upload the ZIP file to this location.

Response:

<vmext:BundleUploadSocket
uploadLocation="[Link]
xmlns:vmext="[Link]
xmlns:vcloud="[Link]
</vmext:BundleUploadSocket>

To update a bundle, follow the same procedure using a new bundle that contains updated message files.
When you upload a new localization bundle for a service that already has one, new key=value pairs are
added, and the values of existing keys are updated.

Message File Content

Message files provide localized text for certain attribute values in Task and Event objects.
Each file in a localization bundle can include an arbitrary number of lines. Each line must have the following
form, where key is any of the values that the service might assign to one of its service-specific Task or Event
elements and value is the localized string to display.

key=value

The value string can contain parameters that provide the resourceId, resourceName, and resourceType of the
subject of the Task or Event.

The following restrictions apply to each message file in a localization bundle:

n File contents must be encoded in the UTF-8 character set.

n key length cannot exceed 2000 UTF-8 characters.

n value length cannot exceed 2000 UTF-8 characters.

n File size cannot exceed 10MB.

n File name must be the locale code for the language used in the value strings. For example, the file
containing English text must be named en_US. The file containing French text must be named fr_FR.

430 VMware, Inc.

Chapter 12 Extending vCloud Director

Whenever a localizable attribute appears in a log message, vCloud Director takes the following steps to find
text to display:

1 If the service has a localization bundle, open the file in that bundle whose name corresponds to the
current client locale and display the value as it appears in the file.
2 If the service has a localization bundle but no file exists in that bundle whose name corresponds to the
current client locale, open the file in that bundle named en_US and display the value as it appears in the
file. The default locale for vCloud Director is en_US.

3 Otherwise, display a predefined string.

A Task or Event that a service posts can also include a passthrough key=value pair that is always displayed as
posted by the service, regardless of the current client locale or the presence or absence of a localization
bundle.

Message File Keys and Parameters

Message file contents (key=value pairs) apply to all Task and Event objects that the service creates. If a Task
and an Event both use the same key, the same message appears for both.

Table 12‑4. Localization Keys for Service-Specific Tasks

Attribute Values Matched for key Available Parameters

operationName
resourceId The value of the id attribute of the
Owner of the Task.

resourceNam The value of the name attribute of the

e Owner of the Task.

resourceTyp The value of the type attribute of the

e Owner of the Task.

Owner:type None

serviceNamespace None

operation (passthrough) None

To create a message that appears only when a Task has status="running", append the string _PROGRESS to
the key.

Table 12‑5. Localization Keys for Service-Specific Events

Attribute Values Matched for key Available Parameters

type
resourceId The value of the id attribute of the
Owner of the Event.

resourceNam The value of the name attribute of the

e Owner of the Event.

resourceTyp The value of the type attribute of the

e Owner of the Event.

Owner:type None

serviceNamespace None

typeFull (passthrough) None

To create a message that appears only for a failed Event (one where success="false"), prepend the string
FAILED. to the key.

VMware, Inc. 431

vCloud API Programming Guide for Service Providers

Example: Example Message File Content

The following lines are appropriate in the en_US message file for a service that meets the following
conditions:

n Its Namespace is registered as [Link].

n It defined a Task whose operationName attribute can have a value of backupInProgress.

n It defined an Event whose type attribute can have a value of backupComplete.

[Link]=vCloud Backup Service

backupInProgress=Backup in progress for ${resourceName} ({resourceType}) with id: {resourceId}
backupInProgress_PROGRESS=Backup in progress for ${resourceName} ({resourceType}) with id:
{resourceId}
backupComplete=Backup complete for entity {resourceName} ({resourceType}) with id: {resourceId}
[Link]=Backup failed for entity {resourceName} ({resourceType}) with id:
{resourceId}

If the localization bundle for this service contained a file named fr_FR that included the following line, the
Task posted in “Example: Add a Task to an Organization's Tasks List,” on page 419 returns this localized
value for the operationName attribute when the client locale is set to fr_FR. The passthrough value for
operation is not localized.

backupInProgress_PROGRESS=Sauvegarde en cours pour entity {resourceName} ({resourceType}) avec

id: {resourceId}

Request:

GET [Link]

Response:

200 OK
Content-Type: application/[Link]+xml
...
<Task
...
operation="Backup in progress for virtual machine with id 7b91b053-2b..."
operationName="Sauvegarde en cours pour entity Finance (application/[Link]
+xml) avec id 26 "
... >

REST APIs for Extension Services

A simple extension service does not need a REST API. You can define a service-specific REST API entrypoint
and one or more schema definition files.

An extension service that does not require request or response bodies other than those that the vCloud API
defines, Task, for example, can simply define the URL patterns that constitute its API filters and the service
links that implement its operations.

A service that defines its own request or response bodies must also specify a URL to which clients can direct
requests. The service must specify locations of the files, such as XML schema definition (XSD) files, to which
its clients require access.

432 VMware, Inc.

Chapter 12 Extending vCloud Director

Create an API Filter for an Extension Service

When you register an extension service with vCloud Director, you specify one or more API filters, which are
URL patterns or MIME content types that the vCloud Director REST service should treat as extension
requests. You cannot update the API filter for a registered service, but you can replace it with a new one.

An API filter can be either a URL pattern, typically in the form of a regular expression, or a content type,
typically in the form of a MIME content-type string. Requests whose URL matches the specified UrlPattern
are sent to the service that has registered the filter. An API filter that specifies ResponseContentType is
applied only to responses whose Content-type attribute has a value that matches the specified
ResponseContentType. An extension service that receives such a response must return it, after making any
service-specific modifications, to the AMQP service as a JSON message, so that it can be returned to the
vCloud Director client that made the request.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the service.

This request retrieves the XML representation of the service created in “Example: Register an Extension
Service,” on page 412:

GET [Link]

2 Examine the response to find the Link for adding API filters

This Link has the following form:

<vcloud:Link
rel="add"
type="application/[Link]+xml"
href="[Link] />

3 Construct an ApiFilter element.

This ApiFilter overwrites any existing ApiFilter defined by the service. See the request portion of
“Example: Create an API Filter for an Extension Service,” on page 433 for information about the
contents of this element.

4 POST the ApiFilter element to the URL described in Step 2.

Example: Create an API Filter for an Extension Service

This request adds a new UrlPattern to set of patterns defined in the request portion of “Example: Register
an Extension Service,” on page 412. The request replaces the existing set of filter expressions with a new one
that includes the original set and one additional expression.

Request:

POST [Link]
Content-type:application/[Link]+xml
<?xml version="1.0" encoding="UTF-8"?>
<vmext:ApiFilter>
<vmext:UrlPattern>(/api/org/.*/backups)|(/api/vApp/vapp-.*/backups)|
(/api/vApp/vapp-.*/action/backup)|(/api/backup/.*) |
(/api/vApp/vapp-.*/action/recoverBackup)</vmext:UrlPattern>
</vmext:ApiFilter>

VMware, Inc. 433

vCloud API Programming Guide for Service Providers

Response:

201 Created
Content-Type: application/[Link]+xml
...
<vmext:ApiFilter>
<vmext:UrlPattern>(/api/org/.*/backups)|(/api/vApp/vapp-.*/backups)|
(/api/vApp/vapp-.*/action/backup)|(/api/backup/.*) |
(/api/vApp/vapp-.*/action/recoverBackup)</vmext:UrlPattern>
</vmext:ApiFilter>

Create or Update an Extension Service API Definition

You can define an API for an extension service when you register the service. You can also create or update
the service API definition later.

An API definition for an extension service includes an API entry point (A URL at which a client can send
requests to the API) and a set of file descriptors, each of which consists of a description and a reference to a
schema definition file.

An ApiDefinition element must contain the following child elements:

EntryPoint The URL to which a client can send requests to the service API. This can be
any URL, and can include the variable {baseUri}, which represents the
vCloud Director REST API base URL.

Namespace The service namespace. See “Register an Extension Service,” on page 411

Files One or more references to schema definition files. The references must be
accessible to vCloud Director.

Prerequisites
This operation is restricted to system administrators.

Procedure
1 Retrieve the XML representation of the service.

Use a request like this one:

GET [Link]

2 Examine the response to find the Link for adding API definitions.

This Link has the following form:

<vcloud:Link
rel="add"
type="application/[Link]+xml"
href="[Link] />

3 Construct an ApiDefinition element.

For information about the contents of this element, see the request portion of “Example: Create an
Extension Service API Definition,” on page 434.

4 POST the ApiDefinition element to the URL described in Step 2.

Example: Create an Extension Service API Definition

This request defines an API for a backup service. The definition includes two FileDescriptor elements that
reference files available on the vendor's public Website. The entrypoint for requests to the service is the
vCloud Director API login URL.

434 VMware, Inc.

Chapter 12 Extending vCloud Director

Request:

POST [Link]
Content-type:application/[Link]+xml
<?xml version="1.0" encoding="UTF-8"?>
<vmext:ApiDefinition
name="Backup service version 5.1">
<Description>Backup service API</Description>
<vmext:EntryPoint>{baseUri}/login</vmext:EntryPoint>
<Namespace>[Link]</Namespace>
<vmext:Files>
<vmext:FileDescriptor>
<vmext:Description>Master schema definition file.</vmext:Description>
<vmext:File
href="[Link] />
</vmext:FileDescriptor>
<vmext:FileDescriptor>
<vmext:Description>Schema definition file for backup devices.</vmext:Description>
<vmext:File
href="[Link] />
</vmext:FileDescriptor>
</vmext:Files>
</vmext:ApiDefinition>

Response:

201 Created
Content-type:application/[Link]+xml
...
<vmext:ApiDefinition
name="Backup service version 5.1">
...
</vmext:ApiDefinition>

Extension Service AMQP Message Format

vCloud Director uses the system AMQP service to communicate with extension services. Messages to and
from an extension service are formatted as JSON objects.
When it receives an extension request, the vCloud Director REST service creates a message and sends it to
the system AMQP service, specifying the exchange and routing key registered by the extension service. The
extension service retrieves the message from a queue bound to the exchange it registered, processes the
request, and returns a response to the common reply exchange.

AMQP Message Headers

Each message from vCloud Director to a service includes both standard and custom AMQP headers.

Table 12‑6. Extension Service AMQP Message Headers

Header Value

correlationId A standard AMQP header that provides a unique identifier

for the message. The extension must supply the same
correlationId in the corresponding response.

reply-to A standard AMQP header specifying the value that the

extension must use as the routingKey in the response.

VMware, Inc. 435

vCloud API Programming Guide for Service Providers

Table 12‑6. Extension Service AMQP Message Headers (Continued)

Header Value

messageType A custom AMQP header. One of:

ProcessHttp Indicates that this message is a

Request forwarded request.

ProcessHttp Indicates that this message is a

Response forwarded response.

replyToExchange A custom AMQP header. The name of the AMQP exchange

to which the extension should publish its response.

Property Names and Values

A request message contains all of the following name=value pairs.

Table 12‑7. Extension Service AMQP Request Message Property Names and Values
Name Value

method The HTTP method (GET, PUT, POST, DELETE) used to

make the request

id The unique id of this message

scheme The scheme (HTTP or HTTPS) specified in the request URL

protocol The protocol used to make the request

headers The request headers represented as a map of name:value

pairs encoded as a JSON object in the form:
name:value,name:value,...

queryString The entire query string, or null if the request did not
include a query string.

localPort The local port to which the request was sent

remoteAddr The IP address of the requesting machine

remotePort The remote port from which the request was sent

localAddr The IP address to which the request was sent

request Always true in request messages

requestURI The request URL, without any query string it might have
included

parameters always null

user The id of the vCloud Director user who made the request

org The id of the vCloud Director organization to which the

requesting user belongs

rights A comma-separated list of id values for the

vCloud Director rights assigned to the requesting user.

The parameters, user, org, and rights properties provide the security context for the request, and are
formatted as a separate JSON object, as shown in “Example: AMQP Message Format,” on page 437

A response message contains all of the following name=value pairs.

436 VMware, Inc.

Chapter 12 Extending vCloud Director

Table 12‑8. Extension Service AMQP Response Message Property Names and Values
Name Value

id The unique id of this message

headers A comma-separated list of request headers in the form:

name:value,name:value,...

statusCode The HTTP status code to return to the requester

body A base64-encoded response body

request Always false in response messages

Example: AMQP Message Format

Assume an extension service that includes an API filter of the following form:

<vmext:ApiFilter>
<vmext:UrlPattern>/api/org/.*</vmext:UrlPattern>
</vmext:ApiFilter>

When vCloud Director receives a request like this one:

GET [Link]

it creates the following message and places it on the service's exchange.

[
{
"method":"GET",
"id":"32d5b9ec-5eef-4aa3-9375-b054018b0e30",
"scheme":"https",
"protocol":"HTTP/1.1",
"headers":{"Cookie":"...", "User-Agent":"...", ...},
"queryString":null,
"localPort":8443,
"remoteAddr":"[Link]",
"remotePort":60576,
"localAddr":"[Link]",
"request":true,
"requestUri":"/api/org/a93c9db9-7471-3192-8d09-a8f7eeda85f9"
},
{
"parameters":null,
"user":"urn:vcloud:user:8cdd352f-f831-4712-a1a3-9e061687c5c6",
"org":"urn:vcloud:org:a93c9db9-7471-3192-8d09-a8f7eeda85f9",
"rights":["urn:vcloud:right:0b8c8cd2-5af9-32ad-a0bd-dc356503a552",...]
},
null
]

The service returns a response containing a base64-encoded body.

[
{
"id":"32d5b9ec-5eef-4aa3-9375-b054018b0e30",
"headers":{"Date":"...", "Content-Type":"application/[Link]+xml;version=2.0"},
"statusCode":200,

VMware, Inc. 437

vCloud API Programming Guide for Service Providers

"body":"base64-encoded-body",
"request":false,
}
]

438 VMware, Inc.

XML Representations in the vCloud
API 13
The vCloud API represents objects in a cloud as XML documents in which object properties are contained in
elements and attributes that have typed values and an explicit object hierarchy defined by an XML schema.

Client 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, and any requirements that
the network protocol (HTTP) places on client-server interaction.

XML Schemas
Each vCloud API object is defined in an XML schema document. Schema files and reference information
about all elements, types, operations, and queries is included in the vCloud API Schema Reference. See “About
the Schema Reference,” on page 26.

vCloud Director uses a validating XML parser that requires elements in XML documents to agree in 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. See “XML Namespace Identifiers,” on page 441.

All vCloud API requests are processed in the [Link] XML namespace. vCloud
API XML namespace information appears in the values of the xsi:schemaLocation and xmlns attributes in a
response document.

xmlns="[Link]
xsi:schemaLocation="[Link]

Other XML namespace identifiers may also be required in request bodies. See “XML Namespace
Identifiers,” on page 441.

API Versions
The vCloud XML namespace ([Link] defines elements and attributes for all
supported versions of the vCloud API. Treatment of version-specific elements and attributes in requests is
controlled by the value of the version attribute in the Accept header. For example, this Accept header
specifies that the request body is presumed to be valid for vCloud API version 20.0 and a version 20.0
response is expected:

Accept: application/*;version=20.0

VMware, Inc. 439

vCloud API Programming Guide for Service Providers

Requests are validated against the elements and attributes defined in the specified version. Responses are
filtered to remove elements and attributes that are not defined in the specified version. In general, client
requests can access objects defined by any version of the vCloud API that is less than or equal to the version
specified in the Accept header. Exceptions to this rule are mentioned in the vCloud Director Release Notes.
The vCloud API Schema Reference indicates the deprecation status of elements and attributes, and also
indicates when each element or attribute was added to the API. See “About the Schema Reference,” on
page 26.

To discover the API versions that a server supports, a client can make an unauthenticated GET request to a
well-known URL on the server. See “Example: Retrieve the Login URL and List of Supported API
Versions,” on page 24.

Date and Time Values

Values of type xs:dateTime are always interpreted as UTC if a timezone has not been explicitly specified.

Length Limits on Element and Attribute String Values

String values for the name attribute and the Description and ComputerName elements have length limitations
that depend on the object to which they are attached.

Table 13‑1. Length Limits on Element and Attribute String Values

Object Element or Attribute Name Maximum Length in Characters

Catalog name 128

Catalog Description 256

EdgeGateway name 35

Media name 128

Media Description 256

VApp name 128

VApp Description 256

VAppTemplate name 128

VAppTemplate Description 256

Vdc name 256

Vdc Description 256

Vm name 128

Vm ComputerName 15 on Windows, 63 on all other platforms

A VM name cannot contain any special characters. See VMware Knowledge Base article
[Link]

Extensibility
The vCloud API provides complete programmatic access to the vCloud Director Extension Services facility.
See “vCloud Director Extension Services,” on page 409.

In addition, there is a more general extensibility mechanism, VCloudExtension, that clients are free to use.
VCloudExtensibleType is an abstract type that all complex types defined in the vCloud API namespace
extend. It can contain an arbitrary number of elements and attributes, and provides a way for you to add
custom attributes and elements to any type.

440 VMware, Inc.

Chapter 13 XML Representations in the vCloud API

The VCloudExtension element has an attribute named required that specifies how clients and servers
proceed when they see an unknown extension. All VCloudExtension elements are assumed to require a
server that understands them. The required attribute is optional, but if omitted is assumed to be present
with a value of true. This extensibility mechanism allows new servers to extend the XML representations
native to the vCloud API without requiring existing clients to understand those extensions.
A client might encounter a VCloudExtension element in any response. If the element declares
required=”true” and the 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. For more information about
VCloudExtension, see the schema reference.

This chapter includes the following topics:

n “XML Namespace Identifiers,” on page 441

n “Common vCloud API Attributes,” on page 442

n “Retrieve an Object as an Entity,” on page 444

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

The vCloud API uses these XML namespace identifier attributes and prefixes.

Table 13‑2. XML Namespace Identifiers in the vCloud API

Name Value Requirement

xmlns [Link] Required in all request bodies.

xmlns:vmext [Link] Required in request bodies that include

elements from the vSphere platform
extensions.

xmlns:ve [Link] Required in request bodies that include

an ovf:Environmentelement.

xmlns:ovf [Link] Required in request bodies that include

elements defined in OVF schema
[Link]
e/1/[Link].

xmlns:rasd [Link] Required in request bodies that include

CIM_ResourceAllocationSettingData elements defined in OVF schema
CIM_ResourceAllocationSettingData.x
sd.

xmlns:oe [Link] Required in request bodies that include

elements defined in OVF schema
dsp8027_1.[Link].

xmlns:vssd [Link] Not required in request bodies.

CIM_VirtualSystemSettingData

xsi:schemaLocati An installation-dependent schema location search path. Not required in request bodies.
on See [Link]

xmlns:xsi [Link] Not required in request bodies.

VMware, Inc. 441

vCloud API Programming Guide for Service Providers

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.

The examples omit XML namespace identifiers from most responses. The following fragment shows how
some of them appear in a typical response body.

<VApp
xmlns="[Link]
...
xmlns:ovf="[Link]
xmlns:xsi="[Link]
xsi:schemaLocation="[Link]
[Link]
...>
...
</VApp>

Common vCloud API Attributes

Most vCloud API objects 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.

Object Name
Every object requires a name attribute. The string value of this attribute is included in all object references,
and can be used as the display name for the object. The value of name must be unique within a given scope.

Table 13‑3. Requirements for Unique Object Names

Object Type Name Scope

ProviderVdc Cloud

Org Cloud

Vdc Organization

Catalog Organization

CatalogItem Catalog

vAppTemplate None

vApp Organization

Vm vApp

Media Catalog

Disk None

Network Container (Organization VDC, vApp, or cloud)

442 VMware, Inc.

Chapter 13 XML Representations in the vCloud API

Object Identifier, Type, and Reference

These attributes are common to all object representations.

id The object identifier, expressed in URN format. The value of the id attribute
uniquely identifies the object, persists for the life of the object, and is never
reused. The id attribute value is intended to provide a context-free identifier
that can be used with the vCloud API entityResolver (see “Retrieve an
Object as an Entity,” on page 444).

type The object type, specified as a MIME content type.

href An object reference, expressed in URL format. This reference includes the
object identifier portion of the id attribute value, and supplies additional
information, including the current location of the object when accessed in a
specific view. 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 how the server constructs href strings might
change in future releases.

Object Creation 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. In this table, YES indicates that a status value is allowed for the
object listed in the column header. The status value for a VAppTemplate or VApp, which contain Vm objects that
each have a status attribute of their own, is computed from the status of the contained objects. When
returned in an XML representation, status has a numeric value. When returned by the query service, it has
a string value.

Table 13‑4. status Attribute Values for VAppTemplate, VApp, Vm, and Media Objects
Num
eric
Valu vAppTem
e String Value Description plate vApp Vm Media

-1 FAILED_CREATIO The object could not be created. YES YES YES YES
N

0 UNRESOLVED The object is unresolved. YES YES YES YES

1 RESOLVED The object is resolved. YES YES YES YES

2 DEPLOYED The object is deployed. No No No No

3 SUSPENDED The object is suspended. No YES YES No

4 POWERED_ON The object is powered on. No YES YES No

5 WAITING_FOR_IN The object is waiting for user No YES YES No

PUT input.

6 UNKNOWN The object is in an unknown YES YES YES No

state.

7 UNRECOGNIZED The object is in an YES YES YES No

unrecognized state.

8 POWERED_OFF The object is resolved and YES YES YES No

powered off.

9 INCONSISTENT_ST The object is in an inconsistent No YES YES No

ATE state.

VMware, Inc. 443

vCloud API Programming Guide for Service Providers

Table 13‑4. status Attribute Values for VAppTemplate, VApp, Vm, and Media Objects (Continued)
Num
eric
Valu vAppTem
e String Value Description plate vApp Vm Media

10 MIXED Children do not all have the YES YES No No

same status.

11 DESCRIPTOR_PEN Upload initiated, OVF YES No No No

DING descriptor pending.

12 COPYING_CONTE Upload initiated, copying YES No No No

NTS contents.

13 DISK_CONTENTS_ Upload initiated , disk contents YES No No No

PENDING pending.

14 QUARANTINED Upload has been quarantined. YES No No No

15 QUARANTINE_EX Upload quarantine period has YES No No No

PIRED expired.

16 REJECTED Upload has been rejected. YES No No No

17 TRANSFER_TIMEO Upload transfer session timed YES No No YES

UT out.

18 VAPP_UNDEPLOY The vApp is resolved and YES No No No

ED undeployed.

19 VAPP_PARTIALLY_ The vApp is resolved and YES No No No

DEPLOYED partially deployed.

VDC objects have their own set of status values and mappings.

Table 13‑5. status Attribute Values for VDC Objects

Numeric
Value String Value Description

-1 FAILED_CREATION The VDC could not be created.

0 NOT_READY The VDC is not ready for use

1 READY The VDC Is ready for use

2 UNKNOWN The VDC status could not be retrieved

3 UNRECOGNIZED The VDC status cannot be mapped to a known state.

Retrieve an Object as an Entity

You can use the vCloud API entity resolver with an object's id attribute value to retrieve a context-free
reference to the object.

Every first-class object that the vCloud API defines includes an id attribute whose value is the object
identifier expressed in URN format. The value of the id attribute uniquely identifies the object, persists for
the life of the object, and is never reused.

You can append the value of the id attribute to the vCloud API entityResolver URL to retrieve a context-
free representation of the underlying object as an Entity element. The Entity includes a Link element for
each currently valid reference to the object identified by the id specified in the request.

Prerequisites
Verify that you are logged in to the vCloud API.

444 VMware, Inc.

Chapter 13 XML Representations in the vCloud API

Procedure
1 Retrieve the current Session object to get the entityResolver URL.

Use a request like this one:

GET [Link]

The response is a Session element, which includes a link to the entityResolver.

<Session ... >

...
<Link
rel="entityResolver"
type="application/[Link]+xml"
href="[Link] />
</Session>

2 Retrieve the object whose id you want to resolve and find the value of its id attribute.

See the request portion of “Example: Using the entityResolver URL,” on page 445.

3 Append the value of the object's id attribute to the entityResolver URL.

4 Make a GET request to the URL you created in Step 3

See the request portion of “Example: Using the entityResolver URL,” on page 445.

Example: Using the entityResolver URL

This example retrieves the organization object shown in “Example: Object id, type, and href Attributes,” on
page 12 as an Entity.

Request:

GET [Link]

This response includes two Link elements, each of which provides a valid href to the object identified by the
id specified in the request.

Response:

<Entity
xmlns="[Link]
id="urn:vcloud:org:72fe715c-5f6a-407f-bbb2-bf465915b5f4"
name="urn:vcloud:org:72fe715c-5f6a-407f-bbb2-bf465915b5f4"
type="application/[Link]+xml"
href="[Link]
bf465915b5f4"
...>
<Link
rel="alternate"
type="application/[Link]+xml"
href="[Link]
<Link
rel="alternate"
type="application/[Link]+xml"
href="[Link]
</Entity>

VMware, Inc. 445

vCloud API Programming Guide for Service Providers

446 VMware, Inc.

Index

A to retrieve 32
access control 91 to synchronize with external source 84
access rights 93 client, REST 25
cloud, administrative view of 56
administrative tasks, about 185
console, displaying 41
administrator, system 185
affinity rule
VM-host 327 D
VM-VM 126 DHCP 205, 211
AMQP, certificate and truststore 351 dhcp service, in vApp network 101
AMQP service, to configure 347 DHCP service, in Edge Gateway 211
AMQP settings, to test 349 disk, independent 85
API client, to develop 24 download URL 75
attributes
custom 156 E
name 442 Edge Gateway
status 442 about 199
interface capacity 213
B syslog server settings 218
blocking task, to configure 381 to create 316
blocking task requests, to monitor 388 entity, retrieve object as 12
blocking task settings, to configure 383 entity resolver, about 444
browsing 47 event, service-specific 420
examples, conventions for 26
C extension framework 409
catalog extension services
change owner 90 ACL rules 425
controlling access to 91 and events 418
for external publication 223 and tasks 418
removing items 84 API definition 434
storage profile for 227 API filters for 433
subscription endpoint 234 authorization frameworks for 421
to administer 219 localization bundles 429
to create 220 localization of 429
to find 30 message files 430
to publish externally 233 message format 435
to retrieve 31 resource class actions 424
to share 230 resource classes 422
to share with specific organizations 231 REST APIs for 432
to synchronize with external source 84, 225 to register 411
with external subscription 225 URL patterns for 433
catalog item extensions
about 81 object 399
to copy 81 object extensions 399
to move 81 types of 399
to change name or description 82 external network, to create 297
to remove 84

VMware, Inc. 447

vCloud API Programming Guide for Service Providers

F M
federation maintenance mode, vApp 151
about 251 media
using LDAP 256 downloading 78
firewall service retrieve owner 90
and syslog 218 supported formats 76
in vApp network 101 to upload 61
in Edge Gateway 203 uploading 76
metadata
G about 357
group and VM placement 129
to import 245 to retrieve or modify 360
to import from OAuth 247 to search for 379
to import from SAML 248 metadata value, to retrieve or modify 363
groups, to administer 241
N
I NAT service
id attribute, and entity resolver 444 in Edge Gateway 205
identity providers, and federation 251 in vApp network 101
independent disk network pool
about 85 and organization VDC network 199
to create 85 list of 275
to remove 89 portgroup-backed 303
to update 87 to create 300
to attach or detach 138 VLAN-backed 301
instantiation, about 98
VxlanPoolType 286, 300
instantiation parameters
network services
in instantiateVAppTemplate request 105
in vApp network 101
in instantiateOvf request 120
in Edge Gateway 201
sections allowed in 151
list of 199
IOPS
networks
configuration for hard disk 180
about 199
configuration for Provider VDC 295
DHCP service 211
configuration for VDC 313
NAT services 205
IP address, of virtual machine NIC 164
to retrieve list from vCenter 273
K vApp 100
keytab, to upload 189, 351 VPN 211
notifications
L format of 393
LDAP, certificate and keystore 189, 351 to enable or disable 382
Link element, rel attribute 13
load balancer service 209 O
logging, of firewall actions 203 OAuth, identity provider 48
login object identifiers 12
as system administrator 53 object references, about 12
Basic authentication 53 Object Extension
integrated identity provider 53 to register 402
OAuth identity provider 48 to retrieve or update 404
object hierarchy, diagram of 10
SAML identity provider 50
organization
logout 44 federation settings 252, 253
grant rights to 283
retrieve or update settings 186
system 185

448 VMware, Inc.

Index

to remove 285 headers 19, 439

to administer 186 login 28
to create 279 required elements and attributes in 19
to enable or disable 285 resource pool
organization VDC network adding 292
about 199 adopting 310
direct 320 host groups in 324
isolated 216 removing 292
routed 213 resource pool set, Provider VDC 290
to administer 199 resource pools, to retrieve list from vCenter 272
responses, about 22
to create 212
right
to configure static routes 207 reference format 263
organizations
to create 428
federation of 186
role
to list 54 predefined 257
OVF, to instantiate 120
to create 257, 263
OVF specification 95
roles and rights 257
OVF descriptor
to download 74
S
upload URL for 66 SAML
OVF environment 168 identity provider 50, 241
OVF package organization settings for 186
manifest file 64, 70 schema files, accessing 26
to upload or download 61 schema reference 26
uploading 62 SectionType element, to retrieve or update 159
OVF upload selector extension, to create 405
initiating 64 Selector Extension, to retrieve or update 408
to monitor progress of 70 service
using ranged PUTs 71 DHCP 211
NAT 205
P service links
required and optional elements 414
ProductSection element 168
to add 415
Provider VDC
resource pool set 290 to add or remove 414
to add or remove storage profiles 294 to delete 416
to create 286 Session 47, 48, 50, 53
to merge 296 Session object, to delete 44
single sign-on
OAuth metadata 252
Q
queries SAML metadata 253
packaged 370 SSL certificate, to upload 189, 351
typed 366 SSPI 189, 351
query service static routing service
about 365 in vApp network 101
and metadata 379 in Edge Gateway 207
attribute names 375 status attribute
of vApp or vApp template 62
query parameters 375
values 442
query types 366
storage profile, disk 177
query encoding rules 375 storage profiles
and storage policies 194, 294
R to retrieve list from vCenter 277
RASD 95 to refresh list of 277
requests system settings, to retrieve or update 268
about 19

VMware, Inc. 449

vCloud API Programming Guide for Service Providers

T hardware customization 108

task retrieve owner 90
blocking 389 to update 151
service-specific 418 to download as OVF package 72
update progress 392 to enable for download 73
task operations 385 to import virtual machine as 344
timezone, in dateTime values 439 to instantiate 35
truststore, to upload 189, 351 to upload or download 61
upload URL 68
U
uploading vmdk files 70
user
vCenter resources, to discover 270
admin take ownership of a user's objects 250
vCenter server, to attach 269
to import from OAuth 247 vCloud API
to import from SAML 248 and RESTful programming style 9
to create 242 deprecation history 7
to import 243 revision history 7
users, to administer 241 VDC
allocation models 304
V control access 197
vApp instantiateVAppTemplate action 34
access control for 125, 229
networks in 34
add virtual machines 114
SupportedHardwareVersion elements 304
adopting 80
template-based 191
capturing 79, 123
to add or remove storage profiles 194
changing owner 90
to administer 191
cloning 118
to change name or description 193
composing 111
to create 191, 304
configuration links in 152
to enable or disable 196
controlling access to 91
to find 30
datacenter operations 95
to remove 196
importing 79, 80, 343 VDC templates
importing from vCenter 343 about 329
maintenance mode 151 access control for 341
power states 134 to create or update 330
recompose 114 with networking 334
remove virtual machines 114 with multiple Provider VDCs 338
to instantiate 105 virtual machine
to undeploy 43 affinity rules 126, 128
to configure 151 available for import 276
to delete 43 CPU configuration 165
to download as OVF package 72 disk configuration 177
to enable for download 73 disk storage profile 177
to modify vApp network configuration 161 disks 171
to operate 133 groups in resource pools 323, 325
to power off 43 guest customization for 167
to retrieve 38 hard disk configuration 173
vApp network host affinity 323
about 199 importing 343
to retrieve 199 importing from vCenter 343
to modify 161 metrics 139, 141, 144, 148
vApp snapshot 137 network cards 171
vApp template question from 135
captured from vApp 123

450 VMware, Inc.

Index

to update NetworkConnectionSection 164

to update storage profile 175
to relocate 346
to relocate to a different storage profile 175
to update multiple sections 157
virtual hardware, vmx versions supported by
Provider VDC 286
virtual machine metrics
about 139
collection intervals 144, 148
negative values for 139
retrieve all 141
retrieve subset 144
wildcards 148
Vm, configuration links in 153
vmdk file, to download from template 75
vSphere
operations 58
retrieve object URL 354
vSphere object map 355
vSphere platform, to manage 267

W
workflow, example of 27

X
XML
compressed responses 19
validation of 19
XML namespaces 441
XML schemas, reference information 439

VMware, Inc. 451

vCloud API Programming Guide for Service Providers

452 VMware, Inc.