VMware vCloud Director - 1.5 Programming Guide

vCloud API Programming Guide

vCloud Director 1.5

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 http://www.vmware.com/support/pubs.

EN-000579-00

vCloud API Programming Guide

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

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

The VMware Web site also provides the latest product updates.

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

docfeedback@vmware.com

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

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

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

VMware, Inc.

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

2 VMware, Inc.

vCloud API Programming Guide 7

About the VMware vCloud API 9

Object Taxonomy 10

Objects, References, and Representations 11

Links and Link Relations 12

Client Workflow Overview 15

Using the vCloud API with vCloud Director 18

About the vCloud API Examples 22

Hello vCloud: A Simplified RESTful Workflow 23

Logging In 24

Find a Catalog and a vDC 26

Retrieve the Contents of a Catalog 27

Retrieve a Catalog Item 28

Retrieve Deployment Information From the vDC 30

Deploy the vApp 31

Get Information About a vApp 34

Displaying the Virtual Machine Console 37

Delete the vApp 38

Log Out 39

Exploring a Cloud 41

Summary of vCloud API Browsing Requests 41

Retrieve the Login URL and List of Supported API Versions 42

Create a Login Session 44

Retrieve a List of Organizations Accessible to You 46

Retrieve an Administrative View of a Cloud 47

Retrieve a List of vSphere Platform Operations and Objects for a Cloud 49

VMware, Inc.

Provisioning an Organization with vApps, Templates, and Media 53

Summary of vCloud API Provisioning Requests 54

Upload an OVF Package to Create a vApp Template 55

Download a vApp Template as OVF 64

Upload a Media Image 67

Copying and Moving with the vCloud API 69

Capturing and Importing vApps 70

Cataloging vApp Templates and Media Images 70

View or Change the Owner of an Object 73

vCloud API Programming Guide

Deploying and Operating vApps 75

Summary of vCloud API vApp and Virtual Machine Operations Requests 77

Create a vApp From a Template 78

Compose a vApp From Existing Virtual Machines 80

Recompose a vApp to Add or Remove Virtual Machines 83

Operate a vApp 85

Configuring vApps and Virtual Machines 86

Creating, Provisioning, and Managing Organizations 109

Summary of Administrative Requests 109

Administrator Credentials and Privileges 111

Organization Administration 112

Network Administration 118

vDC Administration 139

Catalog Administration 145

User and Group Administration 148

Working With Roles and Rights 153

Controlling Access to vApps and Catalogs 157

Using vCloud API Extensions to Provision and Manage a Cloud 161

Summary of vSphere Platform Extension Requests 161

Retrieve or Update System Settings 165

Attach a vCenter Server 166

Finding Available vCenter Resources 167

Create a Provider vDC 173

Create an External Network 180

Create a Network Pool 183

Import a Virtual Machine from vCenter 189

Relocate a Virtual Machine to a Different Datastore 192

Working With Object Metadata 195

Retrieve or Update a Metadata Element 196

Retrieve or Update a Metadata Value 199

Using the Query Service 201

Typed Queries 201

Packaged Queries 207

Query Parameters 211

Configuring and Using Blocking Tasks and Notifications 215

Configure Notifications and AMQP Settings 216

Retrieve or Update Blocking Task Settings 225

Monitor Blocking Tasks 228

Take Action on a Blocking Task 229

Extend The Timeout Expiration of an Active Task 232

XML Representations in the vCloud API 233

XML Namespace Identifiers 234

4 VMware, Inc.

Common vCloud API Attributes 235

Retrieve an Object as an Entity 237

Index 239

Contents

VMware, Inc. 5

vCloud API Programming Guide

6 VMware, Inc.

vCloud API Programming Guide

The vCloud API Programming Guide provides information about version 1.5 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 Programming Guide is revised with each release of the product or when necessary. A revised version can contain minor or major changes.

Table 1. Revision History

Revision Date Description

01SEP11 API Version 1.5

30AUG10 API Version 1.0

14APR10 API Version 0.9

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 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 books, go to http://www.vmware.com/support/pubs.

VMware, Inc.

vCloud API Programming Guide

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 and vCloud Director servers communicate 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:

“Object Taxonomy,” on page 10

“Objects, References, and Representations,” on page 11

“Links and Link Relations,” on page 12

“Client Workflow Overview,” on page 15

“Using the vCloud API with vCloud Director,” on page 18

“About the vCloud API Examples,” on page 22

VMware, Inc.

Catalog 2

Catalogitem

em em em

Catalog 1

Catalog 3

vDC2

Catalogitem Catalogitem Catalogitem Catalogitem

users

Media

vApp

template

Media

vApp

TasksList

Organization

vDC1

Media

vApp

template

Media

vApp

Network

Catalogitem

em em em

groups

vCloud API Programming Guide

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

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.

Users and Groups

An organization can contain an arbitrary number of users and groups. Users can be created by the organization administrator or imported from an LDAP directory service. Groups must be imported from the directory service. Permissions within an organization are controlled through the assignment of

Catalogs

Networks

rights and roles to users and groups.

Catalogs contain references to virtual systems and media images. A catalog can be shared to make it visible to other members of an organization, and can be published to make it visible to administrators in other organizations. A system administrator specifies which organizations can publish catalogs, and an organization administrator controls access to catalogs by organization members.

An organization can be provisioned with one or more networks. These organization networks can be configured to provide services such as DHCP, NAT, VPN, and firewalls.

10 VMware, Inc.

Chapter 1 About the VMware vCloud API

Virtual Datacenters

Virtual Systems and Media Images

A virtual datacenter (vDC) is a deployment environment for virtual systems and an allocation mechanism for resources such as networks, storage, CPU, and memory. In a vDC, computing resources are fully virtualized, and can be allocated based on demand, service level requirements, or a combination of the two.

Virtual systems and media images are stored in a vDC and can be included in a catalog. Media images are stored in their native representation (ISO or floppy). Virtual systems are initially 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:

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

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

End-user license agreement terms for each virtual machine.

Deployment lease terms, typically inherited from the containing organization, that constrain the consumption of vDC resources by the vApp.

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 that members of an organization initiate are tracked by task objects, which are kept on the organization’s tasks list.

Objects, References, and Representations

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

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

type

href

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 237), and is also suitable for use by clients that need to

access the object using a different API.

The object type, specified as a MIME content type.

An object reference, expressed in URL format. Because this URL includes the object identifier portion of the id attribute value, it uniquely identifies the object, persists for the life of the object, and is never reused. The value of the

href attribute is a reference to a view of the object, and can be used to access a

representation of the object that is valid in a particular context. 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.

VMware, Inc. 11

vCloud API Programming Guide

Example: Object id, type, and href Attributes

This XML fragment, extracted from the representation of a vApp, shows its id, type, and href attributes.

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=" type="application/vnd.vmware.vcloud. href=" name="

relationship

URL

string

"/>

Attribute values in a Link element supply the following information:

rel

type

href

object_type

+xml"

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.

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 attribute is a reference to a view of the object, and can be used to access a

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.

12 VMware, Inc.

Chapter 1 About the VMware vCloud API

Table 1-1. Link Relationships and HTTP Request Types

rel Attribute Value Action or Relationship Description Implied HTTP Verb

add Add an item to this container. POST

alternate References an alternate representation

of this object.

catalogItem References the CatalogItem object

that refers to this object.

collaboration:abort Abort this blocking task. POST

collaboration:fail Fail this blocking task. POST

collaboration:resume Resume this blocking task. POST

consolidate Consolidate this virtual machine. POST

controlAccess Apply access controls. POST

copy Reserved, unimplemented. N/A

deploy Deploy this vApp. POST

disable Disable this object. POST

discardState Discard the suspended state of this

virtual machine.

down References an object contained by this

object.

download:alternate Reserved, unimplemented. N/A

download:default References the default location from

which this file can be downloaded.

edit Modify this object. PUT

enable Enable this object. POST

firstPage Reference to the first page of a

paginated response.

installVmwareTools Install VMware Tools on this virtual

machine.

lastPage Reference to the last page of a

paginated response.

media:ejectMedia Eject virtual media from a virtual

device.

media:insertMedia Insert virtual media into a virtual

device.

move Reserved, unimplemented. N/A

nextPage Reference to the next page of a

paginated response.

ova Reserved, unimplemented N/A

ovf References the OVF descriptor of this

vApp template.

power:powerOff Power off this vApp or virtual

machine.

power:powerOn Power on this vApp or virtual

machine.

power:reboot Reboot this vApp or virtual machine. POST

power:reset Reset this vApp or virtual machine. POST

GET

POST

GET

POST

GET

POST

GET

POST

VMware, Inc. 13

vCloud API Programming Guide

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

rel Attribute Value Action or Relationship Description Implied HTTP Verb

power:shutdown Shut down this vApp or virtual

POST

machine.

power:suspend Suspend this vApp or virtual machine. POST

previousPage Reference to the previous page of a

GET

paginated response.

publish Publish this catalog. POST

recompose Recompose this vApp. POST

reconnect Reconnect this vCenter Server to this

POST

cloud.

POST

cloud.

reject Reject this request. POST

relocate Relocate this virtual machine. POST

remove Remove this object. DELETE

repair Repair this ESX/ESXi host. POST

screen:acquireTicket Retrieve a screen ticket for this virtual

GET

machine.

screen:thumbnail Retrieve a thumbnail view of the

GET

screen of this virtual machine.

task:cancel Cancel this task. POST

blockingTask A list of pending blocking task

GET

requests in this cloud.

taskOwner Reference to the owner of a task GET

taskParams Reference to the request parameters of

GET

a task

taskRequest Reference to the request associated

GET

with a task

undeploy Undeploy this vApp. POST

unlock Unlock a user account POST

unregister Unregister this vCenter Server. POST

up References an object that contains this

GET

object.

updateProgress Request an update of this task's

POST

progress.

upgrade Upgrade this ESX/ESXi host. POST

upload:alternate Reserved, unimplemented. N/A

upload:default References the default location to

PUT

which this object can be uploaded.

14 VMware, Inc.

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 rely on the inherent properties of hypermedia to create and modify the state of an object whose serialized representation is accessible at a URL.

If a URL of such an object is known to a client, the client can use an HTTP GET request to retrieve the representation of the object. In the vCloud API, this representation is an XML document. In a RESTful workflow, documents that represent of object state are passed back and forth between a client and a service with the explicit assumption that neither party need know anything about an object other than what is presented in a single request or response. The URLs at which these documents are available 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

Chapter 1 About the VMware vCloud API

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, 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:

What is the set of objects that the API supports, and what do they represent. For example, what is a vDC and how does it relate to an organization or catalog?

How does 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?

How does the client refer 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 this information in the vCloud API XML schemas. The XML elements, attributes, and composition rules defined in these schemas and represent the data structures of objects in the cloud. A client can read an object by making an HTTP GET request to the object’s URL. A client can create or modify an object with an HTTP PUT or POST request that includes a new or changed XML body document for the object. A client can usually delete an object with an HTTP DELETE request.

The vCloud API schema reference includes detailed information about the XML representations of all vCloud API objects and examples of HTTP requests that operate on those objects. See “About the Schema Reference

Downloadable Archive,” on page 19.

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

VMware, Inc. 15

vCloud API Programming Guide

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 representation of an object, including elements and attributes that represent object properties, links that implement operations on the object or provide references to contained or containing objects and, if the object is being created or modified, an embedded task object that tracks the progress of the creation or modification. The response also includes an HTTP response code, which indicates whether the request succeeded or failed, and might be accompanied by a URL that points to a location from which you can retrieve additional information.

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 cloud has a well-known URL from which an unauthenticated user can retrieve a list of vCloud API versions that the server supports. Each version has its own 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 41.

Requests are typically categorized in terms of the type of requested operation: create, retrieve, update, and delete. This sequence of verbs is often abbreviated with the acronym CRUD.

Table 1-2. CRUD Operations Summary

Operation Type HTTP Verb Operation Summary

Create POST Creates a new object.

Retrieve GET Retrieves the representation of an

existing object.

Update PUT Modifies an existing object.

Delete DELETE Deletes an existing object.

Authentication

HTTP communications between a vCloud API client and server are secured with SSL. The vCloud API also implements Basic HTTP Authentication, as defined by RFC 2617, which enables a client to authenticate individual HTTP requests by including an authentication header in the request. See “Logging In,” on page 24.

Request Headers

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

All requests must include an HTTP Accept header that designates the XML namespace in which to process the request. The following header indicates that the request is to be processed in the vCloud API 1.5 namespace:

