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.
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.
Contents vCloud API Programming Guide 7 1 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 2 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
vCloud API Programming Guide 5 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 6 Creating, Provisioning, and Managing Organizations 109 Summary of Administrative Requests 109 Administrator Credentials and Privileges 111 Organization Administration 112 Networ
Contents Common vCloud API Attributes 235 Retrieve an Object as an Entity 237 Index 239 VMware, Inc.
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.
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.
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.
Chapter 1 About the VMware vCloud API Virtual Datacenters 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 Virtual systems and media images are stored in a vDC and can be included in a catalog.
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. ...
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. GET catalogItem References the CatalogItem object that refers to this object. GET collaboration:abort Abort this blocking task. POST collaboration:fail Fail this blocking task.
vCloud API Programming Guide Table 1-1. Link Relationships and HTTP Request Types (Continued) 14 rel Attribute Value Action or Relationship Description Implied HTTP Verb power:shutdown Shut down this vApp or virtual machine. POST power:suspend Suspend this vApp or virtual machine. POST previousPage Reference to the previous page of a paginated response. GET publish Publish this catalog. POST recompose Recompose this vApp. POST reconnect Reconnect this vCenter Server to this cloud.
Chapter 1 About the VMware vCloud API 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.
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.
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.
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 includes a document body. 201 Created The request is valid. The requested object was created and can be found at the URL specified in the Location header. 202 Accepted The request is valid and a task was created to handle it. This response is usually accompanied by a Task element.
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/).
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. n n In an Operations list, you can search for the following items: n 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.
Chapter 1 About the VMware vCloud API Extends The base type from which this element is derived. XML Representation The XML representation of the element or type. Names of contained elements are links to the reference pages for those elements. Attributes A table listing the following properties of each attribute of the element or type: Attribute The name of the attribute. Type The primitive XML type of the attribute. Required Yes for attributes that are required.
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 Schema definition files for vCloud API version 1.0. 1.5 Schema definition files for vCloud API version 1.5. schemas Additional schema definition files that are version-independent or from external sources such as DMTF.
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.
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.
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 n user is the user's login name. n organization is the name of an organization of which the user is a member. n password is the user's password. These credentials must be supplied in a MIME Base64 encoding, as specified in RFC 1421.
vCloud API Programming Guide n 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.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow type="application/vnd.vmware.vcloud.org+xml" href="https://vcloud.example.com/api/org/5"> PAGE 28
vCloud API Programming Guide 2 Examine the response to find the links to the organization's catalogs. These links have the following form: 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.
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.
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"/> 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.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow ... ... PAGE 32vCloud 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.
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"> Example FTP Server Configuration parameters for logical networks PAGE 34vCloud API Programming Guide ... > Get Information About a vApp When you instantiate a vApp template, the server returns the URL of the resulting vApp. You can use this URL with a GET request to retrieve information that you can use to connect to the vApp, modify its configuration, and operate it.
Chapter 2 Hello vCloud: A Simplified RESTful Workflow Response: 200 OK Content-Type: application/vnd.vmware.vcloud.vApp+xml ... ... PAGE 36vCloud API Programming Guide href="https://vcloud.example.com/api/vApp/vapp-7/networkConfigSection/" ovf:required="false"> Configuration parameters for vAppNetwork ... PAGE 37Chapter 2 Hello vCloud: A Simplified RESTful Workflow PAGE 38
vCloud API Programming Guide n 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.
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.
vCloud API Programming Guide Request: DELETE https://vcloud.example.com/api/session x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM= Response: 200 OK 40 VMware, Inc.
3 Exploring a Cloud 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.
vCloud API Programming Guide Table 3-1.
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: n A LoginUrl element that contains the URL to which a client can make a login request to access that version of the vCloud API. See “Logging In,” on page 24.
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 n Verify that you know the login URL. See “Retrieve the Login URL and List of Supported API Versions,” on page 42 n Verify that you know the username and password of the system administrator or a member of one of the organizations in the cloud.
Chapter 3 Exploring a Cloud Request: POST https://vcloud.example.com/api/sessions Authorization: Basic encoded-credentials Accept: application/*+xml;version=1.5 Response: 200 OK x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM= Content-Type: application/vnd.vmware.vcloud.session+xml ... PAGE 46vCloud 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.
Chapter 3 Exploring a Cloud href="https://vcloud.example.com/api/org/5" /> 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.
vCloud API Programming Guide xmlns="http://www.vmware.com/vcloud/v1.5" name="vCloud" href="https://vcloud.example.com/api/admin"> PAGE 49
Chapter 3 Exploring a Cloud type="application/vnd.vmware.admin.role+xml" name="Catalog Creator" href="https://vcloud.example.com/api/admin/role/103" /> PAGE 50vCloud API Programming Guide Response: 200 OK Content-Type: application/vnd.vmware.admin.vmwextension+xml ... PAGE 51Chapter 3 Exploring a Cloud href="https://vcloud.example.com/api/admin/extension/datastores" />
VMware, Inc.
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.
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. n API-URL is a URL of the form https://vcloud.example.com/api. n 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.
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 APIURL/catalog/ id/action/controlAccess ControlAccessParams ControlAccessParams Retrieve the owner of a media object.
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.
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: PAGE 58
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"> PAGE 59
Chapter 4 Provisioning an Organization with vApps, Templates, and Media Uploading the OVF Descriptor 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. 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.
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 ... PAGE 61Chapter 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.
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.
Chapter 4 Provisioning an Organization with vApps, Templates, and Media bytesTransferred="500000000" name="disk0.vmdk"> ... 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.
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.
Chapter 4 Provisioning an Organization with vApps, Templates, and Media Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... 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.
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 ... ...
Chapter 4 Provisioning an Organization with vApps, Templates, and Media 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.
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 ... PAGE 69Chapter 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.
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.
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 . PAGE 72vCloud 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.
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" /> Approved template for public FTP sites PAGE 74vCloud 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.
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.
vCloud API Programming Guide n An undeployed vApp, created when a vApp template is instantiated without also being deployed, or a deployed vApp is undeployed. n A deployed vApp, ready to be powered on and operated. Instantiation can include deployment, poweron, or both. Figure 5-1. vApp State Transitions OVF package descriptor.ovf disk0.vmdk upload vApp template ... ... instantiate vApp
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. n API-URL is a URL of the form https://vcloud.example.com/api. n id is a unique identifier in the form of a UUID, as defined by RFC 4122.
vCloud API Programming Guide Table 5-1.
Chapter 5 Deploying and Operating vApps Template contents that might influence composition of the request body include the following sections: n A NetworkConnectionSection that specifies network connection details for a virtual machine.
vCloud API Programming Guide Request: POST https://vcloud.example.com/api/vdc/5/action/instantiateVAppTemplate Content-Type: application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml ... PAGE 81Chapter 5 Deploying and Operating vApps n 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: n An InstantiationParams element specific to that virtual machine.
vCloud API Programming Guide Request: POST https://vcloud.example.com/api/vdc/5/action/composeVApp Content-Type: application/vnd.vmware.vcloud.composeVAppParams+xml ... PAGE 83Chapter 5 Deploying and Operating vApps Response: 201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml ... ... Composed CRM Appliance ...
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. ...
Chapter 5 Deploying and Operating vApps networkName="CRMApplianceNetwork"> natRouted PAGE 86vCloud API Programming Guide n A request made to a Vm power URL affects only that virtual machine. n 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.
Chapter 5 Deploying and Operating vApps Owner 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. ProductSection elements 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.
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.
Chapter 5 Deploying and Operating vApps href="https://vcloud.example.com/api/vApp/vapp-7/leaseSettingsSection/" /> ... ... ...
vCloud API Programming Guide Table 5-2. Summary of vApp Reconfiguration Requests (Continued) Operation Request Request Body Response Retrieve vApp NetworkConfigSection GET API-URL/vApp/vappid/ networkConfigSection/ None NetworkConfigSection Update vApp NetworkConfigSection PUT API-URL/vApp/vappid/ networkConfigSection/ NetworkConfigSection Task Retrieve the Configuration Links for a Virtual Machine A virtual machine is represented by a Vm element.
Chapter 5 Deploying and Operating vApps PAGE 92
vCloud API Programming Guide 0 0 10.147.122.134 false 00:50:56:01:01:49 POOL PAGE 93Chapter 5 Deploying and Operating vApps Table 5-3.
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) primaryNetworkCon nection xs:boolean True if this is the primary network connection of the virtual machine rasd:HostResource 17 (Hard disks) capacity xs:string Hard disk capacity in megabytes.
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 ... PAGE 96vCloud 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.
Chapter 5 Deploying and Operating vApps false 10.147.56.253 255.255.255.0 10.147.115.1 10.147.115.2 example.com 10.147.56.1 10.147.56.1 PAGE 98vCloud API Programming Guide 64.100.10.1 20ea086f-1a6a-4fb2-8e2e-23372facf7de 0
Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ...
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.
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. 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.
Chapter 5 Deploying and Operating vApps Retrieve or Modify the GuestCustomizationSection of a Virtual Machine The GuestCustomizationSection element includes a customization script and other parameters that are applied when you customize a virtual machine. The GuestCustomizationSection includes predefined property names that VMware guest customization tools recognize.
vCloud API Programming Guide true true false Win2K3 Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ...
Chapter 5 Deploying and Operating vApps 3 n If a Property element that is present in the existing ProductSection has different attributes, qualifiers, or other details in the update, the Property in the update replaces the existing one. n If a Property element that is present in the existing ProductSection has no Value in the update, the existing Property and Value remain unchanged. Update the section with your modifications. Find the Link element in the ProductSectionList where rel="edit".
vCloud API Programming Guide Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... After the vApp is powered on, a virtual machine can retrieve the ovf:Environment document in the following ways: n It can use the default OVF iso transport type. This makes the environment document available as a file named ovf-env.xml on an ISO image that is mounted on the first available CD-ROM device on the virtual machine.
Chapter 5 Deploying and Operating vApps Retrieve or Modify Groups of Related Sections in a Virtual Machine The vCloud API provides links that you can use to retrieve or update groups of sections that define related hardware items such as disks, media devices, and network cards in a Vm element. As shown in “Example: Configuration Links in a Vm Element,” on page 90, Link elements for disks, media devices, and network cards are grouped at the end of the VirtualHardwareSection.
vCloud API Programming Guide type="application/vnd.vmware.vcloud.rasdItemsList+xml" href="https://vcloud.example.
Chapter 5 Deploying and Operating vApps Procedure 1 Retrieve the hard disk configuration from the virtual machine. Make a GET request to the virtual machine's virtualHardwareSection/disks link. GET https://vcloud.example.
vCloud API Programming Guide Hard disk 1 PAGE 1096 Creating, Provisioning, and Managing Organizations The VMware vCloud API supports objects and operations that an organization or a system administrator can use to automate tasks associated with provisioning organizations with resources and users. A successful login by an organization or system administrator returns a Session element, which contains a link that enables the administrator to retrieve a VCloud element. This element provides access to a cloud-wide namespace of administrative objects.
vCloud API Programming Guide Table 6-1. Summary of Administrative Requests (Continued) 110 Operation Request Request Body Response Disable an organization. POST APIURL/admin/org/ id/action/disable None 204 No Content Update an organization. PUT API-URL/admin/org/id AdminOrg AdminOrg Create a network in an organization. POST APIURL/admin/org/ id/networks OrgNetwork OrgNetwork Update a network in an organization.
Chapter 6 Creating, Provisioning, and Managing Organizations Table 6-1. Summary of Administrative Requests (Continued) Operation Request Request Body Response Delete a user. DELETE APIURL/admin/user/id None 204 No Content Import a group. POST APIURL/admin/org/id/groups Group Group Delete a group. DELETE APIURL/admin/group/id None 204 No Content Update group properties. PUT APIURL/admin/group/id Group Group Create a role.
vCloud API Programming Guide Example: The System Organization Every VCloud object contains a link, like the one shown here, to the System organization. ... ... Unlike Org and AdminOrg objects, the System organization cannot contain catalogs, vDCs, groups, or users who are not system administrators.
Chapter 6 Creating, Provisioning, and Managing Organizations 3 Create an AdminOrg element that specifies the properties of the organization. See the request portion of “Example: Create an Organization,” on page 113. 4 POST the AdminOrg element you created in Step 3 to the URL described in Step 2. See the request portion of “Example: Create an Organization,” on page 113.
vCloud API Programming Guide Response: 201 Created Content-Type: application/vnd.vmware.admin.organization+xml ... PAGE 115Chapter 6 Creating, Provisioning, and Managing Organizations rel="down" type="application/vnd.vmware.admin.organizationEmailSettings+xml" href="https://vcloud.example.com/api/admin/org/26/settings/email" /> PAGE 116
vCloud API Programming Guide Retrieve or Update Organization Settings A system or organization administrator can retrieve or update organization properties. These properties establish default values for leases on vApps and vApp templates, email service and message properties, and similar settings. An AdminOrg element contains an OrgSettings element, which contains the following elements, each of which represents a group of related organization settings.
Chapter 6 Creating, Provisioning, and Managing Organizations 5 Update the settings with your modifications. Find the Link element in the settings element where rel="edit". Make a PUT request to the URL in that link's href attribute value, and supply the modified section as the request body. See the request portion of “Example: Update Organization General Settings,” on page 117.
vCloud API Programming Guide n Retrieve the XML representation of the organization. See “Retrieve a List of Organizations Accessible to You,” on page 46. Procedure n To enable an organization, POST a request to its action/enable link. n To disable an organization, POST a request to its action/disable link. n To remove an organization: a POST a request to the action/disable link to disable the organization. After the organization is disabled, its representation includes a rel="remove" link.
Chapter 6 Creating, Provisioning, and Managing Organizations Every VApp element includes a link like this one, which you can use to retrieve details of its vApp networks. PAGE 120
vCloud API Programming Guide Table 6-2. Types of Organization Networks and Their Requirements Organization Network Type Description Requirements External organization network - direct connection Accessible by multiple organizations. Virtual machines belonging to different organizations can connect to and see traffic on this network. This network provides direct layer 2 connectivity to machines outside of the organization.
Chapter 6 Creating, Provisioning, and Managing Organizations Network Services vApp and organization networks can include any of the following services, defined in the Features element of the network's Configuration. DhcpService Provides DHCP services to virtual machines on the network. FirewallService Allows you to create firewall rules that, when matched, block or allow incoming or outgoing network traffic. See “vCloud Director Firewall Configurations,” on page 122.
vCloud API Programming Guide The corresponding element for network pools, VMWNetworkPoolReferences, is similar. In most cases, you can supply just the href attribute value when you specify an external network or network pool in an organization network creation request.
Chapter 6 Creating, Provisioning, and Managing Organizations Rules are applied to packets in the order in which the FirewallRule elements appear in the FirewallService definition.
vCloud API Programming Guide NextHopIp The IP address of the next hop on the route. This address is typically the value in the ExternalIp element of the RouterInfo from the network to which this static route connects. Interface Specify internal if NextHopIp contains an IP address in the same network. Specify external if NextHopIp contains an IP address in a different network.
Chapter 6 Creating, Provisioning, and Managing Organizations Add a Network to an Organization To add a network to an organization, a system administrator POSTs an OrgNetwork element to the organization's add URL for networks. A newly created organization has no networks in it. A system administrator must create an organization network from resources that an external network or network pool provide.
vCloud API Programming Guide Procedure 1 Choose an external network on which to base the new network. 2 Create an OrgNetwork element. Specify the href of the external network you chose in Step 1 in the ParentNetwork element. The type and name attributes are optional here. See the request portion of “Example: Create an Organization Network With a Direct Connection,” on page 126. 3 POST the OrgNetwork element you created in Step 2 to the URL for adding networks to the organization.
Chapter 6 Creating, Provisioning, and Managing Organizations Response: 201 Created Content-Type: application/vnd.vmware.admin.orgNetwork+xml ... PAGE 128vCloud API Programming Guide Create an Organization Network With a Routed Connection An organization network with a routed connection is accessible only by this organization, and provides controlled access to an external network. System administrators and organization administrators can configure settings to make specific virtual machines accessible from the external network. When you create an organization network with a routed connection, you actually create two networks joined by a virtual router.
Chapter 6 Creating, Provisioning, and Managing Organizations Request: POST https://vcloud.example.com/api/admin/org/26/networks Content-Type: application/vnd.vmware.admin.orgNetwork+xml ... NAT-routed organization network false 192.168.0.1 255.255.255.0 10.147.115.
vCloud API Programming Guide true deny outgoing rdp drop true 3389 Any -1 Any out true false portForwarding allowTraffic
Chapter 6 Creating, Provisioning, and Managing Organizations status="running" startTime="2011-06-28T10:31:39.788-07:00" operationName="networkCreateOrgNetwork" operation="Creating Network RoutedOrgNetwork(54)" expiryTime="2011-10-06T10:31:39.788-07:00" ... ... PAGE 132vCloud API Programming Guide type="application/vnd.vmware.admin.vmwvirtualcenter+xml" href="https://vcloud.example.com/api/admin/extension/vimServer/82" /> dvportgroup-908 DV_PORTGROUP PAGE 133
Chapter 6 Creating, Provisioning, and Managing Organizations 3600 7200 192.168.0.2 192.168.0.
vCloud API Programming Guide name="netpool_vc1" href="https://vcloud.example.com/api/admin/extension/networkPool/313" /> Modify the OrgNetwork response to create a new request body. Modifications shown here include the following: n Link elements, href attributes, and other content that the server adds to a response but ignores in a request have been removed. n The reference to the NetworkPool and ParentNetwork have been removed.
Chapter 6 Creating, Provisioning, and Managing Organizations true allow ssh allow true 22 Any -1 Any in false true deny outgoing rdp drop true
vCloud API Programming Guide The response is a Task element. When the task is complete, the network is updated. Response: 202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... ... Create an Isolated Organization Network An isolated organization network is accessible only by the organization for which it is created. Only virtual machines in this organization can connect to and see traffic on the isolated network.
Chapter 6 Creating, Provisioning, and Managing Organizations false 3600 7200 192.168.0.2 192.168.0.99 PAGE 138vCloud API Programming Guide Synchronize Syslog Server Settings for a Network When you change the IP addresses of the primary or secondary syslog server for a cloud, you must also synchronize the syslog server settings for organization and vApp networks that include a firewall service that has logging enabled.
Chapter 6 Creating, Provisioning, and Managing Organizations vDC Administration A newly created organization has no vDCs in it. A system administrator must use system resources to create them. 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.
vCloud API Programming Guide 3 Choose a provider vDC to supply resources for the new organization vDC. a Retrieve the XML representation of the VCloud object and examine the ProviderVdcReferences element it contains. The following request retrieves the representation of the VCloud object: GET https://vcloud.example.com/api/admin The VCloud element contains a ProviderVdcReferences element .
Chapter 6 Creating, Provisioning, and Managing Organizations Request: POST https://vcloud.example.com/api/admin/org/26/vdcs Content-Type: application/vnd.vmware.admin.vdc+xml ... PAGE 142vCloud API Programming Guide href="https://vcloud.example.com/api/admin/org/26" /> PAGE 143
Chapter 6 Creating, Provisioning, and Managing Organizations n Additional Link elements are included for operations that are now valid, but that were not valid while the vDC was under construction.
vCloud API Programming Guide MHz 0 2048 0 0 MB 0 2048 0 0 PAGE 145Chapter 6 Creating, Provisioning, and Managing Organizations n To disable a vDC, POST a request to its action/disable link. n To remove a vDC: a POST a request to its action/disable link to disable the vDC. After the vDC is disabled, its representation includes a rel="remove" link. b Make a DELETE request to the vDC's rel="remove" link. The server takes the requested action and returns an HTTP status of 204 No Content. Catalog Administration A newly created organization has no catalogs in it.
vCloud API Programming Guide 3 Create an AdminCatalog element. See the request portion of “Example: Create a Catalog,” on page 146. 4 POST the AdminCatalog element to the organization's add URL for catalogs. See the request portion of “Example: Create a Catalog,” on page 146. The server creates an empty catalog. See the response portion of “Example: Create a Catalog,” on page 146.
Chapter 6 Creating, Provisioning, and Managing Organizations PAGE 148
vCloud API Programming Guide 3 Create a PublishCatalogParams element that contains an IsPublished element with a value of true. 4 POST the PublishCatalogParams body to the catalog's rel="publish" URL. The catalog is published and becomes available to administrators in other organizations in the cloud. Example: Publish a Catalog Request: POST https://vcloud.example.com/api/admin/catalog/32/action/publish Content-Type: application/vnd.vmware.admin.publishCatalogParams+xml ...
Chapter 6 Creating, Provisioning, and Managing Organizations When you create a user, you must include the Role and Password elements in the request body. The role can be a predefined role or one created by the organization administrator. For more information about retrieving a list of predefined roles, see “Retrieve an Administrative View of a Cloud,” on page 47. For more information about creating new roles, see “Create a Role,” on page 156.
vCloud API Programming Guide rel="edit" type="application/vnd.vmware.admin.user+xml" href="https://vcloud.example.com/api/admin/user/85" /> Example User Full Name user@example.com true false false 0 0 PAGE 151Chapter 6 Creating, Provisioning, and Managing Organizations Request: POST https://vcloud.example.com/api/admin/org/26/users Content-Type: application/vnd.vmware.admin.user+xml ... true true PAGE 152vCloud API Programming Guide n Verify that your organization has defined an LDAP service to use. Procedure 1 Create a Group element that identifies the LDAP group to import. The name attribute of the Group element must match the LDAP group name, as specified in the organization's LDAP properties. You must include a Role element in the request body. The role specified in this element is assigned to all group members during the import. 2 POST the Group element to the organization's groups URL.
Chapter 6 Creating, Provisioning, and Managing Organizations Until the import is complete, the Group element contains only partial information. After the import is complete, the element includes a list of users and other information. PAGE 154vCloud API Programming Guide Table 6-3.
Chapter 6 Creating, Provisioning, and Managing Organizations Table 6-3.
vCloud API Programming Guide Table 6-3.
Chapter 6 Creating, Provisioning, and Managing Organizations PAGE 158vCloud API Programming Guide n Links where rel="controlAccess". Use this kind of link to specify new access control settings for the object identified in the href value. You specify the new access control settings in a ControlAccessParams element that you post to the URL that the href value of this link specifies.
Chapter 6 Creating, Provisioning, and Managing Organizations Viewing or Changing the Owner of a vApp or Catalog Ownership of a VApp or Catalog object is expressed in an Owner element that you can retrieve from the object. This element contains a User element that identifies the owner with a reference to a specific user. The initial owner of an object is the user who created it.
vCloud API Programming Guide 160 VMware, Inc.
Using vCloud API Extensions to Provision and Manage a Cloud 7 The VMware vCloud API includes extensions that support operations on the vSphere platform, which provides resources to vCloud Director. A system administrator can use these extensions to retrieve or update the configuration of a cloud, add or remove resources such as vCenter servers, network pools and external networks, and import vApps and media from vCenter. Only the system administrator can perform vSphere platform operations.
vCloud API Programming Guide Table 7-1. Summary of vSphere Platform Extension Requests 162 Operation Request Request Body Response Retrieve a list of provider vDCs in a cloud. GET APIURL/admin/extension/ providerVdcReferences None VMWProviderVdcReference s Retrieve a list of external networks in a cloud. GET APIURL/admin/extension/ externalNetworkReference s None VMWExternalNetworkRefer ences Retrieve a list of network pools in a cloud.
Chapter 7 Using vCloud API Extensions to Provision and Manage a Cloud Table 7-1. Summary of vSphere Platform Extension Requests (Continued) Operation Request Request Body Response Repair a host. POST APIURL/admin/extension/hos t/id/action/repair None 204 No Content Upgrade a host. POST APIURL/admin/extension/hos t/id/action/upgrade None Task Create a provider vDC. POST APIURL/admin/extension/pro vidervdcs VMWProviderVdc VMWProviderVdc Retrieve a provider vDC.
vCloud API Programming Guide Table 7-1. Summary of vSphere Platform Extension Requests (Continued) 164 Operation Request Request Body Response Import a virtual machine from vCenter as a vApp template. POST APIURL/admin/extension/ vimServer/ id/importVmAsVappTemp late ImportVmAsVAppTemplate Params VAppTemplate Retrieve the representation of a datastore. [NEW] GET APIURL/admin/extension/data store/id None Datastore Enable a datastore.
Chapter 7 Using vCloud API Extensions to Provision and Manage a Cloud Retrieve or Update System Settings A system administrator can retrieve or update a cloud-wide set of system properties. These properties specify default values and behaviors for the cloud and all of the organizations in it. The SystemSettings element includes all system settings for this cloud. The element also includes links that allow you to retrieve these subsidiary elements, which define specific categories of settings.
vCloud API Programming Guide Attach a vCenter Server A system administrator can register a vCenter server and a companion vShield Manager server for use in a cloud by making a POST request to the cloud’s action/registervimserver URL and supplying a RegisterVimServerParams request body Prerequisites n Verify that you are logged in as a system administrator. n Verify that you know the name, IP address, and administrator password of the vCenter server and vShield Manager server.
Chapter 7 Using vCloud API Extensions to Provision and Manage a Cloud name="VSM-VC-22"> Administrator Pa55w0rd https://10.100.121.66 Response: 200 OK Content-Type: application/vnd.vmware.admin.registerVimServerParams+xml ... PAGE 168vCloud API Programming Guide n To see a list of references to ESX/ESXi hosts managed by this vCenter server, retrieve the hostReferences link. n To see a list of references to virtual machines on ESX/ESXi hosts managed by this vCenter server, retrieve the vmsList link. Example: Resources on a vCenter Server Request: GET https://vcloud.example.com/api/admin/extension/vimServer/9 Response: 200 OK ... PAGE 169Chapter 7 Using vCloud API Extensions to Provision and Manage a Cloud Prerequisites n Verify that you are logged in as a system administrator. n Retrieve the XML representation of a vCenter server registered to your cloud. See “Finding Available vCenter Resources,” on page 167. Procedure 1 Examine the VimServer element to locate its resourcePoolList link. The link has the following form: PAGE 170vCloud API Programming Guide DATASTORE resgroup-230 RESOURCE_POOL PAGE 171Chapter 7 Using vCloud API Extensions to Provision and Manage a Cloud Response: 200 OK Content-Type: application/vnd.vmware.admin.vimservernetworks+xml ... PAGE 172vCloud API Programming Guide 3 Retrieve the list of virtual machines. See the request portion of “Example: Retrieve a List of Virtual Machines from a vCenter Server,” on page 172. If the list is empty, no virtual machines are in the server's inventory. Example: Retrieve a List of Virtual Machines from a vCenter Server Request: GET https://vcloud.example.com/api/admin/extension/vimServer/9/vmsList Response: 200 OK Content-Type: application/vnd.vmware.admin.vmsobjectrefslist+xml ...
Chapter 7 Using vCloud API Extensions to Provision and Manage a Cloud Create a Provider vDC A Provider vDC is a collection of compute, memory, and storage resources from one vCenter. A system administrator can make resources from a provider vDC available through organization vDCs in the cloud. A Provider vDC is represented as a VMWProviderVdc element in the extension view and a ProviderVdc element in the admin view.
vCloud API Programming Guide Example: Create a Provider vDC This request creates a small Provider vDC using a resource pool and datastore extracted from the response portion of “Example: Retrieve a List of Resource Pools from a vCenter Server,” on page 169. In practice, the DataStoreRefs element typically includes additional VimObjectRef elements that reference other datastores available on the specified VimServer.
Chapter 7 Using vCloud API Extensions to Provision and Manage a Cloud status="0" name="PvDC-Example" id="urn:vcloud:providervdc:35" type="application/vnd.vmware.admin.vmwprovidervdc+xml" href="https://vcloud.example.com/api/admin/extension/providervdc/35" ... > PAGE 176vCloud API Programming Guide datastore-173 DATASTORE PAGE 177Chapter 7 Using vCloud API Extensions to Provision and Manage a Cloud 2 Locate the resourcePools link in the VMWProviderVdc. Every VMWProviderVdc element includes a link like this one to the provider vDC's resource pools. 3 Retrieve the VMWProviderVdcResourcePoolSet for the provider vDC.
vCloud API Programming Guide type="application/vnd.vmware.admin.vmwvirtualcenter+xml" href="https://vcloud.example.com/api/admin/extension/vimServer/9" /> resgroup-235 RESOURCE_POOL PAGE 179Chapter 7 Using vCloud API Extensions to Provision and Manage a Cloud Example: Add Resource Pools to a Provider vDC This example adds a resource pool to the Provider vDC created in “Example: Create a Provider vDC,” on page 174. The additional resource pool is hosted on the same vCenter server that hosts the existing resource pool. See “Retrieve a List of Resource Pools from a vCenter Server,” on page 168 for an example that lists the resource pools available on that server. Request: POST https://vcloud.
vCloud API Programming Guide Example: Remove a Resource Pool From a Provider vDC This request removes one of the two resource pools shown in “Retrieve a Provider vDC Resource Pool Set,” on page 176. The resource pool removed is the one that contains false. The response is a task. Request: POST https://vcloud.example.com/api/admin/extension/providervdc/35/action/updateResourcePools Content-Type: application/vnd.vmware.admin.resourcePoolSetUpdateParams+xml ...
Chapter 7 Using vCloud API Extensions to Provision and Manage a Cloud 2 Examine the response to locate the Link element that contains the URL for adding external networks to the cloud. This element has a rel attribute value of add and a type attribute value of application/vnd.vmware.admin.vmwexternalnet+xml, as shown here: PAGE 182
vCloud API Programming Guide network-175 NETWORK The response includes a Task that tracks the creation of the network, and a set of Link elements that you can use to operate on or modify it. Response: 201 Created Content-Type: application/vnd.vmware.admin/vmwexternalnet+xml ... PAGE 183Chapter 7 Using vCloud API Extensions to Provision and Manage a Cloud eng.vmware.com isolated PAGE 184vCloud API Programming Guide The server creates the network pool and returns a VMWNetworkPool element that includes the contents you POSTed, along with a set of Link elements that you can use to access, remove, disable, or modify it. A reference to the new network pool is added to the VMWNetworkPoolReferences element of the VCloud. Network resources you specified in the VMWNetworkPool element are removed from the VimObjectRefList of the vCenter server.
Chapter 7 Using vCloud API Extensions to Provision and Manage a Cloud The response includes a Task that tracks the creation of the network pool, and a set of Link elements that you can use to operate on or modify it. Response: 201 Created Content-Type: application/vnd.vmware.admin.networkPool+xml ... PAGE 186vCloud API Programming Guide Procedure 1 Choose a vCenter server to provide a switch for the network pool. 2 Create a VMWNetworkPool element that specifies the properties of the network pool. 3 POST the VMWNetworkPool element you created in Step 2 to your cloud's add URL for networkPools. See the request portion of “Example: Create an Isolation-Backed Network Pool,” on page 186. Example: Create an Isolation-Backed Network Pool Request: POST https://vcloud.example.
Chapter 7 Using vCloud API Extensions to Provision and Manage a Cloud rel="edit" type="application/vnd.vmware.admin.networkPool+xml" href="https://vcloud.example.com/api/admin/extension/networkPool/70" /> Example isolation-backed network pool ...
vCloud API Programming Guide type="application/vnd.vmware.admin.networkPool+xml"> Example portgroup-backed network pool dvportgroup-32 DV_PORTGROUP PAGE 189Chapter 7 Using vCloud API Extensions to Provision and Manage a Cloud Import a Virtual Machine from vCenter A system administrator can import virtual machines from the inventory of any vCenter server registered to vCloud Director. You can import the virtual machines to any vDC in a cloud, and you can import them in vApp or vApp template form.
vCloud API Programming Guide Example: Import a Virtual Machine as a vApp This example imports one of the virtual machines shown in the response portion of “Example: Retrieve a List of Virtual Machines from a vCenter Server,” on page 172. The request body is an ImportVmAsVAppParams element whose sourceMove attribute specifies that the source virtual machine should remain in vCenter inventory after the import is complete.
Chapter 7 Using vCloud API Extensions to Provision and Manage a Cloud Procedure 1 Create an ImportVmAsVAppTemplateParams element that specifies the VmMoRef of the source virtual machine, a target vDC to hold the imported vApp template, and an optional catalog where you want to place a reference to the template. 2 POST the ImportVmAsVAppTemplateParams element to the importVmAsVAppTemplate link of the source vCenter server.
vCloud API Programming Guide Relocate a Virtual Machine to a Different Datastore A Vm element, whether part of a Vapp or VappTemplate element, includes an action/relocate link that you can use to move the virtual machine to a different datastore In both vApps and vApp templates, virtual machines are defined by a combination of metadata in the vCloud Director database and virtual disk files stored on a datastore in the cloud.
Chapter 7 Using vCloud API Extensions to Provision and Manage a Cloud 3 Find the action/relocate link for the Vm, and note the datastore that the Vm currently occupies. This fragment of the response to the request made in Step 2 includes the action/relocate link and the reference to the datastore that the Vm currently occupies. ... PAGE 194vCloud API Programming Guide 194 VMware, Inc.
Working With Object Metadata 8 The vCloud API provides a general-purpose facility for associating user-defined metadata with an object. A system administrator or the owner of an object can use the metadata link in the object's representation to access object metadata. The representations of most first-class objects in the vCloud API include a link to a Metadata element, which contains zero or more name=value pairs that the owner of an object can create, retrieve, update, and delete.
vCloud API Programming Guide vCloud API Object Metadata Limits The following limits apply to vCloud API object metadata: Metadata key size The contents of a Key element in a MetadataEntry cannot exceed 256 Unicode characters. Metadata size The size of all Metadata for an object, computed as the sum of all Key and Value UTF-8 strings, cannot exceed 128 KB. MetadataEntry limit The total metadata associated with an object cannot exceed 1024 pairs, where a pair consists of a Key and corresponding Value.
Chapter 8 Working With Object Metadata 2 Retrieve the Metadata element. If the object has no metadata, the element contains only a rel="edit" link that you can use when modifying the element and a rel="up" link that references the containing object, as shown in this example. PAGE 198vCloud API Programming Guide operationName="metadataUpdate" operation="Updating metadata for Organization (26)" ... > ... After the task is complete, the Metadata element is updated to contain the entries specified in the request, along with links that you can use to retrieve or update individual values.
Chapter 8 Working With Object Metadata Retrieve or Update a Metadata Value Each name=value pair in an object's metadata is represented as a MetadataEntry element, which includes links that a system administrator or object owner can use to retrieve or update the metadata value, or delete the MetadataEntry. Prerequisites n Verify that you are logged in as a system administrator or the object owner. n Retrieve the object's Metadata element.
vCloud API Programming Guide operation="Updating metadata for Organization (26)" ... > ... 200 VMware, Inc.
Using the Query Service 9 You can use the vCloud API query service to query the vCloud Director database for information about objects in the cloud. The query service provides the following kinds of queries: n Typed queries, which require you to construct a query URL that specifies a query type and optional parameters. n Packaged queries, which have well-known URLs and can accept many of the same parameters used with typed queries.
vCloud API Programming Guide n param is an optional query parameter. Zero or more parameters are allowed. See “Query Parameters,” on page 211. n filter is an optional filter expression. At most one filter expression is allowed. See “Filter Expressions,” on page 212.
Chapter 9 Using the Query Service Table 9-1.
vCloud API Programming Guide Table 9-1. Query Types (Continued) Type Name Result Set User Admin Syste m Format virtualCenter All vCenter servers registered to the system No No YES All vm All virtual machines in your organization (or in the system, if the query is run by a system administrator) YES YES No All Examples Simple typed query using default (records) format. GET https://vcloud.example.com/api/query?type=user Response: PAGE 205Chapter 9 Using the Query Service deployedVMQuota="0" href="https://vcloud.example.com/api/admin/user/24" />
Simple typed query using references format. GET https://vcloud.example.
vCloud API Programming Guide Response: PAGE 207Chapter 9 Using the Query Service name="bob" href="https://vcloud.example.com/api/admin/user/39" />
Packaged Queries Packaged queries have well-known URLs and can accept most of the parameters used with typed queries. Query Syntax Packaged queries have the following syntax: API-URL/query-url[?param][¶m ...
vCloud API Programming Guide Table 9-2. Packaged Queries (Continued) Query URL Result Set API-URL/vms/query All virtual machines that you can view or modify API-URL/admin/groups/query Groups in all organizations in the system API-URL/admin/users/query Users in all organizations in the system API-URL/admin/strandedUsers/query Stranded users in the organization. When you delete an LDAP group, users who were imported from that group become stranded and cannot log in.
Chapter 9 Using the Query Service name="VAM" isShared="true" isPublished="true" description="" createdOn="2011-03-21T14:28:09.273-07:00" href="https://vcloud.example.com/api/catalog/150" /> PAGE 210vCloud API Programming Guide Response: PAGE 211Chapter 9 Using the Query Service xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... > PAGE 212
vCloud API Programming Guide Table 9-3. Query Parameters Parameter Name Parameter Description Default type The type of the query. Type names are case-sensitive. See “Query Types,” on page 202. None. This parameter is required for all typed queries, and is not allowed for any packaged query. sortAsc=attribute-name Sort results by attribute-name in ascending order. Sorted by database ID sortDesc=attribute-name Sort results by attribute-name in descending order.
Chapter 9 Using the Query Service Group filter subexpressions with parentheses. Separate grouped subexpressions with a semicolon (no spaces). (attribute1==value1;attribute2!=value2);(attribute3==value3;attribute4!=value4)... For example: https://vcloud.example.com/api/query? type=providerVdcResourcePoolRelation&format=records&filter=(numberOfVMs!=0;isPrimary==true) Attribute Names and Values Several parameters and all filter expressions require you to specify an attribute name.
vCloud API Programming Guide 214 VMware, Inc.
Configuring and Using Blocking Tasks and Notifications 10 vCloud Director allows a system administrator to configure many operations as blocking tasks, which are suspended until a system administrator acts on them or a preconfigured timer expires. Blocking tasks also generate AMQP messages that you can use to automate the handling of the underlying user request. A system administrator can also enable nonblocking AMQP notifications of all system events.
vCloud API Programming Guide Processing Messages from Blocking Tasks Messages from blocking tasks are also sent to the configured message broker, and clients can use the routing key to indicate their interest in these messages. See “Subscribing to Notifications,” on page 215. Messages from blocking tasks contain additional information about the task itself. Clients that process these messages can use the vCloud API to authenticate to the system and act on the blocked task.
Chapter 10 Configuring and Using Blocking Tasks and Notifications 3 Enable or disable notifications. a Retrieve the NotificationsSettings element. Make a GET request to the href value of the application/vnd.vmware.admin.notificationsSettings +xml link. b Modify the value of the EnableNotifications element to enable or disable notifications. c Update the modified element with the new contents. PUT the modified element to the href value of its rel="edit" link. 4 Review or modify system AMQP settings.
vCloud API Programming Guide href="https://vcloud.example.com/api/admin/extension/settings/amqp" ... > 5672 guest amq.
Chapter 10 Configuring and Using Blocking Tasks and Notifications Request: POST https://vcloud.example.com/api/admin/extension/settings/amqp/action/test Content-Type: application/vnd.vmware.admin.amqpSettings+xml ... PAGE 220vCloud API Programming Guide Routing key components include: operationSuccess A Boolean value denoting whether the operation that triggered the notification succeeded or failed. entity The object identifier of the object on which an operation, an event of type com/vmware/vcloud/event/, triggered the notification. For more information about object identifiers, see “Objects, References, and Representations,” on page 11 org The object identifier of the organization that owns the affected object.
Chapter 10 Configuring and Using Blocking Tasks and Notifications name="vdcComposeVapp" id="urn:vcloud:blockingTask:25" /> 2011-06-18T14:33:2
vCloud API Programming Guide Table 10-2. User, Group, Role, and Session Events (Continued) Type (com/vmware/vcloud/event/) Description user/delete A local user was removed from the organization. group/import A group was imported from LDAP. group/remove A group was removed from an organization. role/create A new role was created. role/modify An existing role was modified. role/delete A role was deleted. Table 10-3.
Chapter 10 Configuring and Using Blocking Tasks and Notifications Table 10-4. vApp, vApp Template, Vm, and Media Events (Continued) Type (com/vmware/vcloud/event/) Description vappTemplate/create_request A request to create a vApp template was blocked pending administrative action. vappTemplate/import_request A request to import a vApp template was blocked pending administrative action. vappTemplate/modify_request A request to modify a vApp template was blocked pending administrative action.
vCloud API Programming Guide Table 10-4. vApp, vApp Template, Vm, and Media Events (Continued) Type (com/vmware/vcloud/event/) Description vm/consolidate_request A request to consolidate a virtual machine was blocked pending administrative action. vm/consolidate A virtual machine was consolidated. vm/relocate_request A request to relocate a virtual machine was blocked pending administrative action. vm/relocate A virtual machine was relocated.
Chapter 10 Configuring and Using Blocking Tasks and Notifications Table 10-5. Other System Events (Continued) Type (com/vmware/vcloud/event/) Description datastore/modify One or more properties of a datastore object were modified datastore/delete A datastore object was deleted. Retrieve or Update Blocking Task Settings Timeout settings, default actions, and related messages for blocking tasks are properties of a cloud. They apply to all organizations in the cloud.
vCloud API Programming Guide Request: PUT https://vcloud.example.com/api/admin/extension/settings/blockingTask Content-Type: application/vnd.vmware.admin.blockingTaskSettings+xml ... PAGE 227Chapter 10 Configuring and Using Blocking Tasks and Notifications Table 10-6. Media Operation Name Description vdcCopyMedia Copy a media object. vdcDeleteMedia Delete a media object. vdcUploadMedia Upload media. vdcUpdateMedia Modify one or more properties of a media object. Table 10-7. Network Operation Name Description networkCreateNetworkPool Create a network pool. networkCreateExternalNetwork Create an external network. networkDelete Delete a network.
vCloud API Programming Guide Table 10-9. vApp Template Operation Name Description vdcCopyTemplate Copy a vApp template. vdcDeleteTemplate Delete a vApp template. vdcEnableDownload Enable a vApp template for download as OVF. vdcUpdateTemplate Modify one or more properties of a vApp template. vdcUploadOvfContents Upload an OVF package to create a vApp template. Table 10-10. vDC Operation Name Description rclCreateProviderVdc Create a provider vDC. rclDeleteProviderVdc Delete a provider vDC.
Chapter 10 Configuring and Using Blocking Tasks and Notifications 3 Use one of the action links in the BlockingTask to take action on the task. See the response portion of “Example: Handling a Blocking Task,” on page 230. Example: Retrieve a List of Blocking Tasks Request: GET https://vcloud.example.com/api/admin/extension/blockingTasks/ Response: 200 OK Content-Type: application/vnd.vmware.admin.blockingTaskList+xml ... PAGE 230vCloud API Programming Guide The following actions are allowed: resume Unblock the task and allow it to continue. abort End the task, cleaning up any transient objects that it created. Task status is set to ABORTED. fail End the task, setting the status of any transient objects that it created to ERROR. Task status is set to ERROR. updateProgress Reset the timeout value and timeout action for an active task. Use this action to keep the task alive when it might become subject to a timeout action.
Chapter 10 Configuring and Using Blocking Tasks and Notifications id="urn:vcloud:blockingTask:25" type="application/vnd.vmware.admin.blockingTask+xml" href="https://vcloud.example.com/api/admin/extension/blockingTask/25" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... > PAGE 232vCloud API Programming Guide Extend The Timeout Expiration of an Active Task You can use the updateProgress link in a BlockingTask to extend the expiration time of an active task. Prerequisites Verify that you are logged in as a system administrator. Procedure 1 Retrieve the list of active blocking tasks. See “Monitor Blocking Tasks,” on page 228. If you are using an AMQP client to handle task extension requests, skip this step.
XML Representations in the vCloud API 11 The vCloud API represents objects in a cloud 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. Schema reference information is available as a download.
vCloud API Programming Guide VCloudExtensibleType is an abstract type that all complex types extend that are defined in the vCloud API namespace at http://www.vmware.com/vcloud/v1.5. This type allows you to add custom attributes to any type and supports definition of custom elements within the VCloudExtension element. The VCloudExtension element has an attribute named required that specifies how clients and servers proceed when they see an unknown extension.
Chapter 11 XML Representations in the vCloud API Table 11-1. XML Namespace Identifiers in the vCloud API (Continued) Name Value Requirement xsi:schemaLocati on An installation-dependent schema location search path. See http://www.w3.org/TR/xmlschema-0/. Not required in request bodies. xmlns:xsi http://www.w3.org/2001/XMLSchema-instance Not required in request bodies.
vCloud API Programming Guide Object Identifier, Type, and Reference These attributes are common to all object representations. id The object identifier, expressed in URN format. The value of the id attribute uniquely identifies the object, persists for the life of the object, and is never reused.
Chapter 11 XML Representations in the vCloud API Retrieve an Object as an Entity You can use the vCloud API entity resolver with an object's id attribute value to retrieve a context-free reference to the object. Every first-class object that the vCloud API defines includes an id attribute whose value is the object identifier expressed in URN format. The value of the id attribute uniquely identifies the object, persists for the life of the object, and is never reused.
vCloud API Programming Guide rel="alternate" type="application/vnd.vmware.vcloud.vApp+xml" href="https://vcloud.example.com/api/vApp/vapp-490af534-1491-452e-8ed6-a5eb54447dac" /> 238 VMware, Inc.
Index A administrative tasks, about 109 administrator, system 111 AMQP, about 215 AMQP settings to configure 216 to test 218 API client, to develop 18 attributes custom 93 name 235 status 235 B blocking task, to configure 215 blocking task requests, to monitor 228 blocking task settings, to configure 225 browsing 41 C catalog adding items 70 change owner 73 controlling access to 157 removing items 73 to administer 145 to change owner 109 to create 109, 145 to delete 109 to find 26 to publish 147 to retri
vCloud API Programming Guide to upload or download 54 uploading 67 metadata about 195 to retrieve or modify 196 metadata value, to retrieve or modify 199 to upload or download 53 uploading 55 OVF upload initiating 56 to monitor progress of 62 using ranged PUTs 63 N P network syslog server settings 138 to create, update, or remove 109 to reset 109 to retrieve 41 network pool isolation-backed 185 portgroup-backed 187 to create 183 to retrieve or update 161 VLAN-backed 184 network services, list of 118 Ne
Index to retrieve 109 update progress 232 task list, to retrieve 109 task operations 226 U user to create 109, 148 to import 150 to retrieve 109 to update or remove 109 users, to administer 148 V vApp add virtual machines 83 capturing 70 changing owner 73 composing 80 configuration links in 88 controlling access to 157 datacenter operations 75 importing 70 importing from vCenter 189 list of power operations 77 maintenance mode 86 recompose 83 remove virtual machines 83 to change name or description 54 to
vCloud API Programming Guide to view or modify operating system properties 92 to view or modify virtual disks 92 virtual machines, available for import 171 Vm configuration links in 90 list of power operations 77 pending question 77 to reboot or reset 77 to retrieve 41 vmdk file, to download form template 66 VMware Tools to install 77 to retrieve installed version 77 vSphere, operations 49 vSphere platform, to manage 161 W workflow, example of 23 X XML compressed responses 16 validation of 16 XML namespa