Accept: application/*+xml;version=1.5

Accept-Encoding

By default, vCloud Director returns response content as uncompressed XML. Compressing the response can improve performance, especially when the response is large and network bandwidth is a factor. To request a response to be returned as compressed XML, include the following header:

Accept-Encoding: gzip

16 VMware, Inc.

Chapter 1 About the VMware vCloud API

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.

Authorization

All requests from authenticated clients must include an Authorization header. See “Logging In,” on page 24 for details about the value of this header.

Content-Type

Requests that include a body must start with the appropriate HTTP Content-

Type header. Content types for all elements are included 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/vnd.vmware.vcloud.catalogItem+xml.

A POST or PUT request that supplies a CatalogItem in the request body requires the following Content-Type header:

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

When it appears as the value of a Content-Type header or the type attribute of an element in the vCloud API, this string is case-insensitive in requests, and can be returned in either mixed case or lowercase characters in responses.

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:

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

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.

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.

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.

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

VMware, Inc. 17

vCloud API Programming Guide

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

201 Created The request is valid. The requested object was created and

202 Accepted The request is valid and a task was created to handle it. This

204 No Content The request is valid and was completed. The response does

303 See Other The response to the request can be found at the URL specified

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

401 Unauthorized An authorization header was expected but not found.

403 Forbidden The requesting user does not have adequate privileges to

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

405 Method Not Allowed The HTTP method specified in the request is not supported

500 Internal Server Error The request was received but could not be completed

501 Not Implemented The server does not implement the request.

503 Service Unavailable One or more services needed to complete the request are not

includes a document body.

can be found at the URL specified in the Location header.

response is usually accompanied by a Task element.

not include a body.

in the Location header.

invalid.

access one or more objects specified in the request.

found in the specified container.

for this object.

because of an internal error at the server.

available on the server.

Using the vCloud API with vCloud Director

VMware vCloud Director 1.5 supports version 1.5 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 examples XML representations. See

“About the Schema Reference Downloadable Archive,” on page 19. For information about HTTP client

programs to use with vCloud Director, see “REST Client Programs,” on page 19.

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 Download the schema reference.

The schema reference is an essential supplement to the vCloud API Programming Guide.

What to do next

Decide on an HTTP client program to use. See “REST Client Programs,” on page 19.

18 VMware, Inc.

Chapter 1 About the VMware vCloud API

REST Client Programs

You can use the vCloud API with any browser or client application that supports HTTP and SSL.

Any client application that can send HTTP requests over a secure channel by using SSL can be an appropriate tool for developing RESTful applications with the vCloud API. The examples in this information were developed using two open-source programs: cURL (http://curl.haxx.se/) and the RESTclient (http://code.google.com/p/rest-client/).

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

http://communities.vmware.com/community/developer/forums.

About the Schema Reference Downloadable Archive

XML schema reference documentation in HTML format for the vCloud API is available as a downloadable archive. This archive also includes the schema definition files, and examples XML representations of vCloud API objects.

To use the reference documentation:

1 Download the compressed archive from

http://www.vmware.com/support/vcd/doc/rest-api-doc-1.5-html.zip

2 Uncompress the archive into any convenient folder.

3 In the folder, open the file index.html in a browser.

How the Schema Reference Documentation is Organized

The schema reference documentation is organized to reflect the division of the vCloud API into user, administrator, and extension categories. Within each category, you can open a list of elements, types that the elements extend, and operations that create, retrieve, update, or delete the objects that the elements represent.

User Operations, Elements, and Types

Administrator Operations, Elements, and Types

Extension Operations, Elements, and Types

These operations are performed by all users who have permission to log into an organization. User elements and user types represent the objects that these operations manipulate. See Chapter 3, “Exploring a Cloud,” on page 41,

Chapter 4, “Provisioning an Organization with vApps, Templates, and Media,” on page 53, Chapter 5, “Deploying and Operating vApps,” on

page 75, and Chapter 2, “Hello vCloud: A Simplified RESTful Workflow,” on page 23.

These operations are performed by organization administrators or system administrators. Administrator elements and types represent the objects that these operations manipulate. See Chapter 6, “Creating, Provisioning, and

Managing Organizations,” on page 109.

These operations are performed by system administrators who need access to vSphere platform objects from the vCloud API. Extension elements and types represent the objects that these operations manipulate. See Chapter 7, “Using

vCloud API Extensions to Provision and Manage a Cloud,” on page 161.

VMware, Inc. 19

vCloud API Programming Guide

Searching In a Category

You can enter a search string in the Quick Index text box to search the lists of operations, elements, and types in any category.

In an Operations list, you can search for the following items:

All or part of the name of the object on which you want to operate. The search returns a list of all of the operations that are possible on that object. For example, selecting User Operations and typing

vApp in the Quick Index text box returns a list of all of the requests that operate on a vApp object.

The name of an action to perform. For example, selecting User Operations and typing power in the Quick Index text box returns a list of all the requests that change the power state of a vApp.

An HTTP verb (GET, PUT, POST, DELETE) to view a list of all the requests that use that verb. For example, selecting User Operations and typing PUT in the Quick Index text box returns a list of all of the requests that update an object.

In an Elements or Types list, type all or part of the element or type name.

Search terms are not case-sensitive.

Operation Summary Syntax

Operations consist of an HTTP verb and a request URL. The reference documentation represents the verb and the URL using the following syntax:

HTTP_VERB /object_type/{id}[/action/action_name]

In this syntax, the initial / character is assumed to follow a site-specific API URL, such as

https://vcloud.example.com/api. The following strings represent variables in the remainder of the URL:

HTTP_VERB

object_type

The HTTP verb used to request the operation.

An abbreviation of the MIME type of the object referenced by the operation. This abbreviation is constructed from the final component of the object's media type, between the . and the +xml designation. For example, for an object whose media type is application/vnd.vmware.vcloud.catalogItem+xml, the

{id}

action_name

object_type

The unique identifier of the object of the operation.

The name of an action. Required only when the operation request URL includes

is shown as catalogItem.

the string /action/.

Element and Type Reference Pages

For each element or complex type, the reference documentation provides a page that lists the following items:

Element

Type

The name of the element.

The name of the type that the element extends.

Namespace

Description

Since

Schema

The XML namespace in which this element or type name is defined.

A description of the purpose and contents of the element or type.

The vCloud API version in which this element or type first appeared.

The name of the XML schema definition file in which this element or type is defined. Click to open the file in your browser, or right-click to download it.

Media Type

20 VMware, Inc.

The MIME type associated with this element or type.

Chapter 1 About the VMware vCloud API

Extends

XML Representation

Attributes

Elements

The base type from which this element is derived.

The XML representation of the element or type. Names of contained elements are links to the reference pages for those elements.

A table listing the following properties of each attribute of the element or type:

Attribute

Type

Required

The name of the attribute.

The primitive XML type of the attribute.

Yes for attributes that are required. No for attributes

that are optional.

Modifiable

A value of always means that a client request can modify the value of this attribute. A value of create means that this attribute can be set or modified only as part of object creation. A value of none means that this attribute is read-only.

Since

The vCloud API version in which this attribute first appeared.

Description

A description of the purpose and contents of the attribute.

A table listing the following properties of each element defined in the type:

Element

Type

Occurrence

Modifiable

Since

Description

The name of the element.

A link to the definition of the complex type that the element is based on.

The occurrence constraint for the element. The constraint can be one of the following expressions:

0..*

Optional. Can occur zero or more times.

0..1

Optional. Can occur at most once.

Required. Must occur exactly once.

A value of always means that a client request can modify the contents of this element. A value of

create means that element contents can be set or

modified only as part of object creation. A value of

none means that this element is read-only.

The vCloud API version in which this element first appeared.

A description of the purpose and contents of the element.

Operations

A summary of the operations permitted on the element. Operations are categorized by request type; one of create, retrieve, update, and delete. This sequence of verbs is often abbreviated with the acronym CRUD.

VMware, Inc. 21

vCloud API Programming Guide

Schema Definition Files

XML schema definition files (*.xsd) are included in the etc folder of schema reference downloadable archive. This folder contains several subfolders:

1.0

1.5

schemas

Schema definition files for vCloud API version 1.0.

Schema definition files for vCloud API version 1.5.

Additional schema definition files that are version-independent or from external sources such as DMTF.

About the vCloud API Examples

The vCloud API Programming Guide 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 17. Most example responses show only those elements and attributes that are relevant to the operation being discussed. Ellipses (…) indicate omitted content within response bodies. Several additional conventions apply.

The following HTTP header, which is required in all requests that access version 1.5 of the vCloud API, is omitted from most examples.

Accept: application/*+xml;version=1.5

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.

The XML version and encoding header

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

is included in example requests but omitted from example responses.

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.

22 VMware, Inc.

Hello vCloud: A Simplified RESTful

Workflow 2

vCloud API clients and vCloud Director servers communicate over HTTP, 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.

1 Logging In on page 24

vCloud Director requires API requests to be authenticated. The first step in any RESTful workflow is to obtain an authentication token.

2 Find a Catalog and a vDC on page 26

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 27

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

VMware, Inc.

4 Retrieve a Catalog Item on page 28

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.

5 Retrieve Deployment Information From the vDC on page 30

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

6 Deploy the vApp on page 31

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.

7 Get Information About a vApp on page 34

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.

vCloud API Programming Guide

8 Displaying the Virtual Machine Console on page 37

After a vApp is powered on, you can retrieve a screen ticket from one of its virtual machines. You use that ticket with the VMRC browser plug-in to gain access to the console of the virtual machine.

9 Delete the vApp on page 38

To delete the vApp, power it off, undeploy it, and then use an HTTP DELETE request to delete the vApp object.

10 Log Out on page 39

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

Logging In

vCloud Director requires API requests to be authenticated. The first step in any RESTful workflow is to obtain an authentication token.

Every cloud has a login URL that a client can obtain by making an unauthenticated GET request to the vCloud Director api/versions URL. See “Retrieve the Login URL and List of Supported API Versions,” on page 42. Because all other vCloud API requests must be authenticated, any vCloud API workflow must begin with a login request that supplies user credentials in the form that Basic HTTP authentication requires.

For information about how to create a login request and view the response, see “Example: Login Request and

Response,” on page 25.

Prerequisites

Verify that the following conditions are met:

You know the username and password of the system administrator or a member of one of the organizations in the cloud. The Hello vCloud workflow requires you to log in as a user who has permission to create and operate vApps.

You have access to an organization in which at least one vDC was created and provisioned with a network. For more information about setting up an organization to support the Hello vCloud workflow, see

Chapter 6, “Creating, Provisioning, and Managing Organizations,” on page 109.

The 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 with vApps,

Templates, and Media,” on page 53.

Procedure

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

2 Use the login URL to create a login session.

POST a request to this URL that includes your username, password, and organization name in a MIME Base64 encoding. See “Example: Login Request and Response,” on page 25.

3 Examine the response.

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

A successful login request returns an authentication token that you can use in subsequent requests. It also returns a Session element, which contains one or more Link elements, each of which provides a URL that you can use to explore a subset of objects in the cloud. If you log in as a system administrator or organization administrator, this list includes multiple links. See “Example: Create a Login Session,” on page 44. Otherwise, the list typically includes a link of type application/vnd.vmware.vcloud.orgList+xml, as shown in the response portion of “Example: Login Request and Response,” on page 25. You can use this link to find out more about your organization and the objects it contains.

For more information about the other links in the Session element, see “Create a Login Session,” on page 44.

24 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

Example: Login Request and Response

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

user@organization:password

user is the user's login name.

organization is the name of an organization of which the user is a member.

password is the user's password.

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

NOTE System administrators must log in to the System organization. See “Administrator Credentials and

Privileges,” on page 111.

This example shows a login request and response for a user named HelloUser logging into an organization named ExampleOrg in a cloud whose login URL is https://vcloud.example.com/api/sessions.

Request:

POST https://vcloud.example.com/api/sessions Authorization: Basic Accept: application/*+xml;version=1.5

encoded-credentials

Response:

200 OK x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM= Content-Type: application/vnd.vmware.vcloud.session+xml;version=1.5 ... <Session xmlns="http://www.vmware.com/vcloud/v1.5" user="HelloUser" org="ExampleOrg" ... > <Link rel="down" type="application/vnd.vmware.vcloud.orgList+xml" href="https://vcloud.example.com/api/org"/> <Link rel="down" type="application/vnd.vmware.vcloud.query.queryList+xml" href="https://vcloud.example.com/api/query" /> <Link rel="entityResolver" type="application/vnd.vmware.vcloud.entity+xml" href="https://vcloud.example.com/api/entity/" /> </Session>

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

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

x-vcloud-authorization:

token

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

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

VMware, Inc. 25

vCloud API Programming Guide

If the credentials supplied in the authentication header are invalid, or if the token has expired, the server returns HTTP response code 401. The token expires after a configurable interval of client inactivity. The default is 30 minutes after the token is created. After the token expires, you must log in again to obtain a new token.

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, vDCs, and networks.

Prerequisites

Verify that you are logged in as a system administrator or member of an organization in the cloud.

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 https://vcloud.example.com/api/org/

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

2 Retrieve the representation of your organization.

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

3 Examine the response to find the links to the organization's catalogs, networks, and vDCs.

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

Example: Retrieve the Contents of an Organization

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

Request:

GET https://vcloud.example.com/api/org/5

Response:

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

26 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

type="application/vnd.vmware.vcloud.org+xml" href="https://vcloud.example.com/api/org/5"> <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="https://vcloud.example.com/api/catalog/32" name="ExampleCatalog" /> <Link rel="down" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5" name="ExampleVdc01" /> <Link rel="down" type="application/vnd.vmware.vcloud.network+xml" href="https://vcloud.example.com/api/network/14" name="IsolatedOrgNet" /> <Link rel="down" type="application/vnd.vmware.vcloud.network+xml" href="https://vcloud.example.com/api/network/54" name="Internet" /> <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:

A catalog named ExampleCatalog, at URL https://vcloud.example.com/api/catalog/32, where you can look for vApp templates.

A vDC named ExampleVdc01, at URL https://vcloud.example.com/api/vdc/5, where you can deploy the vApp.

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

IsolatedOrgNet, at URL https://vcloud.example.com/api/network/14. You can connect the vApp to either

of these networks.

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 available from 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

Verify that you are logged in as a system administrator or member of an organization in the cloud.

Procedure

1 Retrieve the XML representation of your organization.

Use a request like this one:

GET https://vcloud.example.com/api/org/5

VMware, Inc. 27

vCloud API Programming Guide

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

These links have the following form:

<Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="https://vcloud.example.com/api/catalog/id" name="

catalog_name

" />

3 Retrieve the contents of the catalog.

Use a GET request of the form shown in the request portion of “Example: Retrieving the Contents of a

Catalog,” on page 28.

Example: Retrieving 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 26.

Request:

GET https://vcloud.example.com/api/catalog/32

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.catalog+xml ... <Catalog xmlns="http://www.vmware.com/vcloud/v1.5" name="ExampleCatalog" type="application/vnd.vmware.vcloud.catalog+xml" href="https://vcloud.example.com/api/catalog/32"> <Description>Main Org Catalog</Description> <CatalogItems> <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu Template with vsftpd" href="https://vcloud.example.com/api/catalogItem/221"/> <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 29, 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.

28 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

Prerequisites

Verify that you are logged in as a system administrator or member of an organization in the cloud.

Procedure

1 Retrieve the representation of a catalog in your organization.

Use a request like this one:

GET https://vcloud.example.com/api/catalog/32

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

Example: Retrieve a Catalog Item

This example retrieves the CatalogItem shown in the response portion of “Example: Retrieving the Contents

of a Catalog,” on page 28.

Request:

GET https://vcloud.example.com/api/catalogItem/221

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/vnd.vmware.vcloud.catalogItem+xml ... <CatalogItem xmlns="http://www.vmware.com/vcloud/v1.5" name="Ubuntu Template with vsftpd" id="urn:vcloud:catalogitem:221" href="https://vcloud.example.com/api/catalogItem/221" ... > <Link rel="up" type="application/vnd.vmware.vcloud.catalog+xml" href="https://vcloud.example.com/api/catalog/32" /> <Link rel="down" type="application/vnd.vmware.vcloud.metadata+xml" href="https://vcloud.example.com/api/catalogItem/221/metadata" /> <Link rel="edit" type="application/vnd.vmware.vcloud.catalogItem+xml" href="https://vcloud.example.com/api/catalogItem/221" /> <Link rel="remove" href="https://vcloud.example.com/api/catalogItem/221" /> <Description>Approved template for public FTP sites</Description> <Entity

VMware, Inc. 29

vCloud API Programming Guide

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

Retrieve Deployment Information From the vDC

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

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

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

A list of networks to which the vApp can connect.

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

Prerequisites

Verify that the following conditions are met:

Verify that you are logged in as a system administrator or member of an organization in the cloud.

Retrieve the representation of your organization. See the request portion of “Example: Retrieve the

Contents of an Organization,” on page 26. The response portion contains links to the organization's vDCs.

Procedure

1 Examine the Org response to find the links to the organization's vDCs.

Links to vDCs have the form:

<Link rel="down" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/ name="

vDC_name

" />

2 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 30.

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 https://vcloud.example.com/api/vdc/5

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.vdc+xml ... <Vdc xmlns="http://www.vmware.com/vcloud/v1.5" name="ExampleVdc01" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5">

30 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

... <Link rel="add" type="application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml" href="https://vcloud.example.com/api/vdc/5/action/instantiateVAppTemplate" /> ... <AvailableNetworks> <Network href="https://vcloud.example.com/api/network/14" type="application/vnd.vmware.vcloud.network+xml" name="IsolatedOrgNet" /> <Network href="https://vcloud.example.com/api/network/54" type="application/vnd.vmware.vcloud.network+xml" name="Internet" /> </AvailableNetworks> ... </Vdc>

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

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

A list of AvailableNetworks that includes all the networks in the organization that contains this vDC.

Deploy the vApp

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.

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.

Prerequisites

Verify that you are logged in as a system administrator or member of an organization in the cloud.

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.

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 32 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. 31

vCloud API Programming Guide

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 it 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 32.

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,” on page 79. The InstantiateVAppTemplateParams includes the following information:

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.

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

Configuration parameters for a vApp network, supplied in the NetworkConfigSection element. This specification includes the following parameters:

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:

A reference to the organization 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 30.

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

For more information about creating networks with the vCloud API, see “About vCloud Director

Networks,” on page 118.

The target of the request is the instantiateVAppTemplate URL of this vDC. See “Example: Deployment

Information in a vDC,” on page 30. Because the operation creates a new vApp object, the HTTP request type

is POST.

Request:

32 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <Description>Example FTP Server</Description> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks </ovf:Info> <NetworkConfig networkName="vAppNetwork"> <Configuration> <ParentNetwork href="https://vcloud.example.com/api/network/54" /> <FenceMode>bridged</FenceMode> </Configuration> </NetworkConfig> </NetworkConfigSection> </InstantiationParams> <Source href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" /> </InstantiateVAppTemplateParams>

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

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

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

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

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/vnd.vmware.vcloud.vApp+xml ... <VApp xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" deployed="false" status="0" name="Linux FTP server" type="application/vnd.vmware.vcloud.vApp+xml" href="https://vcloud.example.com/api/vApp/vapp-7"> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5"/> <Description>Example FTP Server vApp</Description> <Tasks> <Task status="running" operation="Creating Virtual Application Linux FTP server(7)"

VMware, Inc. 33

vCloud API Programming Guide

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

Get Information About a vApp

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

Verify that you are logged in as a system administrator or member of an organization in the cloud.

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

Example: Getting Information About the vApp

This response reveals several things about the vApp:

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

Creation Status,” on page 236.

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

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, such as acquiring a screen ticket or thumbnail, and inserting or removing media, are specific to a virtual machine. Other actions, like shutdown and reboot, can be applied to either object. See Chapter 5, “Deploying and Operating vApps,” on page 75.

Request:

GET https://vcloud.example.com/api/vApp/vapp-7

34 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.vApp+xml ... <VApp status="4" name="Linux FTP server" type="application/vnd.vmware.vcloud.vApp+xml" href="https://vcloud.example.com/api/vApp/vapp-7" ... > ... <Link rel="power:reboot" href="https://vcloud.example.com/api/vApp/vapp-7/power/action/reboot" /> <Link rel="power:powerOff" href="https://vcloud.example.com/api/vApp/vapp-7/power/action/powerOff" /> <Link rel="undeploy" href="https://vcloud.example.com/api/vApp/vapp-7/action/undeploy" /> <Link rel="deploy" href="https://vcloud.example.com/api/vApp/vapp-7/action/deploy" /> <Link rel="power:shutdown" href="https://vcloud.example.com/api/vApp/vapp-7/power/action/shutdown" /> <Link rel="power:reset" href="https://vcloud.example.com/api/vApp/vapp-7/power/action/reset" /> <Link rel="power:suspend" href="https://vcloud.example.com/api/vApp/vapp-7/power/action/suspend" /> <Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml" href="https://vcloud.example.com/api/vApp/vapp-7/controlAccess/" /> <Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml" href="https://vcloud.example.com/api/vApp/vapp-7/action/controlAccess/" /> ... <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

VMware, Inc. 35

vCloud API Programming Guide

href="https://vcloud.example.com/api/vApp/vapp-7/networkConfigSection/" ovf:required="false"> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConfigSection+xml" href="https://vcloud.example.com/api/vApp/vapp-7/networkConfigSection/" /> <ovf:Info>Configuration parameters for vAppNetwork</ovf:Info> <NetworkConfig networkName="vAppNetwork"> <Configuration> <IpScope> ... </IpScope> <ParentNetwork type="application/vnd.vmware.vcloud.network+xml" name="Internet" href="https://vcloud.example.com/api/network/54" /> <FenceMode>bridged</FenceMode> </Configuration> <IsDeployed>true</IsDeployed> </NetworkConfig> </NetworkConfigSection> <Children> <Vm deployed="true" status="4" name="ubuntu10-x86" type="application/vnd.vmware.vcloud.vm+xml" href="https://vcloud.example.com/api/vApp/vm-4"> ... <Link rel="power:reboot" href="https://vcloud.example.com/api/vApp/vm-4/power/action/reboot" /> <Link rel="power:powerOff" href="https://vcloud.example.com/api/vApp/vm-4/power/action/powerOff" /> <Link rel="undeploy" href="https://vcloud.example.com/api/vApp/vm-4/action/undeploy" /> <Link rel="deploy" href="https://vcloud.example.com/api/vApp/vm-4/action/deploy" /> <Link rel="power:shutdown" href="https://vcloud.example.com/api/vApp/vm-4/power/action/shutdown" /> <Link rel="power:reset" href="https://vcloud.example.com/api/vApp/vm-4/power/action/reset" /> <Link rel="power:suspend" href="https://vcloud.example.com/api/vApp/vm-4/power/action/suspend" /> <Link rel="up" type="application/vnd.vmware.vcloud.vApp+xml" href="https://vcloud.example.com/api/vApp/vapp-7" />

36 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

<Link rel="screen:thumbnail" href="https://vcloud.example.com/api/vApp/vm-4/screen" /> <Link rel="screen:acquireTicket" href="https://vcloud.example.com/api/vApp/vm-4/screen/action/acquireTicket" /> <Link rel="media:insertMedia" type="application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml" href="https://vcloud.example.com/api/vApp/vm-4/media/action/insertMedia" /> <Link rel="media:ejectMedia" type="application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml" href="https://vcloud.example.com/api/vApp/vm-4/media/action/ejectMedia" /> ... <Description /> <ovf:VirtualHardwareSection> ... </ovf:VirtualHardwareSection> ... <NetworkConnectionSection> ... <NetworkConnection> network="vAppNetwork"> <NetworkConnectionIndex>0</NetworkConnectionIndex> <IpAddress>10.147.201.10</IpAddress> <IsConnected>true</IsConnected> <MACAddress>00:50:56:01:01:49</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 one of its virtual machines. You use that ticket with the VMRC browser plug-in to gain access to the console of the virtual machine.

A screen ticket is a string that includes the virtual machine’s IP address, its managed object reference, and a residual that is encoded as described in RFC 2396. Each Vm element in a vApp includes a link where

rel="screen:acquireTicket" if the virtual machine it represents is powered on. You can use that link to retrieve

a screen ticket that you can use with the VMRC API to open a VMware Remote Console for the virtual machine.

NOTE You cannot access virtual machines in vCenter with the version of vmware-vmrc that vCloud Director installs.

Prerequisites

Verify that you are logged in as a system administrator or member of an organization in the cloud.

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

VMware, Inc. 37

vCloud API Programming Guide

Verify that your browser has an installed copy of the vmware-vmrc plug-in. This plug-in is installed by your browser whenever you use the vCloud Director Web Console to access the console of a running virtual machine. After this plug-in is installed, you can find it in the folder where your browser stores plug-ins.

Procedure

1 Retrieve the screen ticket.

POST a request to the acquireTicket link of the Vm.

Request:

POST https://vcloud.example.com/api/vApp/vm-4/screen/action/acquireTicket

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.screenTicket+xml ... <ScreenTicket xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1 ...> </ScreenTicket>

The ticket string itself has the following form:

ticket-string

mks://

ip-address/VM-MoRef

ip-address is the IP address of the virtual machine.

VM-MoRef is the managed object reference of the virtual machine.

encoded-ticket is the encoded screen ticket. You must decode this ticket using a function such as the Java URLDecoder or PERL url_escape before you can use it.

2 Use the ticket with the VMRC API.

The ticket is valid for 30 seconds. To use it, you must initialize the VMRC browser plug-in and use the VMRC API, as described in the VMware Technical Note Using the VMRC API.

Delete the vApp

To delete the vApp, power it off, undeploy it, and then use an HTTP DELETE request to delete the vApp object.

A powered-on vApp has a link that you can use with a POST request to power it off. A powered-off vApp has a link that you can use with a DELETE request to remove it.

Prerequisites

Verify that you are logged in as a system administrator or member of an organization in the cloud.

Procedure

1 Retrieve the XML representation of the vApp.

Make a GET request to the URL provided in the href attribute of the VApp element returned when you created the vApp from the template. See “Get Information About a vApp,” on page 34.

/ticket=

encoded-ticket

2 Power off the vApp.

Make a POST request to the vApp's power/action/powerOff link, which has the following form:

38 VMware, Inc.

Chapter 2 Hello vCloud: A Simplified RESTful Workflow

3 Retrieve the XML representation of the vApp again.

a Verify that the value of its status attribute is 8, which indicates that it is powered off.

b Verify that it includes a rel="remove" link of the following form:

4 Remove the vApp.

Make a DELETE request to the vApp's rel="remove" link, as shown in the request portion of

“Example: Delete a vApp,” on page 39.

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: Delete a vApp

Request:

DELETE https://vcloud.example.com/api/vApp/vapp-7

Response:

202 Accepted ... <Task xmlns="http://www.vmware.com/vcloud/v1.5" status="running" startTime="2010-06-25T08:10:23.650-07:00" operation="Deleting Virtual Application Linux FTP server (7)" expiryTime="2010-09-23T08:00:55.402-07:00" type="application/vnd.vmware.vcloud.task+xml" href="https://vcloud.example.com/api/task/3478" ... > </Task>

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

Prerequisites

Verify that you are logged in.

Procedure

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.

VMware, Inc. 39

vCloud API Programming Guide

Request:

DELETE https://vcloud.example.com/api/session x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM=

Response:

200 OK

40 VMware, Inc.

Exploring a Cloud 3

You can use HTTP GET requests in a process of serial discovery 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, where 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. This list is based on your role and privileges.

This chapter includes the following topics:

“Summary of vCloud API Browsing Requests,” on page 41

“Retrieve the Login URL and List of Supported API Versions,” on page 42

“Create a Login Session,” on page 44

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

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

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

Summary of vCloud API Browsing Requests

Browsing requests provide read-only access to a cloud and the objects it contains.

API-URL is a URL of the form https://vcloud.example.com/api.

id is a unique identifier in the form of a UUID, as defined by RFC 4122.

Request URLs are always available when you GET the representation of the object on which they operate. URL forms are for reference purposes only. For more information about the requests and responses for each operation, see “About the Schema Reference Downloadable Archive,” on page 19.

Table 3-1. Summary of vCloud API Browsing Requests

Operation Request Request Body Response

Show login URL and list of supported API versions

VMware, Inc. 41

GET API-URL/versions None

SupportedVersions

Session

vCloud API Programming Guide

Table 3-1. Summary of vCloud API Browsing Requests (Continued)

Operation Request Request Body Response

Log out [NEW] DELETE API-URL/session None 200 OK

Log out [DEPRECATED] POST API-URL/login None 200 OK

Retrieve a list of entry points for browsing operations [NEW]

Retrieve a list of organizations to which you have access

Retrieve the contents of an organization

Retrieve properties of a network

Retrieve the contents of a catalog

Retrieve properties of a catalog item

Retrieve the contents of a vDC

Retrieve properties of a media image

Retrieve a vApp template GET API-

Retrieve properties of a vApp GET API-URL/vApp/vapp-idNone

OrgLIst

GET API-URL/session None 200 OK

GET API-URL/org/ None

GET API-URL/org/id None

GET API-URL/network/id None

GET API-URL/catalog/id None

GET API- URL/catalogItem/id

GET API-URL/vdc/id None

GET API-URL/media/id None

URL/vAppTemplate/vappT emplate-id

None

OrgList

Org

OrgNetwork

Catalog

CatalogItem

Vdc

Media

VAppTemplate

VApp

Retrieve properties of a virtual machine

GET API-URL/vApp/vm-id None

Retrieve the Login URL and List of Supported API Versions

Every cloud has a login URL that a client can obtain by making an unauthenticated GET request to the vCloud Director api/versions URL. The response to this request also lists vCloud API versions that the server supports.

Procedure

1 Make an API version request to vCloud Director to obtain the login URL for the REST API.

See the request portion of “Example: Versions Request and Response,” on page 43.

2 Examine the response to find the login URLs.

Each version of the vCloud API that the server supports has its own login URL. Look for a line of the following form:

<LoginUrl>http://vcloud.example.com/api/...</LoginUrl>

3 Use the login URL to log in to the cloud.

42 VMware, Inc.

Chapter 3 Exploring a Cloud

Example: Versions Request and Response

The api/versions request does not need to be authenticated. The response, a small subset of which is shown here, includes a VersionInfo element for each API version that the server supports. Each VersionInfo element contains:

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

MediaTypeMapping elements for each complex type supported by that version of the vCloud API.

Request:

GET http://vcloud.example.com/api/versions

Response:

200 OK Content-Type: text/xml ... <SupportedVersions xmlns="http://www.vmware.com/vcloud/versions" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/versions http://vcloud.example.com/api/versions/schema/versions.xsd"> <VersionInfo> <Version>1.0</Version> <LoginUrl>https://vcloud.example.com/api/login</LoginUrl> <MediaTypeMapping> <MediaType>application/vnd.vmware.vcloud.catalog+xml</MediaType> <ComplexTypeName>CatalogType</ComplexTypeName> <SchemaLocation>http://vcloud.example.com/api/v1.0/schema/master.xsd</SchemaLocation> </MediaTypeMapping> <MediaTypeMapping> ... </MediaTypeMapping> </VersionInfo> <VersionInfo> <Version>1.5</Version> <LoginUrl>https://vcloud.example.com/api/sessions</LoginUrl> <MediaTypeMapping> <MediaType>application/vnd.vmware.vcloud.catalog+xml</MediaType> <ComplexTypeName>CatalogType</ComplexTypeName> <SchemaLocation>http://vcloud.example.com/api/v1.5/schema/master.xsd</SchemaLocation> </MediaTypeMapping> <MediaTypeMapping> ... </MediaTypeMapping> ... </VersionInfo> </SupportedVersions>

NOTE You can use the URL in the SchemaLocation element with a GET request to retreive the file in which that complex type is defined. For example:

GET http://vcloud.example.com/api/v1.5/schema/master.xsd

VMware, Inc. 43

vCloud API Programming Guide

Create a Login 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.

Prerequisites

Verify that you know the login URL. See “Retrieve the Login URL and List of Supported API Versions,” on page 42

Verify that you know the username and password of the system administrator or a member of one of the organizations in the cloud.

System administrators must log in to the System organization. See “Administrator Credentials and

Privileges,” on page 111.

Procedure

1 Use the login URL to authenticate to the cloud.

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,” on page 44.

2 Examine the response.

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

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

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

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

x-vcloud-authorization:

token

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

The Session element returned from a successful login contains one or more URLs from which you can begin browsing.

The list of URLs in the Session object is based on the role and privileges of the authenticated user. 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 165.

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

Example: Create a Login Session

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

user@organization:password

user is the user's login name.

organization is the name of an organization of which the user is a member.

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 login request and response for a system administrator logging in to a cloud whose

sessions URL is https://vcloud.example.com/api/sessions.

44 VMware, Inc.

Request:

POST https://vcloud.example.com/api/sessions Authorization: Basic Accept: application/*+xml;version=1.5

encoded-credentials

Response:

200 OK x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM= Content-Type: application/vnd.vmware.vcloud.session+xml ... <Session xmlns="http://www.vmware.com/vcloud/v1.5" user="sysadmin" org="System" ... > <Link rel="down" type="application/vnd.vmware.vcloud.orgList+xml" href="https://vcloud.example.com/api/org"/> <Link rel="down" type="application/vnd.vmware.admin.vcloud+xml" href="https://vcloud.example.com/api/admin"/> <Link rel="down" type="application/vnd.vmware.admin.vmwExtension+xml" href="https://vcloud.example.com/api/admin/extension"/> <Link rel="down" type="application/vnd.vmware.vcloud.query.queryList+xml" href="https://vcloud.example.com/api/query" /> <Link rel="entityResolver" type="application/vnd.vmware.vcloud.entity+xml" href="https://vcloud.example.com/api/entity/" /> </Session>

Chapter 3 Exploring a Cloud

This response includes the following link types:

orgList

A link to the list of organizations that you can access. See “Retrieve a List of

Organizations Accessible to You,” on page 46.

vcloud

A link to administrative objects and operations. See Chapter 6, “Creating,

Provisioning, and Managing Organizations,” on page 109

vmwExtension

A link to the vCloud API extensions, accessible to a system administrator. See

Chapter 7, “Using vCloud API Extensions to Provision and Manage a Cloud,” on page 161.

queryList

A link to the set of typed queries you can run. See Chapter 9, “Using the Query

Service,” on page 201.

entity

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

VMware, Inc. 45

vCloud API Programming Guide

Retrieve a List of Organizations Accessible to You

A successful login request returns a Session element, which contains a link to a list of all 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. For an ordinary user, this list includes just the organization to which the user logged in. For an organization administrator or system administrator, the list includes all organizations in the cloud.

Prerequisites

Create a login session. See “Create a Login Session,” on page 44.

Procedure

1 Retrieve the XML representation of your Session object.

Use a request like this one:

GET https://vcloud.example.com/api/session

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

This link has the following form:

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

Example: Retrieve an Organization List

Request:

GET https://vcloud.example.com/api/org

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/vnd.vmware.vcloud.orgList+xml ... <OrgList xmlns="http://www.vmware.com/vcloud/v1.5" type="application/vnd.vmware.vcloud.orgList+xml" href="https://vcloud.example.com/api/org"> <Org type="application/vnd.vmware.vcloud.org+xml" name="ExampleOrg"

46 VMware, Inc.

href="https://vcloud.example.com/api/org/5" /> <Org ... /> <Org ... /> </OrgList>

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.

Chapter 3 Exploring a Cloud

Prerequisites

Use the credentials of an organization administrator or system administrator to create a login session. See

“Create a Login Session,” on page 44.

Procedure

1 Retrieve the XML representation of your Session object.

Use a request like this one:

GET https://vcloud.example.com/api/session

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

This link has the following form:

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 47

Example: Retrieve an Administrative View of a Cloud

Request:

GET https://vcloud.example.com/api/admin

Response:

200 OK Content-Type: application/vnd.vmware.admin.vcloud+xml ... <VCloud

VMware, Inc. 47

vCloud API Programming Guide

xmlns="http://www.vmware.com/vcloud/v1.5" name="vCloud" href="https://vcloud.example.com/api/admin"> <Link rel="add" type="application/vnd.vmware.admin.role+xml" href="https://vcloud.example.com/api/admin/roles" /> <Link rel="add" type="application/vnd.vmware.admin.organization+xml" href="https://vcloud.example.com/api/admin/orgs" /> <Link rel="down" type="application/vnd.vmware.admin.systemOrganization+xml" name="System" href="https://vcloud.example.com/api/admin/org/99" /> <Description>Example Corporation’s vCloud</Description> <OrganizationReferences> <OrganizationReference type="application/vnd.vmware.admin.organization+xml" name="Engineering" href="https://vcloud.example.com/api/admin/org/1"/> <OrganizationReference type="application/vnd.vmware.admin.organization+xml" name="Engineering" href="https://vcloud.example.com/api/admin/org/44"/> <OrganizationReference ... /> ... </OrganizationReferences> <ProviderVdcReferences> <ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="Main Provider" href="https://vcloud.example.com/api/admin/providervdc/2" /> <ProviderVdcReference ... /> ... </ProviderVdcReferences> <RightReferences> <RightReference type="application/vnd.vmware.admin.right+xml name="vApp_Deploy" href="https://vcloud.example.com/api/admin/right/3" /> <RightReference type="application/vnd.vmware.admin.right+xml name="Catalog:Sharing" href="https://vcloud.example.com/api/admin/right/7" /> <RightReference ... /> ... </RightReferences> <RoleReferences> <RoleReference type="application/vnd.vmware.admin.role+xml" name="Organization Administrator" href="https://vcloud.example.com/api/admin/role/102" /> <RoleReference

48 VMware, Inc.

Chapter 3 Exploring a Cloud

type="application/vnd.vmware.admin.role+xml" name="Catalog Creator" href="https://vcloud.example.com/api/admin/role/103" /> <RoleReference /> </RoleReferences> <Networks> <Network type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1" href="https://vcloud.example.com/api/admin/network/7" /> <Network type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC2" href="https://vcloud.example.com/api/admin/network/33" /> </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, ESX/ESXi, and vShield Manager. The VMWExtension element provides access to a cloud-wide namespace of vSphere platform objects that are registered for use by the cloud, and links that allow you to add vSphere servers and related resources such as networks and resource pools to your cloud. The administrative extensions to the vCloud API 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 Login Session,” on page 44.

Procedure

1 Retrieve the XML representation of your Session object.

Use a request like this one:

GET https://vcloud.example.com/api/session

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

This link has the following form:

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

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

Request:

GET https://vcloud.example.com/api/admin/extension

VMware, Inc. 49

vCloud API Programming Guide

Response:

200 OK Content-Type: application/vnd.vmware.admin.vmwextension+xml ... <vmext:VMWExtension xmlns:vmext="http://www.vmware.com/vcloud/extension/v1.5" xmlns:vcloud="http://www.vmware.com/vcloud/v1.5" type="application/vnd.vmware.admin.vmwExtension+xml"> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwProviderVdcReferences+xml" href="https://vcloud.example.com/api/admin/extension/providerVdcReferences" /> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwExternalNetworkReferences+xml" href="https://vcloud.example.com/api/admin/extension/externalNetworkReferences" /> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwNetworkPoolReferences+xml" href="https://vcloud.example.com/api/admin/extension/networkPoolReferences" /> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwVimServerReferences+xml" href="https://vcloud.example.com/api/admin/extension/vimServerReferences" /> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwHostReferences+xml" href="https://vcloud.example.com/api/admin/extension/hostReferences" /> <vcloud:Link rel="down" type="application/vnd.vmware.admin.systemSettings+xml" href="https://vcloud.example.com/api/admin/extension/settings" /> <vcloud:Link rel="add" type="application/vnd.vmware.admin.vmwprovidervdc+xml" href="https://vcloud.example.com/api/admin/extension/providervdcs" /> <vcloud:Link rel="add" type="application/vnd.vmware.admin.vmwexternalnet+xml" href="https://vcloud.example.com/api/admin/extension/externalnets" /> <vcloud:Link rel="add" type="application/vnd.vmware.admin.networkPool+xml" href="https://vcloud.example.com/api/admin/extension/networkPools" /> <vcloud:Link rel="add" type="application/vnd.vmware.admin.registerVimServerParams+xml" href="https://vcloud.example.com/api/admin/extension/action/registervimserver" /> <vcloud:Link rel="down" type="application/vnd.vmware.admin.licensingReportList+xml" href="https://vcloud.example.com/api/admin/extension/licensing/reports" /> <vcloud:Link rel="down" type="application/vnd.vmware.admin.datastoreList+xml"

50 VMware, Inc.

href="https://vcloud.example.com/api/admin/extension/datastores" /> <vcloud:Link rel="blockingTask" type="application/vnd.vmware.admin.blockingTaskList+xml" href="https://vcloud.example.com/api/admin/extension/blockingTasks/" /> </vmext:VMWExtension>

Chapter 3 Exploring a Cloud

VMware, Inc. 51

vCloud API Programming Guide

52 VMware, Inc.

Provisioning an Organization with

vApps, Templates, and Media 4

The vCloud API provides several ways for you to make vApp templates, vApps, and media images available to users in an organization.

With the vCloud API, you can upload and download OVF packages, and upload media images. Transfer operations are characterized as uploads when the operation transfers content from the local host to a remote host, and as downloads when the local host requests the transfer of content from a remote host. A POST request initiates uploads, and a GET request initiates downloads. The vCloud Director transfer service facilitates uploads and downloads and provides temporary storage for files. After they are uploaded, you can add templates and media images to catalogs as needed.

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

Cloning

Capturing

Importing

This chapter includes the following topics:

“Summary of vCloud API Provisioning Requests,” on page 54

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

“Download a vApp Template as OVF,” on page 64

“Upload a Media Image,” on page 67

“Copying and Moving with the vCloud API,” on page 69

“Capturing and Importing vApps,” on page 70

“Cataloging vApp Templates and Media Images,” on page 70

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

The vCloud API clone operation copies a vApp, vApp template, or media image. You can specify whether to delete the source object after the operation completes. Deleting the source object after cloning it moves or renames it. After they are cloned, you can add templates and media images to catalogs as needed.

The vCloud API capture operation captures a vApp to create a vApp template. You can add the captured template to a catalog, download it, or both.

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, download it, or both.

VMware, Inc.

vCloud API Programming Guide

Summary of vCloud API Provisioning Requests

Provisioning requests add vApp templates and media to a vDC and a catalog. You can also use provisioning requests to copy, move, rename, and delete these objects.

API-URL is a URL of the form https://vcloud.example.com/api.

id is a unique identifier in the form of a UUID, as defined by RFC 4122.

Table 4-1. Summary of Provisioning Requests

Operation Request Request Body Response

Upload OVF to create a vApp template.

Download a vApp template as OVF.

Enable a vApp template for download.

Disable a vApp template for download.

Upload a media image. POST API-

Copy or move a media image. POST API-

Copy or move a vApp template.

Copy or move a vApp. POST API-

Change the name or description of a vApp template.

Change the name or description of a vApp.

Change the name or description of a media image.

Delete a vApp template, vApp, or media image.

Add an item to a catalog. POST API-

Remove an item from a catalog.

POST API-URL/vdc/id/ action/uploadVAppTempla te

GET download-URL None Depends on file type

POST API- URL/vAppTemplate/ vAppTemplateid/action/enableDownload

POST API- URL/vAppTemplate/ vAppTemplate-

id/action/disableDownload

URL/vdc/id/media

URL/vdc/ id/action/cloneMedia

POST APIURL/vdc/id/action/

cloneVAppTemplate

URL/vdc/ id/action/cloneVApp

PUT APIURL/vAppTemplate/vappT

emplate-id

PUT API-URL/vApp/vapp-

PUT API-URL/media/id

DELETE object-URL None

URL/catalog/ id/catalogItems

DELETE API-URL/ catalog/id/catalogItem/id

UploadVAppTemplateParamsVAppTemplate

None

None 204 No Content

Media Media

CloneMediaParams Media

CloneVAppTemplateParamsVAppTemplate

CloneVAppParams VApp

VAppTemplate Task

VApp Task

Media Task

CatalogItem CatalogItem

None 204 No content

Task

54 VMware, Inc.

Chapter 4 Provisioning an Organization with vApps, Templates, and Media

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

Operation Request Request Body Response

Control access to catalogs. POST API-

Retrieve the owner of a media object. [NEW]

Retrieve the owner of a vApp template [NEW]

Retrieve the owner of a vApp [NEW]

Update the owner of a vApp [NEW]

URL/catalog/ id/action/controlAccess

GET APIURL/media/id/owner

GET APIURL/vAppTemplate/vappT

emplate-id/owner

GET API- URL/vApp/id/owner

PUT API- URL/vApp/id/owner

ControlAccessParams ControlAccessParams

None

Owner

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.

Owner

204 No Content

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

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

An optional certificate

An optional manifest

The descriptor lists these files and includes information about their format.

You can use this file to certify the authenticity of the package.

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 uses a POST request that specifies a name and description for the template, and a transfer format

for the data.

2 The server returns an unresolved VAppTemplate element with (status="0") that includes an upload URL

for the OVF descriptor.

3 The client uses an HTTP PUT request to upload the descriptor to the upload URL.

4 The server reads 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.

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

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

manifest file.

VMware, Inc. 55

vCloud API Programming Guide

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

Restrictions on Uploaded Content

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

You can upload either OVF 1.0 or OVF 1.1 content. OVF 1.1 packages are converted to OVF 1.0 for download, and any OVF 1.1 content is lost.

You cannot upload a compressed OVF package.

If you upload an OVF package in which any VirtualSystem element has an ovf:id attribute value that is longer than 13 characters, the name of the Vm that represents 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 NewVirtualMa001 and

NewVirtualMa002.

1 Initiating the OVF Upload on page 56

To initiate the OVF upload, a client makes a POST request to the uploadVAppTemplate URL of the target vDC. The request body is an UploadVAppTemplateParams element.

2 Uploading the OVF Descriptor on page 59

You upload the OVF descriptor by making a PUT request to an upload URL and supplying the descriptor’s contents as an Envelope element in the request body. If the request is valid, the server responds with a 200 OK status.

3 Retrieving the Upload URLs on page 59

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.

4 Uploading Referenced Files on page 61

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

Initiating the OVF Upload

To initiate the OVF upload, a client makes a POST request to the uploadVAppTemplate URL of the target vDC. The request body is an UploadVAppTemplateParams element.

The first step in uploading an OVF package is to request vCloud Director to create a vAppTemplate object to represent the template that will be constructed from the upload. This request returns a response that includes a URL to which you can upload the package's descriptor file.

Prerequisites

Verify that you have the following information:

An OVF package to upload.

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

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.

56 VMware, Inc.

Chapter 4 Provisioning an Organization with vApps, Templates, and Media

Procedure

1 Find the uploadVappTemplate link in the target vDC.

Retrieve the XML representation of the vDC using a request like the one shown in the request portion of

“Example: Deployment Information in a vDC,” on page 30. The response contains an

uploadVappTemplate link, which has the following form:

2 Create an UploadVAppTemplateParams element that specifies a name for the template.

The Description element is optional. Using it to provide a concise description of this object is a best practice. See the request portion of “Example: Initiating the Upload,” on page 57.

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 uploadVAppTemplate 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 57.

5 Examine the response.

The response, a VAppTemplate element, contains a File element that specifies an upload URL for the package's OVF descriptor. See the response portion of “Example: Initiating the Upload,” on page 57.

The server creates a new VAppTemplate object in the target vDC and returns the object's XML representation in the response. See the response portion of “Example: Initiating the Upload,” on page 57.

Example: Initiating the Upload

This example assumes an OVF package that has no manifest.

Request:

POST https://vcloud.example.com/api/vdc/5/action/uploadVAppTemplate Content-Type: application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml ... <?xml version="1.0" encoding="UTF-8"?> <UploadVAppTemplateParams name="Ubuntu Template" xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <Description>Ubuntu vApp Template</Description> </UploadVAppTemplateParams>

Response:

201 Created Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"

VMware, Inc. 57

vCloud API Programming Guide

ovfDescriptorUploaded="true" goldMaster="false" status="0" name="Ubuntu Template" id="urn:vcloud:vapptemplate:268" href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-268" type="application/vnd.vmware.vcloud.vAppTemplate+xml"> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5"/> <Link rel="remove" href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-268" /> <Description>Ubuntu vApp Template</Description> <Files> <File name="descriptor.ovf" bytesTransferred="0"> <Link rel="upload:default" href="https://vcloud.example.com/transfer/.../descriptor.ovf" /> </File> </Files> <Owner> ... </Owner> <Children /> <LeaseSettingsSection> ... </LeaseSettingsSection> <CustomizationSection> ... </CustomizationSection> </VAppTemplate>

The response body includes the following attributes:

An href attribute whose value is a link to the new VAppTemplate object.

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

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

A goldMaster attribute, initially set to false

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

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.

58 VMware, Inc.

Chapter 4 Provisioning an Organization with vApps, Templates, and Media

Uploading the OVF Descriptor

OK status.

Prerequisites

Verify that you initiated the upload with an uploadVAppTemplate request and received an upload URL for the descriptor. See “Initiating the OVF Upload,” on page 56.

Procedure

1 Upload the OVF descriptor.

Make a PUT request to the upload URL returned in the response to the uploadVAppTemplate request, and supply the OVF descriptor as the request body. The OVF descriptor contains a single Envelope element.

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 https://vcloud.example.com/transfer/.../descriptor.ovf Content-Type text/xml ... <?xml version="1.0" encoding="UTF-8"?> <Envelope xmlns="http://schemas.dmtf.org/ovf/envelope/1" ... > ... </Envelope>

Response:

200 OK

Retrieving the Upload URLs

Procedure

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

Use the URL returned in the response to your uploadVAppTemplate request. See the request portion of

“Example: Upload URLs in a vAppTemplate,” on page 60.

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

VMware, Inc. 59

vCloud API Programming Guide

Example: Upload URLs in a vAppTemplate

This request uses the vApp template URL returned in “Example: Initiating the Upload,” on page 57.

Request:

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

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" ovfDescriptorUploaded="true" goldMaster="false" status="0" name="Ubuntu Template" id="urn:vcloud:vapptemplate:268" href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-268" type="application/vnd.vmware.vcloud.vAppTemplate+xml"> ... <Description>Ubuntu vApp Template</Description> <Files> <File size="3940" bytesTransferred="3940" name="descriptor.ovf"> <Link rel="upload:default" href="https://vcloud.example.com/transfer/.../descriptor.ovf"/> </File> <File size="1024" bytesTransferred="0" name="manifest.mf"> <Link rel="upload:default" href="https://vcloud.example.com/transfer/.../manifest.mf"/> </File> <File size="1950489088" bytesTransferred="0" name="disk0.vmdk"> <Link rel="upload:default" href="https://vcloud.example.com/transfer/.../disk0.vmdk"/> </File> </Files> ... </VAppTemplate>

60 VMware, Inc.

Chapter 4 Provisioning an Organization with vApps, Templates, and Media

In this example, which omits most of the additional elements shown in “Example: Initiating the Upload,” on page 57, 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 165.

Uploading Referenced Files

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

Prerequisites

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

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

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

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.

VMware, Inc. 61

vCloud API Programming Guide

Request:

PUT https://vcloud.example.com/transfer/.../disk0.vmdk Content-length: 1950489088

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

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 tracking 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 62.

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

Example: Monitoring the Progress of an Upload

Request:

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

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

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate ... name="Ubuntu Template" id="urn:vcloud:vapptemplate:268" href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-268" type="application/vnd.vmware.vcloud.vAppTemplate+xml" ... > ... <Files> ... <File size="1950489088"

62 VMware, Inc.

Chapter 4 Provisioning an Organization with vApps, Templates, and Media

bytesTransferred="500000000" name="disk0.vmdk"> <Link rel="upload:default" href="https://vcloud.example.com/transfer/.../disk0.vmdk"/> </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 63.

Procedure

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

2 Make a PUT request that specifies a Content-Range and Content-Length and includes the serialized

contents of the range.

For 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 disk0.vmdk shown in this fragment of a VAppTemplate.

Request:

PUT https://vcloud.example.com/transfer/.../disk0.vmdk Content-Range: bytes 500000000-1950489087/1950489088 Content-Length: 1450489088

...serialized contents of specified range...

EOF

Response:

200 OK

VMware, Inc. 63

vCloud API Programming Guide

Download a vApp Template as OVF

You can download a vApp template as an OVF package. After you find the template by browsing a catalog, you can request that the template be enabled for download.

When you enable a 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 template. The server excludes

any deployment-specific information that the template contains, and populates the descriptor's

References element with links 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

OVF descriptor references.

3 The server updates the vAppTemplate with a link that contains a URL from which you can retrieve the OVF

descriptor.

After the template is enabled for download, you can retrieve it to see the download:default URL for the descriptor, then parse the descriptor to find the URLs from which you can retrieve the referenced files.

1 Enable the vApp Template for Download on page 64

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

2 Download the OVF Descriptor on page 65

To download the OVF descriptor, you make a GET request to the download:default URL in the download-enabled VappTemplate.

3 Download a Referenced File on page 66

After you download the OVF descriptor of a vApp template, you can examine the contents of the descriptor to discover download URLs for files that the template references.

Enable the vApp Template for Download

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

Prerequisites

Verify that you are logged in as an administrator or other user who has privileges to enable vApp template for download.

Procedure

1 Retrieve the template to find its action/enableDownload link.

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

<Link rel="enable"

href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-

/action/enableDownload"/>

2 Enable the template for download.

Make a POST request to the template's action/enableDownload URL.

Request:

POST https://vcloud.example.com/api/vAppTemplate/vappTemplate-268/action/enableDownload

64 VMware, Inc.

Chapter 4 Provisioning an Organization with vApps, Templates, and Media

Response:

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

The Task in the response tracks the creation of the download package.

3 When the task completes, retrieve the template, which now contains a download URL for the OVF

descriptor.

This 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 165.

Example: vApp Template with Download URL for OVF Descriptor

Request:

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

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate ovfDescriptorUploaded="true" status="8" name="Ubuntu Template" ... > ... <Link type="text/xml" rel="download:default" href="https://vcloud.example.com/transfer/.../descriptor.ovf"/> ... </VAppTemplate>

Download the OVF Descriptor

To download the OVF descriptor, you make a GET request to the download:default URL in the downloadenabled VappTemplate.

Prerequisites

Verify that you are logged in as a system administrator or member of an organization in the cloud.

Verify that you have a vApp template that is enabled for download. See “Enable the vApp Template for

Download,” on page 64.

Procedure

1 Examine the VAppTemplate to find the the download:default URL for the descriptor.

2 Make a GET request to the download:default URL to retrieve the descriptor

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

VMware, Inc. 65

vCloud API Programming Guide

Example: Downloading the OVF Descriptor

This example downloads the OVF descriptor from the URL shown in the href value of the Link shown in

“Example: vApp Template with Download URL for OVF Descriptor,” on page 65. The response includes the

entire Envelope element, only part of which appears here.

Request:

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

Response:

200 OK Content-Type text/xml ... <Envelope xmlns="http://schemas.dmtf.org/ovf/envelope/1" ... > ... </Envelope>

Download a Referenced File

After you download the OVF descriptor of a vApp template, you can examine the contents of the descriptor to discover download URLs for files that the template references.

The OVF descriptor that you download from a vApp template includes the names of files that the template references. To retrieve one of these files, you must create a download URL for it by combining its name with a URL derived from the download URL that you used to retrieve the descriptor. You must retrieve all of the files to create a valid OVF package.

Prerequisites

Verify that you are logged in as a system administrator or member of an organization in the cloud.

Retrieve the OVF descriptor of a vApp template that was 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 66.

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 66 with the file name shown in this File element:

66 VMware, Inc.

Request:

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

Response:

200 OK ...

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

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 disk0.vmdk were both in the same directory, which is the default arrangement.

Upload a Media Image

The vCloud API supports uploading virtual media such as CD-ROM and floppy disk images.

The workflow for uploading media images is similar to the one described in “Upload an OVF Package to Create

a vApp Template,” on page 55.

Chapter 4 Provisioning an Organization with vApps, Templates, and Media

NOTE You cannot download media images.

Prerequisites

Verify that the following conditions are met:

You have a media image to upload.

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

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.

Procedure

1 Find the media link in the target vDC.

Retrieve the XML representation of the vDC contains a media link, which has the following form:

2 POST a media request to the server.

The request body is a Media element that includes information about the virtual media item to upload. See the request portion of “Example: Upload a Media Image,” on page 68.

The server uses this information to create a Media object, then returns a representation of the object that contains an upload URL. See the response portion of “Example: Upload a Media Image,” on page 68.

3 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 61.

VMware, Inc. 67

vCloud API Programming Guide

Example: Upload a Media Image

Request:

POST https://vcloud.example.com/api/vdc/5/media Content-Type: application/vnd.vmware.vcloud.media+xml ... <?xml version="1.0" encoding="UTF-8"?> <Media xmlns="http://www.vmware.com/vcloud/v1.5" name="database.iso" size="51242131" imageType="iso"> <Description>ISO database image</Description> </Media>

In addition to the File element that contains the upload:default URL, the response includes an Owner element and several Link elements that the server creates.

Response:

Content-Type: application/vnd.vmware.vcloud.media+xml 201 Created ... <Media xmlns="http://www.vmware.com/vcloud/v1.5" size="3121215488" imageType="iso" status="0" name="database.iso" id="urn:vcloud:media:254" type="application/vnd.vmware.vcloud.media+xml" href="https://vcloud.example.com/api/media/254" ... > <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5" /> <Link rel="remove" href="https://vcloud.example.com/api/media/254" /> <Description>ISO database image</Description> <Files> <File size="51242131" bytesTransferred="0" name="file"> <Link rel="upload:default" href="https://vcloud.example.com/transfer/.../file" /> </File> </Files> <Owner ... </Owner> </Media>

68 VMware, Inc.

Chapter 4 Provisioning an Organization with vApps, Templates, and Media

Copying and Moving with the vCloud API

The vCloud API provides object-specific copy operations, implemented by clone actions, for media images, vApp templates, and vApps. With these operations, you can create a copy of the object in the same vDC or in another vDC in the same organization.

vCloud API copy operations support an option to delete the source object after the copy is complete. Doing so when the source and target objects are in different vDCs moves the source object to the target vDC. Doing so when the source and target objects are in the same vDC renames the source object. The vCloud API does not include an explicit move operation. When you move an object by copying it and deleting its source, an intermediate object is created in the target vDC, as part of the following sequence of events:

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

a UUID.

2 The source object is deleted.

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

Copy or Move a Media Image

The cloneMedia request makes a copy of the media image referenced in the Source element of the request body. The request specifies a new name and, optionally, a new description for the copy. The request can optionally include an IsSourceDelete element whose value specifies whether the source media image is deleted after the copy is complete. If IsSourceDelete is missing from the request body or present with a value of false, the source object remains in place after the copy is complete. Setting IsSourceDelete to true effectively moves the media image.

For more information and an example, see the cloneMedia operation in the schema reference.

Copy or Move a vApp Template

The cloneVAppTemplate request makes a copy of the vApp template referenced in the Source element of the request body. The request specifies a new name and, optionally, a new description for the copy. The request can optionally include an IsSourceDelete element whose value specifies whether the source vApp template is deleted after the copy is complete. If IsSourceDelete is missing from the request body or present with a value of false, the source object remains in place after the copy is complete. Setting IsSourceDelete to true effectively moves the vApp template.

For more information and an example, see the cloneVAppTemplate operation in the schema reference.

Copy or Move a vApp

The cloneVApp request makes a copy of the vApp referenced in the Source element of the request body. The request specifies a new name and, optionally, a new description for the copy. The request can optionally include an IsSourceDelete element whose value specifies whether 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 the vApp.

NOTE You cannot copy or move a vApp that is deployed.

For more information and an example, see the cloneVApp operation in the schema reference.

VMware, Inc. 69

vCloud API Programming Guide

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.

Every vDC includes a Link of the following form:

You can POST a CaptureVAppParams request to this link to capture an undeployed vApp. The operation returns a VAppTemplate that you can add to a catalog. Instantiating this template recreates the vApp from which it was captured. Most elements of a vApp template are read-only, but you can instantiate a template, modify the resulting vApp, and then capture it to create a modified version of the template.

For more information and an example, see the captureVApp operation in the schema reference.

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

Cataloging vApp Templates and Media Images

Catalogs can contain references to vApp templates and media images. A system administrator or a privileged member of the organization that owns the catalog can create and remove these references.

Although you can retrieve references to vApp templates and media images directly from the vDC to which they were uploaded, it is common practice to place references to such assets in one of an organization’s catalogs. When you place the references in a catalog, the assets are easier to discover, because a catalog can include assets from all vDCs in an organization. You also have more flexible administrative control over them, because you can restrict access to catalogs and the items in them to specific users and groups. Assets such as vApp templates are not enabled for most uses until you include them in a catalog. For example, you cannot instantiate a vApp template that is not included in a catalog. A media image that is not included in a catalog cannot be copied or inserted by anyone but its owner.

Add an Item to a Catalog

A catalog can contain references to vApp templates and media images from any vDC in an organization. A vApp template or media image can be listed in at most one catalog.

Prerequisites

Verify that you are logged in as a user with the Catalog Author role, as an organization administrator, or as a system administrator.

Procedure

1 Retrieve the XML representation of your organization and look for links to the catalogs and vDCs it

contains.

Links to catalogs have the following form:

70 VMware, Inc.

Chapter 4 Provisioning an Organization with vApps, Templates, and Media

Links to vDCs have the following form:

2 Browse the vDCs in your organization to find the ResourceEntity element that represents the item to add

to the catalog.

Resource entities are contained in the ResourceEntities element of a Vdc .

3 Retrieve the XML representation of the catalog to which to add the item.

Use a request like this one:

GET https://vcloud.example.com/api/catalog/32

4 Examine the response to locate the Link element that contains the URL for adding items to the catalog.

This element has a rel attribute value of add and a type attribute value of

application/vnd.vmware.admin.catalogItem+xml, as this example shows:

5 Create a CatalogItem element that contains a reference to the ResourceEntity

See “Example: ResourceEntity and Corresponding CatalogItem,” on page 72 for an example.

6 POST the CatalogItem body to the catalog's rel="add" URL.

Step 4 explains how to find this URL.

VMware, Inc. 71

vCloud API Programming Guide

Example: ResourceEntity and Corresponding CatalogItem

This example starts with this ResourceEntity, which references a vApp template.

Follow these guidelines to create a CatalogItem from a ResourceEntity.

The name attribute of the CatalogItem can be the same as the one in the ResourceEntity, or you can make up a new value for name.

The Description element of the CatalogItem can be the same as the Description element for the object that the ResourceEntity element references, or you can create a Description element.

The href attribute of the Entity element in the CatalogItem must have the same value as the href attribute of the ResourceEntity that the CatalogItem references.

This request creates the catalog item that is retrieved in “Example: Retrieve a Catalog Item,” on page 29. The response echoes the request, and includes links that an administrator or catalog owner can use to manage the

CatalogItem and its metadata.

Request:

POST https://vcloud.example.com/api/catalog/32/catalogItems Content-Type: application/vnd.vmware.vcloud.catalogItem+xml ... <?xml version="1.0" encoding="UTF-8"?> <CatalogItem name="Ubuntu Template with vsftpd" type="application/vnd.vmware.vcloud.catalogItem+xml" xmlns="http://www.vmware.com/vcloud/v1.5"> <Description>Approved template for public FTP sites</Description> <Entity href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111"/> </CatalogItem>

Response:

72 VMware, Inc.

Chapter 4 Provisioning an Organization with vApps, Templates, and Media

type="application/vnd.vmware.vcloud.catalogItem+xml" href="https://vcloud.example.com/api/catalogItem/221" /> <Link rel="remove" href="https://vcloud.example.com/api/catalogItem/221" /> <Description>Approved template for public FTP sites</Description> <Entity href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/> </CatalogItem>

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.

For more information and an example, see the catalogItem operation in the schema reference.

Prerequisites

Verify that you are logged in as a user with the Catalog Author role, as an organization administrator of the organization that owns the catalog, or as a system administrator.

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.

View or Change the Owner of an Object

You can view the owner of a VApp, VAppTemplate, or Media object by making a GET request to the object's

owner link. You can change the owner of a VApp, but not that of a VAppTemplate or Media object. An administrator

can view or change the owner of a Catalog object.

The initial owner of a VApp, VAppTemplate, Catalog, 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.

Prerequisites

To change the owner of a vApp, you must be the vApp owner, an organization administrator, or the system administrator.

To change the owner of a catalog, 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 example retrieves the owner of a vApp.

GET https://vcloud.example.com/api/vApp/vapp-7/owner

VMware, Inc. 73

vCloud API Programming Guide

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 of a vApp, 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 74.

Example: Change the Owner of a vApp

Request:

PUT https://vcloud.example.com/api/vApp/vapp-7/owner Content-type: application/vnd.vmware.vcloud.owner+xml ... <?xml version="1.0" encoding="UTF-8"?> <Owner xmlns="http://www.vmware.com/vcloud/v1.5"> <User type="application/vnd.vmware.admin.user+xml" href="https://vcloud.example.com/api/admin/user/120" /> </Owner>

Response:

204 No Content

74 VMware, Inc.

Deploying and Operating vApps 5

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

About OVF

OVF is a widely accepted standard format that applies to many virtualization technologies.

Virtual machines and appliances are distributed as OVF packages by many vendors.

Many vendors, including VMware, offer tools that simplify creating and customizing OVF, support converting virtual machines on existing virtualization platforms to OVF, or both.

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.

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

http://www.dmtf.org/standards/published_documents/DSP0243_1.0.0.pdf. An informative white paper on

OVF is available at http://www.dmtf.org/standards/published_documents/DSP2017_1.0.0.pdf.

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.

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:

An OVF package, the form in which vApps are typically distributed.

A vApp template, created when a client uploads an OVF package to a vDC.

VMware, Inc.

descriptor.ovf

OVF package

instantiate

<VApp...status=”8” deployed=“false” href=”http://.../vapp-9”> ... <Link rel=”deploy”...> ... </VApp>

deploy

disk0.vmdk

upload

vApp

template

vApp

<VApp...status=”8” deployed=“true” href=”http://.../vapp-9”> ... <Link rel=”power:powerOn”...> ... </VApp>

vApp

vCloud API Programming Guide

An undeployed vApp, created when a vApp template is instantiated without also being deployed, or a deployed vApp is undeployed.

A deployed vApp, ready to be powered on and operated. Instantiation can include deployment, poweron, or both.

Figure 5-1. vApp State Transitions

This chapter includes the following topics:

“Summary of vCloud API vApp and Virtual Machine Operations Requests,” on page 77

“Create a vApp From a Template,” on page 78

“Compose a vApp From Existing Virtual Machines,” on page 80

“Recompose a vApp to Add or Remove Virtual Machines,” on page 83

“Operate a vApp,” on page 85

“Configuring vApps and Virtual Machines,” on page 86

76 VMware, Inc.

Chapter 5 Deploying and Operating vApps

Summary of vCloud API vApp and Virtual Machine Operations Requests

These vCloud API operations requests create, manage, operate, and delete vApps and the virtual machines that they contain.

API-URL is a URL of the form https://vcloud.example.com/api.

id is a unique identifier in the form of a UUID, as defined by RFC 4122.

VApp-or-Vm-URL is a URL of the form API-URL/vApp/vapp-id (for a VApp object) or API-URL/vApp/vm- id (for a Vm object)

Vm-URL is a URL of the form API-URL/vApp/vm-id

Request URLs are always available when you GET the representation of the object on which they operate. URL forms shown in the table are for reference purposes only. For more information about the requests and responses for each operation, see “About the Schema Reference Downloadable Archive,” on page 19.

Table 5-1. Summary of vCloud API Operations Requests

Operation Request Request Body Response

Instantiate a vApp template POST API-URL/vdc/id/

action/instantiateVAppTe mplate

Compose a vApp POST API-URL/vdc/id/

action/composeVApp

Recompose a vApp to add or remove virtual machines

Deploy a vApp or Virtual Machine

Undeploy a vApp or Virtual Machine

Power On a vApp or Virtual Machine

Power Off a vApp or Virtual Machine

Reset a vApp or Virtual Machine

Suspend a vApp or Virtual Machine

Discard the Suspended State of a vApp or Virtual Machine

Shut Down a vApp or Virtual Machine

Reboot a vApp or Virtual Machine

Retrieve product sections of a vApp or virtual machine [NEW]

Update product sections of a vApp or virtual machine [NEW]

POST API- URL/vApp/vapp-id/ action/recomposeVApp

POST VApp-or-Vm- URL/action/deploy

POST VApp-or-Vm- URL/action/undeploy

POST VApp-or-Vm- URL/action/powerOn

POST VApp-or-Vm- URL/action/powerOff

POST VApp-or-Vm- URL/action/reset

POST VApp-or-Vm- URL/action/suspend

POST VApp-or-Vm- URL/action/ discardSuspendedState

POST VApp-or-Vm- URL/action/shutdown

POST VApp-or-Vm- URL/action/reboot

GET VApp-or-Vm- URL/productSections

PUT VApp-or-Vm- URL/productSections

InstantiateVAppTemplat eParams

ComposeVAppParams VApp

RecomposeVAppParams Task

DeployVAppParams Task

UndeployVAppParams Task

None

ProductSectionList Task

VApp

Task

ProductSectionList

VMware, Inc. 77

vCloud API Programming Guide

Table 5-1. Summary of vCloud API Operations Requests (Continued)

Operation Request Request Body Response

Retrieve product sections of a vApp template [NEW]

Update product sections of a vApp template [NEW]

Retrieve version of VMware Tools installed on a virtual machine [NEW]

Install VMware Tools on a virtual machine [NEW]

Consolidate a virtual machine [NEW]

Upgrade the hardware version of a virtual machine [NEW]

Insert Media Into a Virtual Machine

Eject Media from a Virtual Machine

List Media Devices of a Virtual Machine

Get a Request for User Input GET Vm-URL/question None

Provide Requested User Input

Get a Screen Thumbnail for a Virtual Machine

Get a Screen Ticket for a Virtual Machine

GET API- URL/vAppTemplate/vappT emplate-id/productSections

PUT API- URL/vAppTemplate/vappT emplate-id/productSections

GET Vm- URL/runtimeInfoSection

POST Vm- URL/action/installVMware Tools

POST Vm- URL/action/consolidate

POST Vm- URL/action/upgradeHardw areVersion

POST Vm- URL/action/insertMedia

POST Vm- URL/action/ejecttMedia

GET Vm-URL/ virtualHardwareSection/m edia

POST Vm- URL/question/action/answ er

GET Vm-URL/screen None Returns a screen thumbnail

POST Vm-URL/ screen/action/acquireTicket

None

ProductSectionList Task

None

MediaInsertOrEjectParamsTask

None

VmQuestionAnswer

None

ProductSectionList

RuntimeInfoSection

Task

RasdItemsList

VmPendingQuestion

204 No Content

(Content-type: image/png) if one is available. Otherwise returns null (Content-Length:

0).

ScreenTicket

Create a vApp From a Template

An instantiateVAppTemplate request creates a vApp from a vApp template. By default, this operation also deploys the vApp and powers it on.

For an example of a simple instantiation request, see “Deploy the vApp,” on page 31. You can also specify additional parameters as part of instantiation.

78 VMware, Inc.

Chapter 5 Deploying and Operating vApps

Template contents that might influence composition of the request body include the following sections:

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.

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.

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.

Prerequisites

Verify that you are logged in as a system administrator or member of an organization in the cloud.

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.

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,” on page 79 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 it is still being constructed. It also contains a Task element that tracks the

progress of the request.

Example: Instantiate a vApp Template

This InstantiateVAppTemplateParams request extends the request shown in “Example: Deploying a vApp,” on page 32 to include additional elements in its InstantiationParams:

A LeaseSettingsSection that specifies custom lease settings, overriding the settings that would otherwise be inherited from the organization.

An acknowledgement of EulaSection acceptance, supplied in the AllEULAsAccepted element. If the template does not include EulaSection elements, you can omit this acknowledgement.

For more information and a list of sections that you can include in InstantiationParams, see “Configuring a

vApp,” on page 87.

VMware, Inc. 79

vCloud API Programming Guide

Request:

POST https://vcloud.example.com/api/vdc/5/action/instantiateVAppTemplate Content-Type: application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml ... <?xml version="1.0" encoding="UTF-8"?> <InstantiateVAppTemplateParams xmlns="http://www.vmware.com/vcloud/v1.5" name="Linux FTP server" deploy="true" powerOn="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <Description>Example FTP Server</Description> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks </ovf:Info> <NetworkConfig networkName="vAppNetwork"> <Configuration> <ParentNetwork href="https://vcloud.example.com/api/network/54" /> <FenceMode>bridged</FenceMode> </Configuration> </NetworkConfig> </NetworkConfigSection> <LeaseSettingsSection type="application/vnd.vmware.vcloud.leaseSettingsSection+xml"> <ovf:Info>Lease Settings</ovf:Info> <StorageLeaseInSeconds>172800</StorageLeaseInSeconds> <StorageLeaseExpiration>2010-04-11T08:08:16.438-07:00</StorageLeaseExpiration> </LeaseSettingsSection> </InstantiationParams> <Source href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" /> <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 32.

Compose a vApp From Existing Virtual Machines

With the vCloud API composeVApp operation, you can build a vApp from existing virtual machines, including virtual machines contained by vApps and vApp templates to which you have access.

Every vDC includes a link to a composeVApp operation, which creates a new vApp in it. To compose a vApp, POST a composeVApp request to this link. The request body is a ComposeVAppParams element, which includes the following information:

An InstantiationParams element that can include any of the section types listed under “Configuring a

vApp,” on page 87. 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.

An optional Description of the composed vApp.

80 VMware, Inc.

Chapter 5 Deploying and Operating vApps

Zero or more SourcedItem elements, each of which defines a source of virtual machines to include in the composition. Each SourcedItem must contain a Source element that references a composition source, the

href of a Vm, VApp, or VAppTemplate. If the Source element references a virtual machine, the SourcedItem

can include any of the following elements:

An InstantiationParams element specific to that virtual machine. This element can include any of the section types listed under “Configuring a Virtual Machine,” on page 87.

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.

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.

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

Verify that you are logged in as a system administrator or member of an organization in the cloud.

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:

2 Create a ComposeVappParams element that specifies the details of the composition.

3 POST the ComposeVappParams element to the composeVapp link of the target vDC.

See the Request portion of “Example: Compose a vApp,” on page 81.

Example: Compose a vApp

This request specifies two vAppTemplate items and one Vm item. The Vm item requires InstantiationParams that modify its NetworkConnectionSection to specify the vApp network created for this vApp. The vAppTemplate items inherit this setting from the base InstantiationParams element that appears before the first

SourcedItem is specified.

NOTE Virtual machines specified in Source elements must be powered off or 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.

https://vcloud.example.com/api/query?type=adminVM&format=references&filter=status==POWERED_OFF

See Chapter 9, “Using the Query Service,” on page 201.

VMware, Inc. 81

vCloud API Programming Guide

Request:

POST https://vcloud.example.com/api/vdc/5/action/composeVApp Content-Type: application/vnd.vmware.vcloud.composeVAppParams+xml ... <?xml version="1.0" encoding="UTF-8"?> <ComposeVAppParams name="Example Corp’s CRM Appliance" xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <Description>Composed CRM Appliance</Description> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="CRMApplianceNetwork"> <Configuration> <ParentNetwork href="https://vcloud.example.com/api/network/54" /> <FenceMode>natRouted</FenceMode> </Configuration> </NetworkConfig> </NetworkConfigSection> </InstantiationParams> <SourcedItem> <Source href="https://vcloud.example.com/api/vApp/vm-4" /> <InstantiationParams> <NetworkConnectionSection xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" type="application/vnd.vmware.vcloud.networkConnectionSection+xml" href="https://vcloud.example.com/api/vApp/vm-4/networkConnectionSection/" ovf:required="false"> <ovf:Info /> <PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex> <NetworkConnection network="CRMApplianceNetwork"> <NetworkConnectionIndex>0</NetworkConnectionIndex> <IsConnected>true</IsConnected> <IpAddressAllocationMode>DHCP</IpAddressAllocationMode> </NetworkConnection> </NetworkConnectionSection> </InstantiationParams> </SourcedItem> <SourcedItem> <Source href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-114" /> </SourcedItem> <SourcedItem> <Source href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-190" /> </SourcedItem> <AllEULAsAccepted>true</AllEULAsAccepted> </ComposeVAppParams>

82 VMware, Inc.

Chapter 5 Deploying and Operating vApps

Response:

201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml ... <VApp name="Example Corp’s CRM Appliance" type="application/vnd.vmware.vcloud.vApp+xml" status="8" href="https://vcloud.example.com/api/vApp/vapp-33" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="https://vcloud.example.com/api/vdc/5"/> ... <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 or Remove Virtual Machines

The vCloud API supports recomposition of a vApp to add or remove 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 elements, but is otherwise identical to ComposeVAppParams. This means that in addition to adding or removing virtual machines, a

recomposeVApp request can also change the name and description of the vApp, and can supply new InstantiationParams to change various sections of the composed vApp or any of the added virtual machines.

Unlike a composeVapp request, which operates on a vDC and creates a new vApp, a recomposeVapp request operates on (and modifies) an existing vApp.

Prerequisites

Verify that you are logged in as a system administrator or member of an organization in the cloud.

Procedure

1 Find the recomposeVApp link in the target vApp.

The XML representation of a vApp contains a recomposeVapp link, which has the following form:

2 Create a RecomposeVappParams element that specifies the details of the recomposition.

See “Example: Recompose a vApp,” on page 84.

3 POST the RecomposeVappParams element to the recomposeVapp link of the target vApp.

VMware, Inc. 83

vCloud API Programming Guide

Example: Recompose a vApp

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.

The request removes one of the virtual machines from the vApp and creates a StartupSection that specifies a startup order for the remaining virtual machines.

Request:

POST https://vcloud.example.com/api/vApp/vapp-33/action/recomposeVApp Content-Type: application/vnd.vmware.vcloud.recomposeVAppParams+xml ... <?xml version="1.0" encoding="UTF-8"?> <RecomposeVAppParams name="Example Corp’s CRM Appliance" xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <Description>Composed CRM Appliance</Description> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig

84 VMware, Inc.

Chapter 5 Deploying and Operating vApps

networkName="CRMApplianceNetwork"> <Configuration> <ParentNetwork href="https://vcloud.example.com/api/network/54" /> <FenceMode>natRouted</FenceMode> </Configuration> </NetworkConfig> </NetworkConfigSection> <ovf:StartupSection xmlns:vcloud="http://www.vmware.com/vcloud/v1.5" vcloud:type="application/vnd.vmware.vcloud.startupSection+xml"> <ovf:Info>VApp startup section</ovf:Info> <ovf:Item ovf:order="0" ovf:id="CRM-DB" /> <ovf:Item ovf:order="1" ovf:id="CRM-CRM" /> </ovf:StartupSection> </InstantiationParams> <AllEULAsAccepted>true</AllEULAsAccepted> <DeleteItem href="https://vcloud.example.com/api/vApp/vm-45" /> </RecomposeVAppParams>

Response:

202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Updating Virtual Application Example Corp’s CRM Appliance (33)" ...> ... </Task>

https://vcloud.example.com/api/query?type=adminVM&format=references&filter=status==POWERED_OFF

See Chapter 9, “Using the Query Service,” on page 201.

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.

A request made to a vApp power URL invokes the requested operation on each of the virtual machines in the Children element of the vApp, in the order specified in its ovf:StartupSection element. This element, if present, specifies a start order and related properties for each member of a VirtualSystemCollection (each Vm 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.

VMware, Inc. 85

vCloud API Programming Guide

A request made to a Vm power URL affects only that virtual machine.

See “Summary of vCloud API vApp and Virtual Machine Operations Requests,” on page 77 for details of each request.

Prerequisites

Verify that you are logged in as a system administrator or member of an organization in the cloud.

Procedure

1 Retrieve the XML representation of the vApp to find the action links it contains.

Use a request like this one:

GET https://vcloud.example.com/api/vApp/vapp-7

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.

Configuring vApps and Virtual Machines

You specify configuration details for vApps and the virtual machines they contain in ovf:SectionType elements contained in a VApp or Vm element. You can include most of these sections in the InstantiationParams that you supply when you instantiate a vApp template. You can also retrieve, modify, and update these sections to reconfigure a deployed vApp.

You establish the initial configuration of a vApp in the OVF package on which its source template is based. You cannot modify most sections of the template, but you can update the configuration during the following operations:

When you create a vApp by making an instantiateVAppTemplate request, you can update its configuration by including modified sections in the request's InstantiationParams element.

When you compose or recompose a vApp, you can update its configuration by including modified sections in the request's InstantiationParams element.

When you update any of the modifiable sections in a deployed vApp or the virtual machines that it contains.

You can capture the reconfigured vApp to create a vApp template that preserves your modifications. See

“Capturing and Importing vApps,” on page 70.

Updating a vApp Template

You can update the following sections of a vApp template.

CustomizationSection

Name and description

You can use a PUT request to update this section, which contains a Boolean value, CustomizeOnInstantiate, that specifies whether guest customization should be run during instantiation. You cannot modify this element if the vApp has been added to a catalog.

You can use a PUT request to update the value of the template's name attribute or the contents of its Description element.

86 VMware, Inc.

Chapter 5 Deploying and Operating vApps

Owner

ProductSection elements

Except for the Owner element, all updates to a vApp template propagate to the vApp during instantiation. The owner of the vApp is reset to the identity of the user who instantiates the template.

You can use a PUT request to update the value of the template's Owner element. See “View or Change the Owner of an Object,” on page 73.

You can retrieve or update the template's ProductSection elements, which provide a way to pass runtime information to the virtual machines defined in the template. See “Retrieve or Modify ProductSection Elements,” on page 102.

Configuring a vApp

You can include the following sections in InstantiationParams for a vApp. You can also modify them after you deploy the vApp.

LeaseSettingsSection

NetworkConfigSection

StartupSection

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.

Defines the properties of the vApp network and specifies how it is connected to a network in the vDC. Unless you intend to create a vApp that has no connection to any network, you must include this section in the

InstantiationParams element of an instantiateVappTemplate request.

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.

Configuring a Virtual Machine

You can include the following sections in the InstantiationParams for a Vm. You can also modify them after you deploy the Vm. You can reconfigure a virtual machine by making changes to any of the following sections of a Vm:

VirtualHardwareSection

OperatingSystemSectio n

NetworkConnectionSect ion

GuestCustomizationSec tion

Contains a description of the virtual hardware supported by a virtual machine. You can reconfigure individual items in this section, or reconfigure groups of related items such as hard disks or network interface cards.

Specifies the guest operating system installed on the virtual machine.

Specifies how the virtual NIC devices on the virtual machine are connected to the vApp network.

Contains guest customization parameters for the virtual machine.

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.

VMware, Inc. 87

vCloud API Programming Guide

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.

Modified sections must contain all required elements, even if you are not changing their values. Because optional elements revert to default values if they are omitted or empty, it is a best practice to include optional elements in updates. Link elements and href attributes from responses do not need to be included in modified sections. Some elements and attributes might be read-only. 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. See “Summary of vSphere Platform Extension Requests,” on page 161.

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 section's href attribute. Then make a PUT request to the href attribute value of Link where

rel="edit" to update the section with your modifications.

Prerequisites

Verify that you are logged in as a system administrator or member of an organization in the cloud.

Procedure

1 Retrieve the XML representation of the vApp.

Use a GET request as shown in “Example: Configuration Links in a vApp,” on page 88.

2 Examine the response for edit links to modifiable sections.

The response portion of “Example: Configuration Links in a vApp,” on page 88 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 90.

Request:

GET https://vcloud.example.com/api/vApp/vapp-7

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.vApp+xml ... <VApp ... href="https://vcloud.example.com/api/vApp/vapp-7"> ... <LeaseSettingsSection ... href="https://vcloud.example.com/api/vApp/vapp-7/leaseSettingsSection/" ...> ... <Link rel="edit" type="application/vnd.vmware.vcloud.leaseSettingsSection+xml"

88 VMware, Inc.

Chapter 5 Deploying and Operating vApps

href="https://vcloud.example.com/api/vApp/vapp-7/leaseSettingsSection/" /> ... </LeaseSettingsSection> <ovf:StartupSection ... href="https://vcloud.example.com/api/vApp/vapp-7/startupSection/" ... > ... <Link rel="edit" type="application/vnd.vmware.vcloud.startupSection+xml" href="https://vcloud.example.com/api/vApp/vapp-7/startupSection/" /> ... </ovf:StartupSection> <NetworkConfigSection ... href="https://vcloud.example.com/api/vApp/vapp-7/networkConfigSection/" ... /> ... <Link rel="edit" type="application/vnd.vmware.vcloud.networkConfigSection+xml" href="https://vcloud.example.com/api/vApp/vapp-7/networkConfigSection/" /> ... </NetworkConfigSection> <Children> <Vm ... status="8" name="ubuntu10-x86" href="https://vcloud.example.com/api/vApp/vm-4"> ... </Vm> </Children> </VApp>

Summary of vApp Reconfiguration Requests

vApp reconfiguration requests retrieve or update modifiable sections of a vApp.

API-URL is a URL of the form https://vcloud.example.com/api.

id is a unique identifier in the form of a UUID, as defined by RFC 4122.

Table 5-2. Summary of vApp Reconfiguration Requests

Operation Request Request Body Response

Retrieve vApp

LeaseSettingsSection

Update vApp

LeaseSettingsSection

Retrieve vApp

StartupSection

Update vApp

StartupSection

GET API-URL/vApp/vapp- id/ leaseSettingsSection/

PUT API-URL/vApp/vapp- id/ leaseSettingsSection/

GET API-URL/vApp/vapp- id/ startupSection/

PUT API-URL/vApp/vapp- id/ startupSection/

None

LeaseSettingsSection Task

None

StartupSection Task

LeaseSettingsSection

StartupSection

VMware, Inc. 89

vCloud API Programming Guide

Table 5-2. Summary of vApp Reconfiguration Requests (Continued)

Operation Request Request Body Response

Retrieve vApp

NetworkConfigSection

Update vApp

NetworkConfigSection

GET API-URL/vApp/vapp- id/ networkConfigSection/

PUT API-URL/vApp/vapp- id/ networkConfigSection/

None

NetworkConfigSection Task

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.

rel="edit" to update the section with your modifications.

Prerequisites

Verify that you are logged in as a system administrator or member of an organization in the cloud.

NetworkConfigSection

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

2 In the VApp element's Children element, find the Vm element that represents the virtual machine and retrieve

it.

3 Examine the response for edit links to modifiable sections.

The response portion of “Example: Configuration Links in a Vm Element,” on page 90 shows the links for each of the modifiable section 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 88. 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 88.

Request:

GET https://vcloud.example.com/api/vApp/vm-4

Response:

200 OK Content-Type: application/vnd.vmware.vcloud.vm+xml <Vm xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" status="8" name="ubuntu10-x86" href="https://vcloud.example.com/api/vApp/vm-4"> <ovf:VirtualHardwareSection>

90 VMware, Inc.

Chapter 5 Deploying and Operating vApps

<Link rel="edit" type="application/vnd.vmware.vcloud.virtualHardwareSection+xml" href="https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/" /> <Link rel="down" type="application/vnd.vmware.vcloud.rasdItem+xml" href="https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/cpu" /> <Link rel="edit" type="application/vnd.vmware.vcloud.rasdItem+xml" href="https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/cpu" /> <Link rel="down" type="application/vnd.vmware.vcloud.rasdItem+xml" href="https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/memory" /> <Link rel="edit" type="application/vnd.vmware.vcloud.rasdItem+xml" href="https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/memory" /> <Link rel="down" type="application/vnd.vmware.vcloud.rasdItemsList+xml" href="https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/disks" /> <Link rel="edit" type="application/vnd.vmware.vcloud.rasdItemsList+xml" href="https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/disks" /> <Link rel="down" type="application/vnd.vmware.vcloud.rasdItemsList+xml" href="https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/media" /> <Link rel="down" type="application/vnd.vmware.vcloud.rasdItemsList+xml" href="https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/networkCards" /> <Link rel="edit" type="application/vnd.vmware.vcloud.rasdItemsList+xml" href="https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/networkCards" /> </ovf:VirtualHardwareSection> <ovf:OperatingSystemSection href="https://vcloud.example.com/api/vApp/vm-4/operatingSystemSection/" ... > <Link rel="edit" type="application/vnd.vmware.vcloud.operatingSystemSection+xml" href="https://vcloud.example.com/api/vApp/vm-4/operatingSystemSection/" /> ... </ovf:OperatingSystemSection> <NetworkConnectionSection> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConnectionSection+xml" href="https://vcloud.example.com/api/vApp/vm-4/networkConnectionSection/" /> <ovf:Info>Specifies the available VM network connections</ovf:Info>

VMware, Inc. 91

vCloud API Programming Guide

<PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex> <NetworkConnection network="vAppNetwork"> <NetworkConnectionIndex>0</NetworkConnectionIndex> <IpAddress>10.147.122.134</IpAddress> <IsConnected>false</IsConnected> <MACAddress>00:50:56:01:01:49</MACAddress> <IpAddressAllocationMode>POOL</IpAddressAllocationMode> </NetworkConnection> </NetworkConnectionSection> <GuestCustomizationSection> <Link rel="edit" href="https://vcloud.example.com/api/vApp/vm-4/guestCustomizationSection+xml/"> </Link> ... </GuestCustomizationSection> ... </Vm>

Summary of Vm Reconfiguration Requests

Vm reconfiguration requests retrieve or update modifiable sections of a virtual machine (Vm object)

API-URL is a URL of the form https://vcloud.example.com/api.

id is a unique identifier in the form of a UUID, as defined by RFC 4122.

Table 5-3. Summary of Vm Reconfiguration Requests

Operation Request Request Body Response

Retrieve the

NetworkConnectionSectio n of a virtual machine

Update the

NetworkConnectionSectio n of a virtual machine

Retrieve the

GuestCustomizationSecti on of a virtual machine

Update the

GuestCustomizationSecti on of a virtual machine

Retrieve the

OperatingSystemSection

of a virtual machine

Update the

OperatingSystemSection

of a virtual machine

Retrieve the

VirtualHardwareSection

of a virtual machine

GET API-URL/vApp/vm-id/ networkConnectionSectio n/

PUT API-URL/vApp/vm-id/ networkConnectionSectio n/

GET API-URL/vApp/vm-id/ guestCustomizationSectio n/

PUT API-URL/vApp/vm-id/ guestCustomizationSectio n/

GET API-URL/vApp/vm-id/ operatingSystemSection/

PUT API-URL/vApp/vm-id/ operatingSystemSection/

GET API-URL/vApp/vm-id/ virtualHardwareSection/

None

NetworkConnectionSectionTask

None

GuestCustomizationSectioTask

None

OperatingSystemSection Task

None

NetworkConnectionSectio n

GuestCustomizationSecti o

OperatingSystemSection

VirtualHardwareSection

92 VMware, Inc.

Chapter 5 Deploying and Operating vApps

Table 5-3. Summary of Vm Reconfiguration Requests (Continued)

Operation Request Request Body Response

Update the

VirtualHardwareSection

of a virtual machine

Retrieve the CPU configuration of a virtual machine

Update the CPU configuration of a virtual machine

Retrieve the memory item from the

VirtualHardwareSection

of a virtual machine

Update the memory item in the

VirtualHardwareSection

of a virtual machine

Retrieve virtual disk items from the

VirtualHardwareSection

of a virtual machine

Update virtual disk items in the

VirtualHardwareSection

of a virtual machine

Retrieve network card items from the

VirtualHardwareSection

of a virtual machine

Update network card items in the

VirtualHardwareSection

of a virtual machine

PUT API-URL/vApp/vm-id/ virtualHardwareSection/

GET API-URL/vApp/vm-id/ virtualHardwareSection/ cpu

PUT API-URL/vApp/vm-id/ virtualHardwareSection/ cpu

GET API-URL/vApp/vm-id/ virtualHardwareSection/ memory

PUT API-URL/vApp/vm-id/ virtualHardwareSection/ memory

GET API-URL/vApp/vm-id/ virtualHardwareSection/ disks

PUT API-URL/vApp/vm-id/ virtualHardwareSection/ disks

GET API-URL/vApp/vm-id/ virtualHardwareSection/ networkCards

PUT API-URL/vApp/vm-id/ virtualHardwareSection/ networkCards

VirtualHardwareSection Task

None

ovf:Item Task

None

ovf:Item Task

None

RasdItemsList Task

None

RasdItemsList Task

ovf:Item

RasdItemsList

vCloud API Custom Attributes

vCloud API custom attributes extend several elements in the OVF and RASD 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 5-4. vCloud API Custom Attributes for OVF and RASD Elements

RASD Resource

Element Name

rasd:Connection 10

VMware, Inc. 93

Type Attribute Name Attribute Type Description

ipAddressingMode xs:string IP addressing mode to use for this (Network adapters)

ipAddress xs:string If ipAddressingMode="MANUAL", (Network adapters)

connection. One of NONE, MANUAL, DHCP, POOL.

set the IP address here

vCloud API Programming Guide

Table 5-4. vCloud API Custom Attributes for OVF and RASD Elements (Continued)

Element Name

RASD Resource Type Attribute Name Attribute Type Description

rasd:Connection 10

(Network adapters)

rasd:HostResource 17 (Hard

disks)

rasd:HostResource 17 (Hard

disks)

rasd:HostResource 17 (Hard

disks)

ovf:OperatingSystemSec tion

N/A osType xs:string Internal VMware identifier for the

primaryNetworkCon

nection

capacity xs:string Hard disk capacity in megabytes. See

busType xs:string read-only

busSubType xs:string read-only

xs:boolean True if this is the primary network

connection of the virtual machine

“Retrieve or Modify the Hard Disk Configuration of a Virtual Machine,” on page 106

guest operating system. See

https://www.vmware.com/suppor t/developer/vcsdk/visdk41pubs/ApiReference/vim .vm.GuestOsDescriptor.GuestOsIde ntifier.html

For more information about OVF and RASD (CIM_ResourceAllocationSettingData) elements, see the OVF specification, available at http://www.dmtf.org/standards/published_documents/DSP0243_1.0.0.pdf.

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

Verify that you are logged in as a system administrator or the object owner.

Procedure

1 Retrieve the section to modify.

Make a GET request to the URL in the section's href attribute value.

2 Modify the retrieved section.

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.

94 VMware, Inc.

Chapter 5 Deploying and Operating vApps

Example: Retrieve a NetworkConfigSection

This example retrieves the NetworkConfigSection of the vApp shown in “Example: Configuration Links in a

vApp,” on page 88.

Request:

GET https://vcloud.example.com/api/vApp/vapp-7/networkConfigSection

Response:

200 OK Content-type: application/vnd.vmware.vcloud.networkConfigSection+xml ... <NetworkConfigSection xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" href="https://vcloud.example.com/api/vApp/vapp-7/networkConfigSection/" ovf:required="false"> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConfigSection+xml" href="https://vcloud.example.com/api/vApp/vapp-7/networkConfigSection/" /> <NetworkConfig networkName="vAppNetwork"> <Configuration> <IpScope> <IsInherited>true</IsInherited> <Gateway>10.147.56.253</Gateway> <Netmask>255.255.255.0</Netmask> <Dns1>10.147.115.1</Dns1> <Dns2>10.147.115.2</Dns2> <DnsSuffix>example.com</DnsSuffix> <IpRanges> <IpRange> <StartAddress>10.147.56.1</StartAddress> <EndAddress>10.147.56.255</EndAddress> </IpRange> </IpRanges> </IpScope> <ParentNetwork type="application/vnd.vmware.vcloud.network+xml" name="Internet" href="https://vcloud.example.com/api/network/54" /> <FenceMode>bridged</FenceMode> </Configuration> <IsDeployed>false</IsDeployed> </NetworkConfig> </NetworkConfigSection>

For an example that updates this section, see “Example: Update a NetworkConfigSection,” on page 96 .

VMware, Inc. 95

vCloud API Programming Guide

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

Verify that you are logged in as a system administrator or the object owner.

Procedure

1 Retrieve the vApp's NetworkConfigSection.

2 Modify the returned NetworkConfigSection as needed.

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 95. 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:

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.

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

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

Request:

PUT https://vcloud.example.com/api/vApp/vapp-7/networkConfigSection/ Content-type: application/vnd.vmware.vcloud.networkConfigSection+xml ... <?xml version="1.0" encoding="UTF-8"?> <NetworkConfigSection xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="vAppNetwork">

96 VMware, Inc.

<Configuration> <IpScope> <IsInherited>false</IsInherited> <Gateway>10.147.56.253</Gateway> <Netmask>255.255.255.0</Netmask> <Dns1>10.147.115.1</Dns1> <Dns2>10.147.115.2</Dns2> <DnsSuffix>example.com</DnsSuffix> <IpRanges> <IpRange> <StartAddress>10.147.56.1</StartAddress> <EndAddress>10.147.56.1</EndAddress> </IpRange> </IpRanges> </IpScope> <ParentNetwork type="application/vnd.vmware.vcloud.network+xml" name="Internet" href="https://vcloud.example.com/api/network/54" /> <FenceMode>natRouted</FenceMode> <Features> <FirewallService> <IsEnabled>true</IsEnabled> <FirewallRule> <IsEnabled>true</IsEnabled> <Description>FTP Rule</Description> <Policy>allow</Policy> <Protocols> <Tcp>true</Tcp> </Protocols> <Port>21</Port> <DestinationIp>10.147.115.1</DestinationIp> <SourcePort>-1</SourcePort> <SourceIp>Any</SourceIp> </FirewallRule> <FirewallRule> <IsEnabled>true</IsEnabled> <Description>SSH Rule</Description> <Policy>allow</Policy> <Protocols> <Tcp>true</Tcp> </Protocols> <Port>22</Port> <DestinationIp>10.147.115.1</DestinationIp> <SourcePort>-1</SourcePort> <SourceIp>Any</SourceIp> </FirewallRule> </FirewallService> <NatService> <IsEnabled>true</IsEnabled> <NatType>ipTranslation</NatType> <Policy>allowTraffic</Policy> <NatRule> <OneToOneVmRule> <MappingMode>manual</MappingMode>

Chapter 5 Deploying and Operating vApps

VMware, Inc. 97

vCloud API Programming Guide

Response:

202 Accepted Content-Type: application/vnd.vmware.vcloud.task+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 90, specifies an IP address that will not be available

after the vApp network is reconfigured as shown here. “Example: Update a NetworkConnectionSection,” on page 99 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 99. 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 99 allows the FirewallRules in this example to remain valid.

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

Verify that you are logged in as a system administrator or the object owner.

Procedure

1 Retrieve the virtual machine's NetworkConnectionSection.

2 Modify the returned NetworkConnectionSection as needed.

3 Update the NetworkConnectionSection in the virtual machine.

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.

98 VMware, Inc.

Chapter 5 Deploying and Operating vApps

Example: Update a NetworkConnectionSection

This example modifies the NetworkConnectionSection shown in “Example: Configuration Links in a Vm

Element,” on page 90 so that this network connection is compatible with the reconfigured vApp network to

which it must connect. See “Example: Update a NetworkConfigSection,” on page 96. The modified

NetworkConnectionSection in the request changes two values:

The IpAddress now specifies the address to which the vApp network's firewall allows access.

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. Element content is ignored, but the element itself must be present. In this example, we use the content to explain why the connection is configured this way.

Request:

PUT "https://vcloud.example.com/api/vApp/vm-4/networkConnectionSection/ Content-type: application/vnd.vmware.vcloud.networkConnectionSection+xml ... <?xml version="1.0" encoding="UTF-8"?> <NetworkConnectionSection type="application/vnd.vmware.vcloud.networkConnectionSection+xml" xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <ovf:Info>Firewall allows access to this address.</ovf:Info> <PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex> <NetworkConnection network="vAppNetwork"> <NetworkConnectionIndex>0</NetworkConnectionIndex> <IpAddress>10.147.115.1</IpAddress> <IsConnected>true</IsConnected> <MACAddress>00:50:56:01:01:49</MACAddress> <IpAddressAllocationMode>STATIC</IpAddressAllocationMode> </NetworkConnection> </NetworkConnectionSection>

Response:

202 Accepted Content-Type: application/vnd.vmware.vcloud.task+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

Verify that you are logged in as a system administrator or the object owner.

VMware, Inc. 99

vCloud API Programming Guide

Procedure

1 Retrieve the CPU section to modify.

Make a GET request to the URL in the section's href attribute value:

GET https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/cpu

2 Modify the retrieved section.

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.

The response to this request is a Task element that tracks the update operation. When the task is complete, the section is updated.

Example: Modify the CPU Configuration of a Virtual Machine

This request modifies the CPU section of the virtual machines shown in “Example: Configuration Links in a

Vm Element,” on page 90. The modified Item in the request body adds a second CPU to the Vm by changing

the rasd:VirtualQuantity value of the Item to 2.

Request:

PUT https://vcloud.example.com/api/vApp/vm-4/virtualHardwareSection/cpu Content-type: application/vnd.vmware.vcloud.rasdItem+xml ... <?xml version="1.0" encoding="UTF-8"?> <Item xmlns="http://schemas.dmtf.org/ovf/envelope/1" xmlns:vcloud="http://www.vmware.com/vcloud/v1.5" xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cimschema/2/CIM_ResourceAllocationSettingData" vcloud:type="application/vnd.vmware.vcloud.rasdItem+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> </Item>

Response:

202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Updating Virtual Application Linux FTP server (7)" ...> ... </Task>

100 VMware, Inc.

VMware vCloud Director - 1.5 Programming Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

vCloud API Programming Guide

About the VMware vCloud API 1

Object Taxonomy

Objects, References, and Representations

Links and Link Relations

Client Workflow Overview

vCloud API REST Requests

vCloud API REST Responses

Using the vCloud API with vCloud Director

REST Client Programs

About the Schema Reference Downloadable Archive

About the vCloud API Examples

Logging In

Find a Catalog and a vDC

Retrieve the Contents of a Catalog

Retrieve a Catalog Item

Retrieve Deployment Information From the vDC

Deploy the vApp

Get Information About a vApp

Displaying the Virtual Machine Console

Delete the vApp

Log Out

Exploring a Cloud 3

Summary of vCloud API Browsing Requests

Retrieve the Login URL and List of Supported API Versions

Create a Login Session

Retrieve a List of Organizations Accessible to You

Retrieve an Administrative View of a Cloud

Retrieve a List of vSphere Platform Operations and Objects for a Cloud

Summary of vCloud API Provisioning Requests

Upload an OVF Package to Create a vApp Template

Initiating the OVF Upload

Uploading the OVF Descriptor

Retrieving the Upload URLs

Uploading Referenced Files

Monitoring the Progress of an Upload

Using Ranged PUT requests to Complete a Partial Upload

Download a vApp Template as OVF

Enable the vApp Template for Download

Download the OVF Descriptor

Download a Referenced File

Upload a Media Image

Copying and Moving with the vCloud API

Capturing and Importing vApps

Cataloging vApp Templates and Media Images

Add an Item to a Catalog

Remove an Item from a Catalog

View or Change the Owner of an Object

Deploying and Operating vApps 5

Summary of vCloud API vApp and Virtual Machine Operations Requests

Create a vApp From a Template

Compose a vApp From Existing Virtual Machines

Recompose a vApp to Add or Remove Virtual Machines

Operate a vApp

Configuring vApps and Virtual Machines

Retrieve the Configuration Links for a vApp

Summary of vApp Reconfiguration Requests

Retrieve the Configuration Links for a Virtual Machine

Summary of Vm Reconfiguration Requests

vCloud API Custom Attributes

Retrieve or Update a Modifiable Section

Update a vApp Network Configuration

Update the NetworkConnectionSection of a Virtual Machine

Retrieve or Modify the CPU Configuration of a Virtual Machine