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-000180-01
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.
Contents
AboutThisBook
11
1 IntroducingtheVMwarevCloudAPI 13
vCloudObjectTaxonomy 13 vCloudOrganizations 13 Objects,References,andRepresentations 15 LinksandLinkRelations 15 vCloudClientWorkflowOverview 17 Requests 17 Responses 18 ConfiguringthevCloudAPIURL 19 RelatedPublications 19 AbouttheExamples 19
2 HellovCloud:AStructuredRESTWorkflowExample 21
LoggingInandGettinganOrganizationList BrowsinganOrganization 22 FindingavAppTemplate 23 GettingInformationAboutavDC 24 InstantiatingtheTemplateinthevDC 24 DeployingandPoweringOnthevApp 26 GettingInformationAboutthevApp 27 DisplayingtheConsole 29 RetrieveaScreenTicket 29 UsetheTicketwithvmwarevmrc 30 DeletingthevApp 30 LoggingOut 30 MovingontoAdditionalUseCases 31 21
3 Browsing 33
SummaryofBrowsingRequests 33 DiscoveringtheContentsofanOrganization,Catalog,orvDC 34 ListtheOrganizationsinavCloud 34 ListtheContentsofanOrganization 34 ListtheContentsofaCatalog 35 GetInformationAboutaCatalogItem 36 ListtheContentsofavDC 37 GettingMoreInformationAboutanObject 38 GetInformationAboutaMediaImage 38 GetInformationAboutavAppTemplate 39 GetInformationAboutavApporVirtualMachine 40 GetInformationAboutaNetwork 40
4 Provisioning 41
SummaryofProvisioningRequests 41 UploadOVFtoCreateavAppTemplate 42
VMware, Inc.
RestrictionsonUploadedContent 43 InitiatetheUpload 43 IncludingaManifest 45 UploadingtheFiles 45 ViewtheOVFDescriptorofavAppTemplate 47 DownloadavAppTemplateasOVF 47 EnableavAppTemplateforDownload 48 DisableavAppTemplateforDownload 49 UploadaMediaImage 50 CopyingandMoving 50 CopyorMoveaMediaImage 51 CopyorMoveavAppTemplate 51 CopyorMoveavApp 52 ChangingaNameorDescription 53 ChangetheNameorDescriptionofavAppTemplate 53 ChangetheNameorDescriptionofavApp 53 ChangetheNameorDescriptionofaMediaImage 54 DeleteavAppTemplate,vApp,orMediaImage 54 CatalogingvAppTemplatesandMediaImages 54 AddanItemtoaCatalog 54 RemoveanItemfromaCatalog 56 CatalogLinksinaVAppTemplateorMediaImage 56 ControllingAccess 56 ControlAccesstoCatalogs 56
5 DatacenterOperations 59
SummaryofDatacenterOperationsRequests 59 vAppLifecycle 60 InstantiateavAppTemplate 61 AboutInstantiationParameters 62 AboutvAppNetworks 62 InstantiatingavAppTemplateUsingDefaultParameters 62 InstantiatingavAppTemplateUsingAdditionalParameters 62 RetrieveorModifytheCustomizationSectionofavAppTemplate 64 ComposeavApp 65 FindingVirtualMachineURLstoUseinaCompositionItem 66 RecomposeavApptoAddorRemoveVirtualMachines 67 CaptureavApptoCreateavAppTemplate 68 ReconfiguringvAppsandVirtualMachines 69 ReconfigureavApp 69 ReconfigureaVirtualMachine 73 DeployingandControllingvAppsandVirtualMachines 80 DeployavApporVirtualMachine 80 UndeployavApporVirtualMachine 81 PowerOnavApporVirtualMachine 81 PowerOffavApporVirtualMachine 82 ResetavApporVirtualMachine 82 SuspendavApporVirtualMachine 83 DiscardtheSuspendedStateofavApporVirtualMachine 83 ShutDownavApporVirtualMachine 84 RebootavApporVirtualMachine 84 ListMediaDevicesofaVirtualMachine 85 InsertMediaIntoaVirtualMachine 85 EjectMediafromaVirtualMachine 86 GetaScreenThumbnailforaVirtualMachine 86
VMware, Inc.
Contents
6 AdministrativeOperations 91
SummaryofAdministrativeRequests 91 AdministratorCredentialsandPrivileges 93 AdministrativeObjectsandURLs 93 GetanAdministrativeViewofaCloud 93 OrganizationAdministration 94 CreateanOrganization 95 GetanAdministrativeViewofanOrganization 96 ListAllTasksOwnedbyanOrganization 97 ModifyanOrganization 97 EnableorDisableanOrganization 98 RemoveanOrganization 99 NetworkAdministration 99 ViewthePropertiesofanExternalNetwork 99 AddaNetworktoanOrganization 100 GetanAdministrativeViewofanOrganizationNetwork 101 ModifyanOrganizationNetwork 101 RemoveanOrganizationNetwork 102 vDCAdministration 102 ExaminetheContentsofaProvidervDC 103 ListtheOrganizationvDCsSupportedbyaProvidervDC 104 AllocateavDCtoanOrganization 104 GetanAdministrativeViewofavDC 106 ModifyavDC 106 EnableorDisableavDC 107 RemoveavDC 107 CatalogAdministration 107 CreateaCatalog 107 GetanAdministrativeViewofaCatalog 108 PublishaCatalog 109 ModifyCatalogMetadata 109 RemoveaCatalog 110 UserAdministration 110 CreateorImportaUser 110 GetanAdministrativeViewofaUser 112 ModifyUserMetadata 112 RemoveaUser 113 GroupAdministration 113 ImportaGroup 113 ViewGroupMetadata 114 ModifyGroupMetadata 114 RemoveaGroup 114 RoleAdministration 114 CreateaRole 114 ViewRoleMetadata 115 ModifyaRole 116 RemoveaRole 116 ViewaRight 116
VMware, Inc.
7 VMwarevSpherePlatformOperations 117
SummaryofvSpherePlatformOperationsRequests 117 ListvSpherePlatformOperationsandObjectsforavCloud 119 ListProvidervDCsinavCloud 120 ListExternalNetworksinavCloud 120 ListNetworkPoolsinavCloud 120 ListvCenterServersRegisteredtoavCloud 120 GetInformationAboutavCenterServer 120 ListAvailableResourcePoolsonavCenterServer 121 ModifyvCenterServerSettings 122 RegisteravCenterServerandvShieldManager 122 UnregisteravCenterServerandvShieldManager 123 ForceReconnectiontoavCenterServer 124 ListESX/ESXiHostsinavCloud 124 GetInformationAboutaHost 124 PrepareaHost 125 UnprepareaHost 126 EnableorDisableaHost 126 RepairaHost 126 UpgradeaHostAgent 127 CreateaProvidervDC 127 ExaminethevSphereObjectsinaProvidervDC 131 ModifyaProvidervDC 131 EnableorDisableaProvidervDC 132 RemoveaProvidervDC 132 CreateanExternalNetwork 133 GetInformationAboutanExternalNetwork 134 ModifyanExternalNetwork 135 RemoveanExternalNetwork 135 CreateaNetworkPool 136 GetInformationAboutaNetworkPool 137 ModifyaNetworkPool 137 RemoveaNetworkPool 138 ImportaVirtualMachinefromvCenter 138 DiscovertheVirtualMachinesinavCenter 138 ImportaVirtualMachineasavApp 139 ImportaVirtualMachineasavAppTemplate 140
VMware, Inc.
Contents
Link 147 APIVersioning 147 SupportedVersions 148 VersionInfo 148 Extensibility 148 VCloudExtension 149
9 UserAPIReference 151
OrgList 151 Org 151 Vdc 152 StorageCapacity 153 ComputeCapacity 153 AvailableNetworks 153 ResourceEntities 154 ResourceEntity 154 OrgNetwork 154 Configuration 155 Catalog 160 CatalogItems 160 CatalogItem 160 Media 161 VAppTemplate 161 Children 162 VApp 162 Vm 163 Section 163 LeaseSettingsSection 164 StartupSection 164 CustomizationSection 164 NetworkConfigSection 165 NetworkConnectionSection 165 VirtualHardwareSection 167 OperatingSystemSection 167 GuestCustomizationSection 167 RasdItemsList 168 ScreenTicket 168 TasksList 168 Tasks 168 Task 168
10 RequestParametersReference 171
UploadVAppTemplateParams 171 InstantiateVAppTemplateParams 172 InstantiationParams 172 ComposeVAppParams 173 Item 173 NetworkAssignment 174 RecomposeVAppParams 174 DeployVAppParams 175 UndeployVAppParams 175 CaptureVAppParams 175 CloneMediaParams 176 CloneVAppTemplateParams 176
VMware, Inc.
CloneVAppParams 176 MediaInsertOrEjectParams 177 VmPendingQuestion 177 VmQuestionAnswer 177 ControlAccessParams 177 AccessSettings 178
11 AdministrativeAPIReference 179
VCloud 179 OrganizationReferences ProviderVdcReferences RightReferences 180 RoleReferences 180 Networks 180 ExternalNetwork 180 AdminOrg 180 Settings 181 Users 185 Groups 185 Catalogs 185 Catalog 186 Vdcs 186 ProviderVdc 186 ComputeCapacity 187 StorageCapacity 188 NetworkPoolReferences NetworkPoolReference VdcReferences 188 AdminVdc 188 AllocationModel 190 User 190 Group 191 Role 191 RightReferences 191 RightReference 191 Right 192 180 180
188 188
12 vSpherePlatformExtensionsReference 193
VMWExtension 193 VMWProviderVdcReferences 194 VMWExternalNetworkReferences 194 VMWNetworkPoolReferences 194 VMWVimServerReferences 194 VMWHostReferences 194 VimServer 194 VmObjectRefsList 195 VimObjectRef 195 ResourcePoolList 196 ResourcePool 196 ShieldManager 196 VMWProviderVdc 197 VMWNetworkPool 198 FencePoolType 198 PortGroupPoolType 198 VlanPoolType 198
8 VMware, Inc.
Contents
VMWExternalNetwork 199 VlanRange 199 VMWHostReferences 199 Host 199 RequestParameters 200 PrepareHostParams 200 RegisterVimServerParams 200 ImportVmAsVAppParams 201 ImportVmAsVAppTemplateParams
201
A OVFandthevCloudAPI 203
AboutOVF 203 AboutOVFPackages 204 AboutOVAFiles 204 HowthevCloudAPIUsesOVF 204 VirtualMachines 204 VirtualDiskFiles 205 Networks 205
B AnIntroductiontoRESTforvCloudAPIUsers 207
HowRESTWorks 207 UsingthevCloudRESTAPI 207 RESTfulWorkflowPatterns 208 ForMoreInformationAboutREST 208
Index 209
VMware, Inc.
10
VMware, Inc.
Revision History
Thisbookisrevisedwitheachreleaseoftheproductorwhennecessary.Arevisedversioncancontainminor ormajorchanges.Table 1summarizesthesignificantchangesineachversionofthisbook. Table 1. Revision History
Revision Date 08MAR11 30AUG10 Description GuestCustomizationSectionnotallowedinInstantiationParams Version1.0
Intended Audience
ThisguideisintendedforsoftwaredeveloperswhoarebuildingVMwareReadyCloudServices,including interactiveclientsofVMwareCloudDirector.ThisguideassumesyouarefamiliarwithRepresentationalState Transfer(REST)andRESTfulprogrammingconventions,theOpenVirtualizationFormatSpecification,and VMwareVirtualmachinetechnology.FamiliaritywithotherwidelydeployedtechnologiessuchasXML, HTTP,andtheWindowsorLinuxoperatingsystemsisalsoassumed.
Document Feedback
VMwarewelcomesyoursuggestionsforimprovingourdocumentation.Sendyourfeedbackto docfeedback@vmware.com.
VMware, Inc.
11
Support Offerings
TofindouthowVMwaresupportofferingscanhelpmeetyourbusinessneeds,goto http://www.vmware.com/support/services.
12
VMware, Inc.
vCloud Organizations
AvCloudcontainsoneormoreorganizations.AvCloudorganizationisaunitofadministrationfora collectionofusers,groups,andcomputingresources.Usersauthenticateattheorganizationlevel,supplying credentialsestablishedbyanorganizationadministratorwhentheuserwascreatedorimported.
vCloud Networks
Anorganizationcanbeprovisionedwithoneormorenetworks.Theseorganizationnetworkscanbe configuredtoprovideservicessuchasDHCP,NAT,andfirewalls.
VMware, Inc.
13
Organization vDC1
vApp vApp template
Catalog 3
Catalogitem em Catalog 2 em em Catalogitem em Catalog 1 em em Catalogitem Catalogitem Catalogitem Catalogitem
Media Media
vDC2
vApp vApp template
Media Media
Network Network
users
groups
TasksList
AnorganizationadministratorspecifieshowresourcesfromaprovidervDCaredistributedtothevDCsinan organization.
vCloud Catalogs
Catalogscontainreferencestovirtualsystemsandmediaimages.Acatalogcanbesharedtomakeitvisibleto othermembersofanorganization,andcanbepublishedtomakeitvisibletootherorganizations.AvCloud systemadministratorspecifieswhichorganizationscanpublishcatalogs,andanorganizationadministrator controlsaccesstocatalogsbyorganizationmembers.
vCloud Tasks
Longrunningoperationsinitiatedbymembersofanorganizationcreatetasks,whicharekeptonthe organizationstaskslist.
14
VMware, Inc.
TherelattributevaluedefinestherelationshipoftheobjectwhoseXMLrepresentationcontainstheLink toatargetobject.TherelationshipalsoindicatestheHTTPrequesttypetousewhenmakingarequest withthehrefattributeofthelink,asshowninTable 11: Table 1-1. Link Relationships and HTTP Request Types
rel Attribute Value add alternate catalogItem controlAccess copy deploy Relation Description addsanitemtothiscontainer alinktoanalternaterepresentationofthisobject alinktothecatalogItemthatcontainsareferencetothisobject. applyaccesscontrols notsupportedinthisrelease deploythisobject HTTP Request POST GET GET POST N/A POST
VMware, Inc.
15
16
Requests
ClientsmakeHTTPrequeststovCloudURLs,hrefattributevalueswhicharetypicallyprovidedbytheserver inresponsetoGETrequestsbytheclient.EveryvCloudhasawellknownURLfromwhichaclientcangetthe serversloginURLandthelistofvCloudAPIversionsthattheserversupports,alongwithadditional information(seeAPIVersioningonpage 147).Afteraclienthasloggedin,allvCloudAPIURLscanbe discoveredbymakingGETrequeststoURLslistedintheloginresponseandtheURLscontainedinresponses tothoserequests.
Request Headers
Allrequestsfromauthenticatedclientsmustincludeanauthenticationheader.SeeAuthenticationon page 18. RequeststhatincludeadocumentbodymuststartwiththeappropriateHTTPContentTypeheader.Thetype attributeofaresponsebodyindicatesthecontenttypeofthedocument.Forexample,thisresponsefragment indicatesthatthecontenttypeassociatedwithaCatalogItem entityis application/vnd.vmware.vcloud.catalogItem+xml.
<CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221" name="Ubuntu Template with vsftpd"/>
AnyrequestthatincludesaCatalogItemrequiresthefollowingContentTypeheader:
Content-Type: application/vnd.vmware.vcloud.catalogItem+xml
Request Bodies
ThisreleaseofCloudDirectorusesavalidatingXMLparserthatrequireselementsinarequestbodytoagree inbothorderandnumberwiththeschema.Requestbodiesarerejectedasinvalidunlesstheymeetthe followingcriteria:
VMware, Inc.
17
Authentication
HTTPcommunicationsbetweenavCloudclientandserveraretypicallysecuredwithSSL.Inaddition,the vCloudAPIimplementsBasicHTTPAuthentication,asdefinedbyRFC2617,whichenablesaclienttoobtain atokenthatitcanusetoauthenticateindividualHTTPrequests. Toobtainanduseanauthenticationtoken,aclientmustfirstdiscovertheserversloginURL,andthenPOST aloginrequesttothatURL,supplyingthecredentialsofanauthorizeduser. To obtain and use an authentication token 1 2 MakeanAPIversionrequesttoavCloudservicetoobtaintheloginURLforthatservice.Formore information,seeAPIVersioningonpage 147. MakeanHTTPPOSTrequesttotheloginURL,asshowninExample 21onpage 21.
Responses
AllresponsesincludeanHTTPstatuscodeand,unlessthestatuscodeis204(NoContent),aContentType header.Responsecontentdependsontherequest.Someresponsesincludeadocumentbody,someinclude onlyaURL,andsomeareempty.
Status Codes
Table 12liststhesubsetofHTTPstatuscodesthatavCloudAPIclientcanexpectinaresponse. Table 1-2. HTTP Status Codes Returned by the vCloud API
Status Code 200OK 201Created 202Accepted 204NoContent 303SeeOther 400BadRequest Status Description Therequestisvalidandwascompleted.Theresponseincludesadocumentbody. Therequestisvalid.TherequestedobjectwascreatedandcanbefoundattheURLspecifiedin theLocationheader. Therequestisvalidandataskwascreatedtohandleit.Thisresponseisusuallyaccompanied byataskURL. Therequestisvalidandwascompleted.Theresponsedoesnotincludeabody. TheresponsetotherequestcanbefoundattheURLspecifiedintheLocationheader. Therequestbodyismalformed,incomplete,orotherwiseinvalid.
18
VMware, Inc.
Table 1-2. HTTP Status Codes Returned by the vCloud API (Continued)
Status Code 401Unauthorized 403Forbidden 404NotFound 405MethodNot Allowed 500InternalServer Error 501NotImplemented 503Service Unavailable Status Description Anauthorizationheaderwasexpectedbutnotfound. Therequestinguserdoesnothaveadequateprivilegestoaccessoneormoreobjectsspecified intherequest. Oneormoreobjectsspecifiedintherequestcouldnotbefoundinthespecifiedcontainer. TheHTTPmethodspecifiedintherequestisnotsupportedforthisobject. Therequestwasreceivedbutcouldnotbecompletedduetoaninternalerrorattheserver. Therequestisnotimplementedbytheserver. Oneormoreservicesneededtocompletetherequestarenotavailableontheserver.
Related Publications
TheVMwareCloudDirectorAdministratorsGuideandVMwareCloudDirectorUsersGuidecontaindetailed informationaboutmanyoftheobjectsandoperationsreferredtointhisguide.MostusersofthevCloudAPI willfindtheinformationinthosedocumentsvaluablewhendevelopingclientapplications.Toaccessthe currentversionsoftheseandotherVMwarebooks,gotohttp://www.vmware.com/support/pubs.
VMware, Inc.
19
20
VMware, Inc.
Response:
200 OK Date: request-date x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM= Content-Type: application/vnd.vmware.vcloud.orgList+xml ... <?xml version="1.0" encoding="UTF-8"?> <OrgList ... href="http://vcloud.example.com/api/v1.0/org/" ... > <Org type="application/vnd.vmware.vcloud.org+xml" name="ExampleOrg" href="http://vcloud.example.com/api/v1.0/org/5"/>
VMware, Inc.
21
Theresponseincludesanauthenticationtokensuppliedinthe x-vcloud-authorizationheader,andalist oftheorganizationstowhichtheauthenticateduserhasaccess.EachOrghasaURL(initshrefattribute value)thattheclientcanusetogetmoreinformationaboutobjectsthattheorganizationcontains.Formore informationaboutauthentication,seeAuthenticationonpage 18. NOTEThisexample,likeotherexamplesinthisguide,omitscertainrequiredHTTPheadersandothercontent sothatitcanprovideaconcise,readablesubsetofanactualrequestandresponse.Formoreinformation,see AbouttheExamplesonpage 19.
Browsing an Organization
YoucanuseanHTTPGETrequestandoneoftheOrgURLsreturnedbytheloginrequesttodiscoverthe contentsofanorganization,asshowninExample 22.(Foramorecompleteversionofthisexample,see Example 31onpage 34.) Example 2-2. List the Contents of an Organization Request:
GET http://vcloud.example.com/api/v1.0/org/5
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.org+xml ... <Org name="ExampleOrg" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/5" ... > <Link ... /> <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32" name="MainCatalog"/> <Link ... /> <Link rel="down" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5" name="ExampleVdc01"/> <Link ... /> <Link rel="down" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/14" name="IsolatedOrgNet"/> <Link rel="down" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/54" name="Internet"/> <Description>Example Corps Primary Organization</Description> </Org>
22
VMware, Inc.
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.catalog+xml ... <Catalog name="MainCatalog" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32" ...> ... <Description>Main Org Catalog</Description> <CatalogItems> ... <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu Template with vsftpd" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/> ... </CatalogItems> ... </Catalog>
EveryvApptemplateormediaimagethathasbeenaddedtothecatalogisrepresentedasaCatalogItem element.Whenaclientbrowsesacatalog,itcanreadonlythename,type,andhrefofeachCatalogItem.To retrieveanitemfromthecatalog,moreinformationisrequired.InExample 24,theclientmakesaGETrequest toaCatalogItemURL(itshrefvalue).Theresponseprovidesmoreinformation,includingadescriptionof thereferencedobjectandanotherURLthattheclientcanusetoretrievearepresentationoftheobject. Example 2-4. Getting the vApp Template URL From a CatalogItem Request:
GET http://vcloud.example.com/api/v1.0/catalogItem/221
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.catalogItem+xml ... <CatalogItem name="Ubuntu Template with vsftpd" href="http://vcloud.example.com/api/v1.0/catalogItem/221" ...> ... <Description>Ubuntu Template with vsftpd</Description> <Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/> ... </CatalogItem>
ThisresponseshowsthatasuitablevApptemplatecanbefoundat http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate111.
VMware, Inc.
23
TheURLthataclientcanusetorequestaninstantiateVAppTemplateoperationinthevDC AlistofnetworkstowhichthevAppcanconnect.
Example 25showsthissubsetofvDCcontents.(Foramorecompletelookatthosecontents,seeExample 34 onpage 37.) Example 2-5. List the Contents of a vDC Request:
GET http://vcloud.example.com/api/v1.0/vdc/5
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.vdc+xml ... <Vdc name="ExampleVdc01" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5" ...> ... <Link rel="add" type="application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate" /> ... <AvailableNetworks> <Network href="http://vcloud.example.com/api/v1.0/network/14" type="application/vnd.vmware.vcloud.network+xml" name="IsolatedOrgNet"/> <Network href="http://vcloud.example.com/api/v1.0/network/54" type="application/vnd.vmware.vcloud.network+xml" name="Internet"/> </AvailableNetworks> ... </Vdc>
Theinformationyouneedisavailablehereintwoplaces:
BoththesepiecesofinformationareputtouseinExample 26.
24
VMware, Inc.
TheinstantiateVAppTemplaterequestinExample 26suppliestheseparametersinthefollowingplaces:
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml <VApp deployed=false status="0" name="Linux FTP server" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Description>Example FTP Server vApp</Description> <Tasks>
VMware, Inc.
25
<Task status="running" startTime="2010-06-25T08:00:55.402-07:00" operation="Creating Virtual Application Linux FTP server(7)" expiryTime="2010-09-23T08:00:55.402-07:00" type="application/vnd.vmware.vcloud.task+xml" href="http://vcloud.example.com/api/v1.0/task/1awvdrn82atz7yzsdey"> <Owner type="application/vnd.vmware.vcloud.vApp+xml" name="LinuxFtpServer" href="http://vcloud.example.com/vApp/vapp-7"/> </Task> </Tasks> </VApp>
Response:
202 Accepted <Task xmlns="http://www.vmware.com/vcloud/v1" status="running" startTime="2010-06-25T11:15:55.558-07:00" operation="Starting Virtual Application Linux FTP server(7)" expiryTime="2010-09-23T08:00:55.402-07:00" type="application/vnd.vmware.vcloud.task+xml" href="http://vcloud.example.com/api/v1.0/task/i9h1djqzsyllf0zvdy" ...> <Owner type="application/vnd.vmware.vcloud.vApp+xml" name="LinuxFtpServer" href="http://vcloud.example.com/vApp/vapp-7"/> </Task>
Becausedeploymentisalongrunningoperationthatcanfailforavarietyofreasons(inabilityofthevDCto satisfythevAppsresourcerequirements,forexample),theresponseisaTask.
26
VMware, Inc.
ThevAppisdeployed(itsdeployedattributeissettotrue)andpoweredon(status="4"). TheVminitsChildrencollectionisalsopoweredonanddeployed.TheVmisconnectedtothevApp networkcreatedduringinstantiation(seeExample 26).Propertiesofthisnetworkareincludedinthe NetworkConfigSectionofthevApp,thoughmostarenotshownhere. ActionlinksforalloperationsexceptpowerOnarepresentinboththevAppitselfanditschildVm.Because thevAppisalreadypoweredon,thatoperationisinvalidforthevAppinitscurrentstate,sothelinkis notpartoftheresponse.(Thelinkfordeployisalwayspresent,eveninadeployedvApp,becausethe deployactionisalwaysvalid.)TheVmelementalsoincludesseverallinksforactionsthatnotapplicable toavApp:actionslikeacquiringascreenticketorthumbnail,andinsertingorremovingmedia,are specifictoavirtualmachine.Otheractionslikeshutdownandreboot,canbeappliedtoeitherobject.See DeployingandControllingvAppsandVirtualMachinesonpage 80. Muchadditionalinformationisavailable,thoughmostofitisnotshownhere.Theexampledoesshow wheretofindtheIPaddressofthevApp,intheIpAddresselementoftheNetworkConnection.
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="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ... > <Link rel="power:reboot" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/reboot"/> <Link rel="power:powerOff" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/powerOff"/> <Link rel="undeploy" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/undeploy"/> <Link rel="deploy" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/deploy"/> <Link rel="power:shutdown" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/shutdown"/> <Link rel="power:reset" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/reset"/> <Link rel="power:suspend" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/power/action/suspend"/> <Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/controlAccess/"/> <Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/action/controlAccess/"/> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Link rel="edit" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7"/> <Description>Example FTP Server vApp</Description> <LeaseSettingsSection ...> ... </LeaseSettingsSection> <ovf:StartupSection ... > ...
VMware, Inc.
27
</ovf:StartupSection> <ovf:NetworkSection ... > <ovf:Info/> <ovf:Network ovf:name="vAppNetwork"> <ovf:Description/> </ovf:Network> </ovf:NetworkSection> <NetworkConfigSection href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/" ovf:required="false"> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConfigSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/ networkConfigSection/"/> <ovf:Info>Configuration parameters for vAppNetwork</ovf:Info> <NetworkConfig networkName="vAppNetwork"> <Configuration> <IpScope> ... </IpScope> <ParentNetwork type="application/vnd.vmware.vcloud.network+xml" name="Internet" href="http://vcloud.example.com/api/v1.0/network/54"/> <FenceMode>bridged</FenceMode> </Configuration> <IsDeployed>true</IsDeployed> </NetworkConfig> </NetworkConfigSection> <Children> <Vm deployed="true" status="4" name="ubuntu10-x86" type="application/vnd.vmware.vcloud.vm+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4"> <Link rel="power:reboot" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/ action/reboot"/> <Link rel="power:powerOff" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/ action/powerOff"/> <Link rel="undeploy" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/action/undeploy"/> <Link rel="deploy" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/action/deploy"/> <Link rel="power:shutdown" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/ action/shutdown"/> <Link rel="power:reset" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/ action/reset"/> <Link rel="power:suspend" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/ action/suspend"/> <Link rel="up" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7"/> <Link rel="screen:thumbnail" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/screen"/> <Link rel="screen:acquireTicket" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/screen/ action/acquireTicket"/> <Link rel="media:insertMedia" type="application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/media/ action/insertMedia"/> <Link rel="media:ejectMedia" type="application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/media/ action/ejectMedia"/> <Description/> <ovf:VirtualHardwareSection ...> ... </ovf:VirtualHardwareSection> ... <NetworkConnectionSection> ... <NetworkConnection network="vAppNetwork"> ...
28
VMware, Inc.
<IpAddress>10.147.122.134</IpAddress> <IsConnected>true</IsConnected> <MACAddress>00:50:56:01:01:49</MACAddress> ... </NetworkConnection> ... </NetworkConnectionSection> <GuestCustomizationSection ...> ... </GuestCustomizationSection> <VAppScopedLocalId>20ea086f-1a6a-4fb2-8e2e-23372facf7de</VAppScopedLocalId> </Vm> </Children> </VApp>
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.screenTicket+xml ... <ScreenTicket xmlns="http://www.vmware.com/vcloud/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1 ...> mks://10.147.43.171/vm-61?ticket=Pznh4HMb7k%2FlniSLwyAD1fmlPIXOuSACKgEReF7ylTIn4qRkxhFv9QT7I3 SLTAQu%2F7W5RxVpDxjVKuuHQ4VIwu59F%2FG1WL1OmYMWistJC9tkRjQ1RRQiB1Oem5E7qX9O </ScreenTicket>
Theticketitselfhasthefollowingform:
mks://ip-address/VM-MoRef/ticket=encoded-ticket
where:
Theticketisvalidfor30seconds.
VMware, Inc.
29
FortheticketshowninExample 29,thecommandlinewouldlooksimilartothisone.
vmware-vmrc -h 10.147.43.171 -p 9XVUXZ... -M vm-61
Response:
202 Accepted <Task xmlns="http://www.vmware.com/vcloud/v1" status="running" startTime="2010-06-25T08:10:23.650-07:00" operation="Deleting Virtual Application Linux FTP server (7)" expiryTime="2010-09-23T08:00:55.402-07:00" type="application/vnd.vmware.vcloud.task+xml" href="http://vcloud.example.com/api/v1.0/task/jul1tndoojgaesymci" ... > <Owner type="application/vnd.vmware.vcloud.vApp+xml" name="Linux FTP server" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7"/> </Task>
Logging Out
Tologoutandendasession,avCloudAPIclientmakesaPOSTrequesttothelogoutURL,asshownin Example 211. Example 2-11. Log Out Request:
POST http://vcloud.example.com/api/v1.0/logout x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM=
Response:
200 OK
30
VMware, Inc.
CreatingvApptemplatesbyuploadingOVFpackagesorcapturingvApps(Provisioningonpage 41) Nondefaultinstantiationusingdetailedinstantiationparameters(InstantiateavAppTemplateon page 61) CreatingacopyofavAppbycloning,orcomposingavAppfrommultiplevAppsortemplates ReconfigurationofavApptoaddorremovevirtualhardware,modifynetworkconnections,andchange othervAppproperties(ReconfiguringvAppsandVirtualMachinesonpage 69) AdministrativeoperationstocreatevDCsandCatalogs,andtoadministerusers,groups,androles (AdministrativeOperationsonpage 91). OperationsthatasystemadministratorcanusetoaccessthevSphereplatformthatsupportsavCloud roles(VMwarevSpherePlatformOperationsonpage 117).
ThisguidealsoincludescompletereferenceinformationonXMLelementsdefinedbythevCloudAPI(see Chapter 9,UserAPIReference,onpage 151andChapter 11,AdministrativeAPIReference,onpage 179), andthosedefinedbythevSphereplatformextensions(seeChapter 12,vSpherePlatformExtensions Reference,onpage 193).ItalsoincludesanintroductiontoOVFAppendix A,OVFandthevCloudAPI,on page 203,whichconcentratesonthoseaspectsofOVFthatmightbeofinteresttoadvancedvCloudAPI programmers.
VMware, Inc.
31
32
VMware, Inc.
Browsing
APIURLisaURLoftheformhttp://vcloud.example.com/api/v1.0 idisaninteger
VMware, Inc.
33
Formoreinformation,seeLoggingInandGettinganOrganizationListonpage 21.
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.org+xml ... <Org name="ExampleOrg" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/5" ...> <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32" name="MainCatalog"/> <Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/controlAccess/"/> <Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/action/controlAccess/"/> <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/37" name="Shared Catalog"/> <Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/catalog/37/controlAccess/"/> <Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml" href="http://vcloud.example.com/api/v1.0/catalog/37/action/controlAccess/"/> <Link rel="down" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5" name="ExampleVdc01"/> <Link rel="down" type="application/vnd.vmware.vcloud.tasksList+xml" href="http://vcloud.example.com/api/v1.0/tasksList/5"/>
34
VMware, Inc.
Chapter 3 Browsing
<Link rel="down" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/14" name="IsolatedOrgNet"/> <Link rel="down" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/54" name="Internet"/> <Description>Example Corps Primary Organization</Description> </Org>
Thisresponseshowsthattheorganizationcontainstheseobjects,eachofwhichisreferencedbyaLinkwhose relattributehasavalueofdown(indicatingthatthelinkreferencesanobjectcontainedbytheorganization):
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.catalog+xml ... <Catalog name="MainCatalog" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32" ...> <Link rel="up" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/5"/> <Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/catalogItems"/> <Description>Main Org Catalog</Description> <CatalogItems> <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu Template with vsftpd" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/> <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu Boot Floppy" href="http://vcloud.example.com/api/v1.0/catalogItem/222"/> <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="Ubuntu ISO Image" href="http://vcloud.example.com/api/v1.0/catalogItem/223"/> ... </CatalogItems> <IsPublished>true</IsPublished> </Catalog>
VMware, Inc.
35
Thisresponsebodyincludes:
ALinkelementthatreferencestheorganizationthatcontainsthiscatalog:
<Link rel="up" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/5"/>
ALinkelementthatyoucanusetoaddanitemtothecatalog:
<Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/catalogItems"/>
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.catalogItem+xml ... <CatalogItem name="Ubuntu Template with vsftpd" href="http://vcloud.example.com/api/v1.0/catalogItem/221" ...> <Link rel="edit" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/> <Description>Ubuntu Template with vsftpd</Description> <Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/> <Property key="Company">Example</Property> </CatalogItem>
36
VMware, Inc.
Chapter 3 Browsing
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.vdc+xml ... <Vdc name="ExampleVdc01" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5" ...> <Link rel="up" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/5"/> <Link rel="add" type="application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/uploadVAppTemplate"/> <Link rel="add" type="application/vnd.vmware.vcloud.media+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/media"/> <Link rel="add" type="application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate" /> <Link rel="add" type="application/vnd.vmware.vcloud.cloneVAppParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/cloneVApp"/> <Link rel="add" type="application/vnd.vmware.vcloud.captureVAppParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/captureVApp"/> <Link rel="add" type="application/vnd.vmware.vcloud.composeVAppParams+xml" href="http://vcloud.example.com/api/v1.0/vdc/5/action/composeVApp"/> <AllocationModel>AllocationPool</AllocationModel> <Description>Example Corp. Primary vDC</Description> <StorageCapacity> <Units>MB</Units> <Allocated>1000</Allocated> <Limit>1000</Limit> <Used>512</Used> <Overhead>0</Overhead> </StorageCapacity> <ComputeCapacity> <Cpu> <Units>MHz</Units> <Allocated>100</Allocated> <Limit>100</Limit> <Used>32</Used> <Overhead>0</Overhead> </Cpu> <Memory> <Units>MB</Units> <Allocated>100</Allocated> <Limit>100</Limit> <Used>64</Used> <Overhead>0</Overhead> </Memory> </ComputeCapacity> <ResourceEntities> <ResourceEntity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/> <ResourceEntity href="http://vcloud.example.com/api/v1.0/media/112" type="application/vnd.vmware.vcloud.media+xml" name="Ubuntu Boot Floppy"/> <ResourceEntity href="http://vcloud.example.com/api/v1.0/media/113" type="application/vnd.vmware.vcloud.media+xml" name="Ubuntu ISO Image"/>
VMware, Inc.
37
<ResourceEntity href="http://vcloud.example.com/vApp/vapp-413" type="application/vnd.vmware.vcloud.vApp+xml" name="Example Corp. CRM"/> ... </ResourceEntities> <AvailableNetworks> <Network href="http://vcloud.example.com/api/v1.0/network/14" type="application/vnd.vmware.vcloud.network+xml" name="IsolatedOrgNet"/> <Network href="http://vcloud.example.com/api/v1.0/network/54" type="application/vnd.vmware.vcloud.network+xml" name="Internet"/> </AvailableNetworks> <NicQuota>0</NicQuota> <NetworkQuota>0</NetworkQuota> <VmQuota>0</VmQuota> <IsEnabled>true</IsEnabled> </Vdc>
TheresponseisadetaileddescriptionofthevDCanditscontents.Itincludes:
Formoreinformation,seeVdconpage 152.
Chapter 3 Browsing
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.media+xml ... <Media xmlns="http://www.vmware.com/vcloud/v1" size="242131" imageType="iso" status="1" name="sql2000.iso" type="application/vnd.vmware.vcloud.media+xml" href="http://vcloud.example.com/api/v1.0/media/254" ... > <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/21"/> <Link rel="catalogItem" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/211"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/media/123"/> <Link rel="edit" type="application/vnd.vmware.vcloud.media+xml" href="http://vcloud.example.com/api/v1.0/media/123"/> <Description>ISO Database Image</Description> </Media>
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate ovfDescriptorUploaded="true" status="8" name="Ubuntu Template with vsftpd" type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111" ... > <Description>Description of Ubuntu Template with vsftpd</Description> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/10"/> <Link rel="catalogItem" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/> <Link rel="edit" type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/> <Link rel="ovf" type="text/xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111/ovf"/> <Children> ... </Children> </VAppTemplate>
VMware, Inc.
39
Response:
200 OK Content-Type: application/vnd.vmware.admin.network+xml ... <OrgNetwork xmlns="http://www.vmware.com/vcloud/v1" name="Internet" type="application/vnd.vmware.admin.network+xml" ref="http://vcloud.example.com/api/v1.0/admin/network/54" ...> <Link rel="alternate" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/54"/> <Link rel="edit" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/54"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/network/54"/> <Link rel="up" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0//org/26"/> <Description>Bridged to the Public Internet</Description> <Configuration> <IpScope> <IsInherited>true</IsInherited> <Gateway>10.147.56.253</Gateway> <Netmask>255.255.255.0</Netmask> <Dns1>10.147.115.1</Dns1> <Dns2>10.147.115.2</Dns2> <DnsSuffix>example.com</DnsSuffix> <IpRanges> <IpRange> <StartAddress>10.147.56.1</StartAddress> <EndAddress>10.147.56.255</EndAddress> </IpRange> </IpRanges> </IpScope> <ParentNetwork type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1" href="http://vcloud.example.com/api/v1.0/admin/network/7"/> <FenceMode>bridged</FenceMode> </Configuration> </OrgNetwork>
40
VMware, Inc.
Provisioning
ThevCloudAPIsupportsuploadanddownloadofOVFpackages,anduploadofmediaimages.Transfer operationsarecharacterizedasuploadswhentheoperationtransferscontentfromthelocalhosttoaremote one,andasdownloadswhenthelocalhostrequeststhetransferofcontentfromaremotehost.Uploadsare typicallyinitiatedbyaPOSTrequest,anddownloadsbyaGETrequest.Uploadsanddownloadsare facilitatedbythevCloudtransferservice,whichprovidestemporarystorageforfiles. ThevCloudAPIalsosupportsacloneoperationthatcopiesvApps,vApptemplates,ormediaimages.The cloneoperationalsoallowsyoutospecifythatthesourceobjectbedeletedaftertheoperationcompletes, whicheffectivelymovesorrenamesthesourceobject. Aftertheyhavebeenuploadedorcloned,templatesandmediaimagescanbeaddedtocatalogsasneeded. Thischapterincludesthefollowingtopics:
SummaryofProvisioningRequestsonpage 41 UploadOVFtoCreateavAppTemplateonpage 42 ViewtheOVFDescriptorofavAppTemplateonpage 47 DownloadavAppTemplateasOVFonpage 47 UploadaMediaImageonpage 50 CopyingandMovingonpage 50 ChangingaNameorDescriptiononpage 53 DeleteavAppTemplate,vApp,orMediaImageonpage 54 CatalogingvAppTemplatesandMediaImagesonpage 54 ControllingAccessonpage 56
APIURLisaURLoftheformhttp://vcloud.example.com/api/v1.0. idisaninteger.
VMware, Inc.
41
PUTAPIURL/vApp/vappid PUTAPIURL/media/id
VApp Media
Task Task
5 6
42
VMware, Inc.
Chapter 4 Provisioning
ThisrequestcreatesanewVAppTemplateobjectinthetargetvDCandreturnstheobjectsXMLrepresentation inaresponse,asshowninExample 42. Example 4-2. Unresolved vAppTemplate Body with Upload URL for OVF Descriptor
201 Created Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml <VAppTemplate name="Ubuntu Template" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268" status="0" ovfDescriptorUploaded="false" type="application/vnd.vmware.vcloud.vAppTemplate+xml" ... > <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> ... <Description>Ubuntu vApp Template</Description> <Files> <File name="descriptor.ovf" bytesTransferred="0"> <Link rel="upload:default" href="http://vcloud.example.com/transfer/.../descriptor.ovf"/> </File> </Files> </VAppTemplate>
VMware, Inc.
43
Theresponsebodyincludesthefollowingattributes:
ItalsoincludesaFileelementwithanuploadURL(rel="upload:default")fortheOVFdescriptor.The nameattributeofthisFileelementhasbeencreatedbytheserverandspecifiesacontainerthattheserverhas createdtoreceivethecontentsofthedescriptor.Ithasnorelationtothefilenameofthedescriptorinthe clientsfilesystem. TheclientuploadstheOVFdescriptorbymakingaPUTrequesttotheuploadURL,andsupplyingthe descriptorscontentsasanEnvelopeelementintherequestbody.Theserverrespondswitha200OKstatus, asshowninExample 43. Example 4-3. Upload OVF Descriptor Request:
PUT http://vcloud.example.com/transfer/.../descriptor.ovf Content-Type text/xml ... <Envelope ... > ... </Envelope>
Response:
200 OK
Afterthedescriptorisuploaded,theservervalidatesitand,ifitisvalid,createsuploadURLsforeachofthe filesitreferences.Totracktheprogressofthisoperation,theclientcanmakeperiodicGETrequeststothe vAppTemplateURL.Whentheoperationiscomplete,theresponsetothiskindofrequestincludesadditional Fileelementsbeyondtheonealreadycreatedforthedescriptor,asshowninExample 44. Example 4-4. GET vAppTemplate with Upload URLs Request:
GET http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate ovfDescriptorUploaded="true" status="0" name="Ubuntu Template" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268" type="application/vnd.vmware.vcloud.vAppTemplate+xml" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> ... <Description>Ubuntu vApp Template</Description> <Files> <File size="3940" bytesTransferred="3940" name="descriptor.ovf"> <Link rel="upload:default" href="http://vcloud.example.com/transfer/.../descriptor.ovf"/> </File>
44
VMware, Inc.
Chapter 4 Provisioning
<File size="1950489088" bytesTransferred="0" name="disk0.vmdk"> <Link rel="upload:default" href="http://vcloud.example.com/transfer/.../disk0.vmdk"/> </File> </Files> </VAppTemplate>
Including a Manifest
SomeOVFpackagesincludeamanifestdocument,whichspecifiesachecksumforeachfileinthepackage.If youareuploadingapackagethatincludesamanifestfile,addamanifestRequired="true"attributetothe requestbody,asshowninExample 45. Example 4-5. uploadVappTemplate Request for an OVF Package That Includes a Manifest
POST http://vcloud.example.com/api/v1.0/vdc/5/action/uploadVAppTemplate Content-Type: application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml <UploadVAppTemplateParams name="Ubuntu Template" manifestRequired="true" xmlns="http://www.vmware.com/vcloud/v1" > <Description>Ubuntu vApp Template</Description> </UploadVAppTemplateParams>
VMware, Inc.
45
Tomonitortheprogressofanupload,aclientcanuseanHTTPGETrequestspecifyingtheVAppTemplate URLthatwasreturnedintheuploadmap.Theresponseisthesameuploadmap.Afterallthefileshavebeen uploaded,theresponseincludesaTaskthatthevAppTemplatecreatestomonitortheeventsleadinguptoits resolution,andanupdatedvalueforthebytesTransferredattributeofeachFileelement,asshownin Example 47.(ThecompleteVAppTemplatebodyisreturned.Thisexampleomitsmostofitforclarity.) Example 4-7. Monitoring the Progress of an Upload Request:
GET http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268
Response:
200 OK <VAppTemplate name="Ubuntu Template" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268" status="0" ... > ... <Files> ... <File size="1950489088" bytesTransferred="500000000" name="disk0.vmdk"> <Link rel="upload:default" href="http://vcloud.example.com/transfer/.../disk0.vmdk"/> </File> </Files> ... </VAppTemplate>
Iftheresponsetoanuploadprogressrequestindicatesthattheuploadterminatedbeforeitwascomplete(for example,ifrepeatedprogressrequestsshowthesamebytesTransferredvalue),aclientcanusethesize andbytesTransferredvaluesfromtheresponsetoconstructarangedPUToftheremainingcontents,as showninExample 48. NOTERangedPUTrequestsaretypicallyrequiredforverylargeuploads,especiallywhennetwork bandwidthorlatencycouldcausetheoperationtotimeout. Example 4-8. Ranged PUT to Complete a Partial Upload Request:
PUT http://vcloud.example.com/transfer/.../disk0.vmdkk Content-Range: bytes 500000000-1950489087/1950489088 Content-length: 1450489088
...serializedcontentsofspecifiedrange... EOF
46
VMware, Inc.
Chapter 4 Provisioning
Response:
200 OK
AGETrequestspecifyingtheURLinthehrefvalueofthisLinkreturnsthedescriptor,asshownin Example 49.OnlyresolvedVAppTemplateelementsincludethislink.TogettheOVFdescriptorthatdefines avApporvirtualmachine,youmuststartwiththetemplatefromwhichitwascreated. WhenyouviewtheOVFdescriptorofavApptemplate,itincludesdeploymentspecificinformation. Example 4-9. View the OVF Descriptor of a vApp Template Request:
GET http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268/ovf
Response:
200 OK Content-Type text/xml ... <Envelope ...> <DiskSection> <Info>Virtual disk information</Info> <Disk ovf:capacity="100" ovf:capacityAllocationUnits="byte * 2^20" ovf:diskId="vmdisk1" ovf:fileRef="file1" ovf:format="http://www.vmware.com/interfaces/specifications/ vmdk.html#streamOptimized"/> </DiskSection> <VirtualSystem ... ovf:id="Ubuntu Template"> ... </VirtualSystem> </Envelope>
NOTETheOVFdescriptordoesnotincludeanyFilereferences.Theseareremovedbytheserverafterthe templateisresolvedandrecreatedwhenthetemplateisenabledfordownload.
VMware, Inc.
47
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Enabling download of Virtual Application Template Ubuntu Template (268)" ... > ... </Task>
WhentheenableDownloadtaskcompletes,thetemplatesfilesareavailablefromthevCloudtransferservice, andthevAppTemplateincludesaLinkelementthatcontainsaURLfromwhichthetemplatesOVFdescriptor canbedownloaded,asshowninExample 411. Example 4-11. vApp Template with DownloadURL for OVF Descriptor Request:
GET http://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" type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-268" ...> ... <Link type="text/xml" rel="download:default" href="http://vcloud.example.com/transfer/.../descriptor.ovf"/> ... </VAppTemplate>
Theclientusesthisdownload:defaultURLinaGETrequestthatdownloadstheOVFdescriptor(asshown inExample 412),thenexaminesthecontentsofthedescriptortodiscoverthehrefvaluesfortheremaining filesinthetemplatesReferencescontainer. Example 4-12. Downloading the OVF Descriptor Request:
GET http://vcloud.example.com/transfer/..../descriptor.ovf
Response:
200 OK ... <Envelope ...> <References> <File ovf:href="disk0.vmdk" ovf:id="file1" ovf:size="1950489088"/> </References> <DiskSection> <Info>Virtual disk information</Info>
48
VMware, Inc.
Chapter 4 Provisioning
<Disk ovf:capacity="100" ovf:capacityAllocationUnits="byte * 2^20" ovf:diskId="vmdisk1" ovf:fileRef="file1" ovf:format="http://www.vmware.com/interfaces/specifications/ vmdk.html#streamOptimized"/> </DiskSection> <VirtualSystem ... ovf:id="Ubuntu Template"> ... </VirtualSystem> </Envelope>
Inthisexample,thedescriptorreferencesonlyonefile:
<File ovf:href="disk0.vmdk" ovf:id="file1" ovf:size="1950489088"/>
Theresultofthisprocess,usingtheresponsesinExample 411andExample 412,istherequestURLshown inExample 413. Example 4-13. Downloading a Referenced File Request:
GET http://vcloud.example.com/transfer/..../disk0.vmdk
Response:
200 OK ...
...serializedcontentsoffiledisk0.vmdk... EOF
Response:
204 No Content
VMware, Inc.
49
AfterthedisableDownloadrequestcompletes,thetemplatesfilesareremovedfromthetransferserver,and theLinkelementthatcontainsthedownload:defaultURLnolongerappearsinthevAppTemplatebody.
TheserverreturnsaMediarepresentationthatincludesasingleFileelement,asshowninExample 416.The clientrespondswithaPUTrequest,sendingserializedfiledatatotheFileelementsupload:defaultURL. Example 46showsasimilarrequest. Example 4-16. Server Response to Request to Upload an ISO Image
Content-Type: application/vnd.vmware.vcloud.media+xml 201 Created <Media name="database.iso" size="242131" status="0" imageType="iso" href="http://vcloud.example.com/api/v1.0/media/254" type="application/vnd.vmware.vcloud.media+xml" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Description>ISO database image</Description> <Files> <File name="database.iso" size="242131" bytesTransferred="0" <Link rel="upload:default" href="http://vcloud.example.com/.../database.iso"/> </File> </Files> </Media>
50
VMware, Inc.
Chapter 4 Provisioning
Response:
201 Created ... <Media name="database-backup.iso" size="242131" status="0" imageType="iso" href="http://vcloud.example.com/api/v1.0/media/277" type="application/vnd.vmware.vcloud.media+xml" ...> <Link rel="up" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Description>This is a backup copy of the ISO database image</Description> <Tasks> <Task ... operation="Busy Media File cloned(277)" ... > ... </Task> </Tasks> </Media>
VMware, Inc.
51
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate ovfDescriptorUploaded="true" status="0" name="Ubuntu Copy" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-302" type="application/vnd.vmware.vcloud.vAppTemplate+xml" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> ... <Tasks> <Task ... operation="Busy Virtual Application Template Ubuntu Copy (382)" ...> ... </Task> </Tasks> </VAppTemplate>
52
VMware, Inc.
Chapter 4 Provisioning
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml <VApp name="New Linux Server" status="0" href="http://vcloud.example.com/api/v1.0/vApp/vapp-999" ...> <Description>Cloned from Ubuntu FTP Server</Description> ... <Tasks> <Task ... operation="Busy Virtual Application New Linux Server Copy (201)" ...> ... </Task> </Tasks> </VApp>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ...> ... </Task>
VMware, Inc.
53
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ...> ... </Task>
54
VMware, Inc.
Chapter 4 Provisioning
To add an item to a catalog 1 2 BrowsethevDCsinanorganizationtofindResourceEntityelementsthatreferencetheitemyouwant toaddtothecatalog. CreateaCatalogItemelementthatcontainsareferencetotheitem. Example 34onpage 37listsanumberofResourceEntityelementsinavDC.TocreateaCatalogItem thatreferencesthisone:
<ResourceEntity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111" type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="Ubuntu Template with vsftpd"/>
followtheseguidelines:
POSTtheCatalogItembodytotherel="add"URLincludedintheCatalogbody.
Example 422addsaCatalogItemtothecataloglistedinExample 32onpage 35. Example 4-22. Add an Item to a Catalog Request:
POST http://vcloud.example.com/api/v1.0/catalog/32/catalogItems Content-Type: application/vnd.vmware.vcloud.catalogItem+xml <CatalogItem name="Ubuntu Template with vsftpd" xmlns="http://www.vmware.com/vcloud/v1"> <Description>Approved template for public FTP sites</Description> <Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/> <Property key="Owner">Tech Ops</Property> </CatalogItem>
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.catalogItem+xml ... <CatalogItem name="Ubuntu Template with vsftpd" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221" ...> <Link rel="edit" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/> <Link rel="up" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/catalogItem/221"/> <Description>Approved template for public FTP sites</Description> <Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/> <Property key="Owner">Tech Ops</Property> </CatalogItem>
VMware, Inc.
55
Response:
204 No Content
Controlling Access
AnorganizationadministratorcanusecontrolAccesslinkstocontrolaccesstocatalogsandvApps.
Foreachofthecatalogslistedinthisexcerpt,threelinksareprovided:
56
VMware, Inc.
Chapter 4 Provisioning
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.controlAccess+xml ... <ControlAccessParams ...> <IsSharedToEveryone>false</IsSharedToEveryone> </ControlAccessParams>
BecausethevalueofIsSharedToEveryoneisfalse,theadministratormustgrantaccesstoindividualusers orgroups,specifiedbyreference.InExample 426,theadministratorPOSTsamodifiedversionofthe ControlAccessParamselementreceivedinExample 425tothecatalogsaccesscontrolURL.The modificationspopulatetheAccessSettingscontainerwithtwoAccessSettingelements,eachofwhich assignsanaccessleveltoaspecificuser. Example 4-26. Granting Catalog Access to Users Request:
POST http://vcloud.example.com/api/v1.0/catalog/32/action/controlAccess Content-Type: application/vnd.vmware.vcloud.controlAccess+xml <ControlAccessParams xmlns="http://www.vmware.com/vcloud/v1"> <IsSharedToEveryone>false</IsSharedToEveryone> <AccessSettings> <AccessSetting> <Subject type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/1"/> <AccessLevel>FullControl</AccessLevel> </AccessSetting> <AccessSetting> <Subject type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/6"/> <AccessLevel>ReadOnly</AccessLevel> </AccessSetting> </AccessSettings> </ControlAccessParams>
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.controlaccess+xml ... <ControlAccessParams ...> <IsSharedToEveryone>false</IsSharedToEveryone> <AccessSettings> <AccessSetting> <Subject type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/1"/> <AccessLevel>FullControl</AccessLevel> </AccessSetting> <AccessSetting> <Subject type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/6"/> <AccessLevel>ReadOnly</AccessLevel> </AccessSetting> </AccessSettings> </ControlAccessParams>
VMware, Inc.
57
Tospecifyglobalaccesscontrolsthatapplytoallmembersofanorganization,anorganizationadministrator cansetIsSharedToEveryonetotrueandspecifyanaccesslevelintheEveryoneAccessLevelelement,as showninExample 427. Example 4-27. Granting Catalog Access to Everyone Request:
POST http://vcloud.example.com/api/v1.0/catalog/32/controlAccess Content-Type: application/vnd.vmware.vcloud.controlAccess+xml ... <ControlAccessParams xmlns="http://www.vmware.com/vcloud/v1"> <IsSharedToEveryone>true</IsSharedToEveryone> <EveryoneAccessLevel>ReadOnly</EveryoneAccessLevel> </ControlAccessParams>
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.controlaccess+xml ... <ControlAccessParams ...> <IsSharedToEveryone>true</IsSharedToEveryone> <EveryoneAccessLevel>ReadOnly</EveryoneAccessLevel> </ControlAccessParams>
58
VMware, Inc.
Datacenter Operations
SummaryofDatacenterOperationsRequestsonpage 59 vAppLifecycleonpage 60 InstantiateavAppTemplateonpage 61 ComposeavApponpage 65 RecomposeavApptoAddorRemoveVirtualMachinesonpage 67 CaptureavApptoCreateavAppTemplateonpage 68 ReconfiguringvAppsandVirtualMachinesonpage 69 DeployingandControllingvAppsandVirtualMachinesonpage 80 ControlAccesstovAppsonpage 89 RetrieveaTaskonpage 89
CustomizationSection
Task
ComposeVAppParams
VApp
VMware, Inc.
59
CaptureVAppParams DeployVAppParams UndeployVAppParams None None None None None None None MediaInsertOrEjectParams MediaInsertOrEjectParams None None VmQuestionAnswer None None ControlAccessParams
VAppTemplate Task Task Task Task Task Task Task 204NoContent 204NoContent Task Task RasdItemsList VmPendingQuestion 204NoContent screenthumbnail (Contenttype:image/png) ScreenTicket ControlAccessParams
RetrieveaTask
None
Task
vApp Lifecycle
AvAppcontainsoneormoreVmelements,whichrepresentindividualvirtualmachines.Italsocontains informationthatdefinesoperationaldetailsforthevAppandthevirtualmachinesitcontains.ThevApp lifecycleincludesseveraldistinctstates:
AnOVFpackage,theforminwhichvAppsaretypicallymadeavailablefordownloadanddistribution AvApptemplate,createdwhenaclientuploadsanOVFpackagetoavDC
60
VMware, Inc.
OVF package
descriptor.ovf
disk0.vmdk upload
vApp template
<VApp Template...status=8 href=http://.../vapp Template-3> ... ... </VApp Template>
instantiate vApp
<VApp...status=8 deployed=false href=http://.../vapp-9> ... <Link rel=deploy...> ... </VApp>
deploy vApp
<VApp...status=8 deployed=true href=http://.../vapp-9> ... <Link rel=power:powerOn...> ... </VApp>
VMware, Inc.
61
62
VMware, Inc.
Example 51showsaninstantiationrequestsimilartotheoneshowninExample 26onpage 25,butincludes anAllEULAsAcceptedelementthatdenotesacceptanceoftermsandconditionsembeddedinthechildVm elements,andaLeaseSettingsSectionelementthatspecifiescustomdeploymentandstorageleaseterms forthisvApp.ItalsospecifiesthatthevAppshouldbedeployedandpoweredonafteritisinstantiated.(If youomitthedeployandpowerOnattributes,thedefaultvalueoffalseisassumed.) Example 5-1. Instantiating a vApp Template wIth Custom Lease Settings Request:
POST http://vcloud.example.com/api/v1.0/vdc/5/action/instantiateVAppTemplate Content-Type: application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml ... <InstantiateVAppTemplateParams name="Linux FTP server" deploy=true powerOn=true xmlns="http://www.vmware.com/vcloud/v1" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <Description>Example FTP Server</Description> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="vAppNetwork"> <Configuration> <ParentNetwork href="http://vcloud.example.com/api/v1.0/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=http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111/> <AllEULAsAccepted>true</AllEULAsAccepted> </InstantiateVAppTemplateParams>
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml <VApp name="Linux FTP server" deployed=false status="0" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...> <Description>Example FTP Server</Description> ... <Tasks> <Task ... operation="Creating Virtual Application Linux FTP server(7)" ... > ... </Task> </Tasks> </VApp>
VMware, Inc.
63
Response:
200 OK Content-type: application/vnd.vmware.vcloud.customizationSection+xml ... <CustomizationSection xmlns="http://www.vmware.com/vcloud/v1" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" ovf:required="false" vcloud:href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/ customizationSection/" vcloud:type="application/vnd.vmware.vcloud.customizationSection+xml" ...> <ovf:Info>VApp template customization section</ovf:Info> <CustomizeOnInstantiate>true</CustomizeOnInstantiate> <Link rel="edit" type="application/vnd.vmware.vcloud.customizationSection+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/ customizationSection/"/> </CustomizationSection>
TochangethevalueofCustomizeOnInstantiate,PUTaCustomizationSectionbodythathasthechanged valuetothesectionsrel="edit"URL,asshowninExample 53. Example 5-3. Modify vApp Template CustomizationSection Request:
PUT http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/customizationSection Content-type: application/vnd.vmware.vcloud.customizationSection+xml ... <CustomizationSection xmlns="http://www.vmware.com/vcloud/v1" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" ovf:required="false" vcloud:href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-3/ customizationSection/" vcloud:type="application/vnd.vmware.vcloud.customizationSection+xml"> <ovf:Info>VApp template customization section</ovf:Info> <CustomizeOnInstantiate>false</CustomizeOnInstantiate> </CustomizationSection>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ...> ... </Task>
64
VMware, Inc.
Compose a vApp
ThevCloudAPIsupportscomposingavAppfromanycombinationofvApptemplates,vApps,orvirtual machines.WhenyoucomposeavApp,allchildrenofeachcompositionsourcebecomepeersintheChildren collectionofthecomposedvApp. TocomposeavApp,aclientmakesacomposeVApprequestwhosebody,aComposeVAppParamselement, includesthefollowinginformation:
ThecomposedvAppmustbedeployedandpoweredonbeforeitcanbeused. Example 54showsacomposeVApprequestthatspecifiestwovAppTemplatesourcesandoneVmsource.The VmsourcerequiresInstantiationParamsthatmodifyitsNetworkConnectionSectiontospecifythevApp networkcreatedforthisvApp.ThevAppTemplatesourcesinheritthissettingfromthebase InstantiationParamselement(theonethatappearsbeforethefirstItemisspecified). Example 5-4. Compose a vApp Request:
POST http://vcloud.example.com/api/v1.0/vdc/5/action/composeVApp Content-Type: application/vnd.vmware.vcloud.composeVAppParams+xml ... <ComposeVAppParams name="Example Corps CRM Appliance" xmlns="http://www.vmware.com/vcloud/v1" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="CRMApplianceNetwork"> <Configuration> <ParentNetwork href="http://vcloud.example.com/api/v1.0/network/54"/> <FenceMode>bridged</FenceMode> </Configuration> </NetworkConfig> </NetworkConfigSection> </InstantiationParams> <Item> <Source href="http://vcloud.example.com/api/v1.0/vApp/vm-4"/> <InstantiationParams> <NetworkConnectionSection type="application/vnd.vmware.vcloud.networkConnectionSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ networkConnectionSection/" ovf:required="false"> <ovf:Info/> <PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex> <NetworkConnection network="CRMApplianceNetwork"> <NetworkConnectionIndex>0</NetworkConnectionIndex> <IsConnected>true</IsConnected> <IpAddressAllocationMode>DHCP</IpAddressAllocationMode> </NetworkConnection>
VMware, Inc.
65
</NetworkConnectionSection> </InstantiationParams> </Item> <Item> <Source href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-114"/> </Item> <Item> <Source href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-190"/> </Item> <AllEULAsAccepted>true</AllEULAsAccepted> </ComposeVAppParams>
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml ... <VApp name="Example Corps CRM Appliance" type="application/vnd.vmware.vcloud.vApp+xml" status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-33" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Description>Composed CRM Appliance</Description> ... <Tasks> <Task ...> ... </Task> </Tasks> </VApp>
Response:
200 OK Content-type: application/vnd.vmware.vcloud.vApp+xml ... <VApp name="Linux FTP server" status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...> ... <Children> <Vm status="8" href="http://vcloud.example.com/api/v1.0/vApp/vm-4" ...> ... </Children> </VApp>
66
VMware, Inc.
Response:
200 OK Content-type: application/vnd.vmware.vcloud.vApp+xml ... <VApp name="Example Corps CRM Appliance" type="application/vnd.vmware.vcloud.vApp+xml" status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-33" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Description>Composed CRM Appliance</Description> ... <Children> <Vm status="8" name="CRM-DB" href="http://vcloud.example.com/api/v1.0/vApp/vm-7" ...> ... </Vm> <Vm status="8" name="CRM-CRM" href="http://vcloud.example.com/api/v1.0/vApp/vm-44" ...> ... </Vm> <Vm status="8" name="CRM-HTTP" href="http://vcloud.example.com/api/v1.0/vApp/vm-45" ...> ... </Vm> </Children> ... </VApp>
Example 57showsarecomposeVApprequestthatmodifiesthevAppshowninExample 56byremovingone ofthevirtualmachinesitcontainsandcreatinganewStartupSectionthatspecifiesastartuporderforthe twovirtualmachinesthatremaininthevApp. Example 5-7. Recompose a vApp Request:
POST http://vcloud.example.com/api/v1.0/vApp/vapp-33/action/recomposeVApp Content-Type: application/vnd.vmware.vcloud.recomposeVAppParams+xml ... <RecomposeVAppParams name="Example Corps CRM Appliance" xmlns="http://www.vmware.com/vcloud/v1" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"> <InstantiationParams> <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="CRMApplianceNetwork"> <Configuration> <ParentNetwork href="http://vcloud.example.com/api/v1.0/network/54"/> <FenceMode>bridged</FenceMode> </Configuration> </NetworkConfig> </NetworkConfigSection>
VMware, Inc.
67
<ovf:StartupSection xmlns:vcloud="http://www.vmware.com/vcloud/v1" vcloud:href="http://vcloud.example.com/api/v1.0/vApp/vapp-33/ startupSection/" vcloud:type="application/vnd.vmware.vcloud.startupSection+xml"> <ovf:Info>VApp startup section</ovf:Info> <ovf:Item ovf:order="0" ovf:id="CRM-DB"/> <ovf:Item ovf:order="1" ovf:id="CRM-CRM"/> </ovf:StartupSection> </InstantiationParams> <AllEULAsAccepted>true</AllEULAsAccepted> <DeleteItem href="http://vcloud.example.com/api/v1.0/vApp/vm-45" /> </RecomposeVAppParams>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Updating Virtual Application Example Corps CRM Appliance (33)" ...> ... </Task>
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate name="Linux Server Template"" type="application/vnd.vmware.vcloud.vApp+xml" status="8" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-20" ...> <Link rel="up" type="application/vnd.vmware.vcloud.vdc+xml" href="http://vcloud.example.com/api/v1.0/vdc/5"/> <Description>Template captured from Ubuntu vApp</Description> <Tasks> <Task ... operation="Capturing Virtual Application Template CaturedTemplate (20)" ... > ... </Task> </Tasks> ... </VAppTemplate>
TheresponseisavAppTemplatedocumentthatcontainsaTask.ThestatusofthevAppTemplateisinitially 0.Whenthecaptureoperationiscomplete,thestatuschangesto8.
68
VMware, Inc.
Reconfigure a vApp
Table 52summarizesvAppreconfigurationrequestssupportedinthisrelease.Thetableusesthefollowing conventions:
APIURLisaURLoftheformhttp://vcloud.example.com/api/v1.0 idisaninteger
YoucanreconfigureavAppbymakingchangestoanyofthefollowingsections:
VMware, Inc.
69
Response:
200 OK Content-type: application/vnd.vmware.vcloud.vApp+xml ... <VApp name="Linux FTP server" status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...> <Description>Example FTP Server</Description> ... <LeaseSettingsSection href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/leaseSettingsSection/" ovf:required="false"> <ovf:Info>VApp lease settings</ovf:Info> <Link rel="edit" type="application/vnd.vmware.vcloud.leaseSettingsSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/ leaseSettingsSection/"/> <DeploymentLeaseInSeconds>3600</DeploymentLeaseInSeconds> <StorageLeaseInSeconds>3600</StorageLeaseInSeconds> <DeploymentLeaseExpiration>2010-01-21T13:50:59.764-08:00</DeploymentLeaseExpiration> </LeaseSettingsSection> <ovf:StartupSection href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/startupSection/"> <ovf:Info>VApp startup section</ovf:Info> <Link rel="edit" type="application/vnd.vmware.vcloud.startupSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/startupSection/"/> </ovf:StartupSection> <ovf:NetworkSection ... > ... </ovf:NetworkSection> <NetworkConfigSection href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/" ovf:required="false"> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConfigSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/ networkConfigSection/"/> <ovf:Info>Configuration parameters for vAppNetwork</ovf:Info> <NetworkConfig ... > ... <Configuration> ... </Configuration> <IsDeployed>false</IsDeployed> </NetworkConfig> </NetworkConfigSection> <Children> ... </Children> </VApp>
70
VMware, Inc.
NOTESectionsthatdonothaveaLinkwhererel="edit"cannotbemodified.
Response:
200 OK Content-type: application/vnd.vmware.vcloud.networkConfigSection+xml ... <NetworkConfigSection href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/" ovf:required="false"> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConfigSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/"/> <NetworkConfig networkName="vAppNetwork"> <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="http://vcloud.example.com/api/v1.0/network/54"/> <FenceMode>bridged</FenceMode> </Configuration> <IsDeployed>false</IsDeployed> </NetworkConfig> </NetworkConfigSection>
VMware, Inc.
71
AsetofFirewallRulesthatallowTCPtraffictoports21and22.Becausetheserulesrequireyouto specifyasingleIPaddressontheinsideofthefirewall,theIpScopeelementismodifiedtolimittherange ofIPaddressesavailableonthevAppnetworktoasingleaddress.AnyVmthatconnectstothevApp networkdefinedinthisNetworkConfigSectionisgiventhisaddress. ANatServiceelementthatmapsaroutableexternalIPaddresstotheinternalIPaddressallocatedtothe VmbythevAppnetwork.TheVAppScopedVmIdvalueinthiselementistakenfromthe VAppScopedLocalIdelementoftheVmandtheVmNicIdvalueistakenfromits PrimaryNetworkConnectionIndex.SeeExample 512onpage 75.
WheneveryoumodifyavAppnetwork,aswedointhisexample,youmustbesurethatthemodificationsare consistentwiththenetworkconnectionrequirementsofthevirtualmachinesthatconnecttothenetwork.The vAppinthisexamplecontainsasingleVm.AsshowninExample 512onpage 75,thatvirtualmachines NetworkConnectionelementspecifiesanIPaddressthatwillnotbeavailableafterthevAppnetworkhas beenreconfiguredasshowninExample 511.Example 514onpage 77correctsthisproblem.While Example 511usestheIpScopeelementtorestricttheIPaddressesavailableonavAppnetwork,itisusually morepracticaltokeeptherangeofaddressesavailableonavAppnetworksomewhatwider,andapplyany firewallrelatedIPaddressrestrictionsbymodifyingtheNetworkConnection oftheVmtowhichthe FirewallRulesapply,aswedoinExample 514.AwiderrangeofIPaddresseswouldallowthisvApptobe modifiedtoincludeadditionalvirtualmachines,andtheIPaddressrestrictionappliedinExample 514would allowtheFirewallRulesinExample 514toremainvalid. Thisrequest,likeallrequestbodiesderivedfromaresponse,omitstheLinkelementsandhrefattributesthat werepartoftheresponse.ItalsoomitstheIsDeployedelementoftheNetworkConfig.Theseelementsand attributesarecreatedbytheserverandarereadonly.Theyareignoredifyouincludetheminarequest. Example 5-11. Modify vApp Network Configuration Request:
PUT http://vcloud.example.com/api/v1.0/vApp/vapp-7/networkConfigSection/ Content-type: application/vnd.vmware.vcloud.networkConfigSection+xml ... <NetworkConfigSection> <ovf:Info>Configuration parameters for logical networks</ovf:Info> <NetworkConfig networkName="vAppNetwork"> <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="http://vcloud.example.com/api/v1.0/network/54"/> <FenceMode>natRouted</FenceMode> <Features> <FirewallService> <IsEnabled>true</IsEnabled> <FirewallRule> <IsEnabled>true</IsEnabled> <Description>FTP Rule</Description> <Policy>allow</Policy> <Protocols> <Tcp>true</Tcp> </Protocols> <Port>21</Port>
72
VMware, Inc.
<DestinationIp>10.147.115.1</DestinationIp> </FirewallRule> <FirewallRule> <IsEnabled>true</IsEnabled> <Description>SSH Rule</Description> <Policy>allow</Policy> <Protocols> <Tcp>true</Tcp> </Protocols> <Port>22</Port> <DestinationIp>10.147.115.1</DestinationIp> </FirewallRule> </FirewallService> <NatService> <IsEnabled>true</IsEnabled> <NatType>ipTranslation</NatType> <Policy>allowTraffic</Policy> <NatRule> <OneToOneVmRule> <MappingMode>manual</MappingMode> <ExternalIp>64.100.10.1</ExternalIp> <VAppScopedVmId>20ea086f-1a6a-4fb2-8e2e-23372facf7de</VAppScopedVmId> <VmNicId>0</VmNicId> </OneToOneVmRule> </NatRule> </NatService> </Features> </Configuration> </NetworkConfig> </NetworkConfigSection>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Updating Virtual Application Linux FTP server (7)" ...> ... </Task>
TheresponseisaTaskelement.
APIURLisaURLoftheformhttp://vcloud.example.com/api/v1.0 idisaninteger
VMware, Inc.
73
RetrievetheGuestCustomization GETAPIURL/vApp/vmid/ SectionofaVirtualMachine guestCustomizationSection/ ModifytheGuestCustomization PUTAPIURL/vApp/vmid/ SectionofaVirtualMachine guestCustomizationSection/ RetrievetheOperatingSystem SectionofaVirtualMachine ModifytheOperatingSystem SectionofaVirtualMachine RetrievetheVirtualHardware SectionofaVirtualMachine ModifytheVirtualHardware SectionofaVirtualMachine GETAPIURL/vApp/vmid/ operatingSystemSection/ PUTAPIURL/vApp/vmid/ operatingSystemSection/ GETAPIURL/vApp/vmid/ virtualHardwareSection/ PUTAPIURL/vApp/vmid/ virtualHardwareSection/
RetrievetheCPUConfigurationof GETAPIURL/vApp/vmid/ aVirtualMachine virtualHardwareSection/cpu ModifytheCPUConfigurationof PUTAPIURL/vApp/vmid/ aVirtualMachine virtualHardwareSection/cpu RetrievetheMemoryItemfrom GETAPIURL/vApp/vmid/ theVirtualHardwareSectionofa virtualHardwareSection/memory VirtualMachine ModifytheMemoryItemofthe VirtualHardwareSectionofa VirtualMachine PUTAPIURL/vApp/vmid/ virtualHardwareSection/memory
ovf:Item
Task
RetrieveVirtualDiskItemsfrom GETAPIURL/vApp/vmid/ theVirtualHardwareSectionofa virtualHardwareSection/disks VirtualMachine ModifyVirtualDiskItemsofthe VirtualHardwareSectionofa VirtualMachine PUTAPIURL/vApp/vmid/ virtualHardwareSection/disks
None
RasdItemsList
RasdItemsList
Task
GETAPIURL/vApp/vmid/ RetrieveNetworkCardItems fromtheVirtualHardwareSection virtualHardwareSection/ networkCards ofaVirtualMachine ModifyNetworkCardItemsofthe PUTAPIURL/vApp/vmid/ virtualHardwareSection/ VirtualHardwareSectionofa networkCards VirtualMachine RetrieveRemovableMediaDrive GETAPIURL/vApp/vmid/ ItemsfromtheVirtualHardware virtualHardwareSection/media SectionofaVirtualMachine
None
RasdItemsList
RasdItemsList
Task
None
RasdItemsList
Youcanreconfigureavirtualmachine(Vmelement)bymakingchangestoanyofthefollowingsections:
Modifiedsectionsmustcontainallrequiredelements,evenifyouarenotchangingtheirvalues.Some elementsinsomesectionsarereadonly.Seetheschemareferencesfordetails.
74
VMware, Inc.
Example 512showsarepresentativecollectionoftheselinks.(Thisexampledoesnotshowtheconfiguration linksfortheparentvApp.Toseethem,refertoExample 59onpage 70.) Example 5-12. Configuration Links for a Vm Request:
GET http://vcloud.example.com/api/v1.0/vApp/vapp-7
Response:
200 OK Content-type: application/vnd.vmware.vcloud.vApp+xml ... <VApp name="Linux FTP server" status="8" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...> <Description>Example FTP Server</Description> ... <Children> <Vm status="8" name="ubuntu10-x86" href="http://vcloud.example.com/api/v1.0/vApp/vm-4" ...> <Link rel="power:reboot" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/power/ action/reboot"/> ... <Link rel="media:ejectMedia" type="application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/media/ action/ejectMedia"/> <Description/> <ovf:VirtualHardwareSection ... "> <ovf:System> ... </ovf:System> <ovf:Item vcloud:href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/cpu" ... > ... <rasd:Description>Number of Virtual CPUs</rasd:Description> <rasd:ResourceType>3</rasd:ResourceType> ... <Link rel="edit" type="application/vnd.vmware.vcloud.rasdItem+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/cpu"/> </ovf:Item> <ovf:Item vcloud:href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/memory" ...> ... <rasd:Description>Memory Size</rasd:Description> <rasd:ResourceType>4</rasd:ResourceType> ... <Link rel="edit" type="application/vnd.vmware.vcloud.rasdItem+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/memory"/> </ovf:Item> <ovf:Item> ... <rasd:Description>SCSI Controller</rasd:Description> <rasd:ResourceType>6</rasd:ResourceType> ... </ovf:Item> <ovf:Item> ... <rasd:Description>Hard disk</rasd:Description> <rasd:ElementName>Hard disk 1</rasd:ElementName> <rasd:ResourceType>17</rasd:ResourceType> ... </ovf:Item>
VMware, Inc.
75
<Link rel="edit" type="application/vnd.vmware.vcloud.virtualHardwareSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/"/> <Link type="application/vnd.vmware.vcloud.rasdItemsList+xml" rel="edit href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/disks"/> ... <Link rel="edit" type="application/vnd.vmware.vcloud.rasdItemsList+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ virtualHardwareSection/networkCards"/> ... </ovf:VirtualHardwareSection> <ovf:OperatingSystemSection ... href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ operatingSystemSection/"> ... <Link rel="edit" type="application/vnd.vmware.vcloud.operatingSystemSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ operatingSystemSection/"/> </ovf:OperatingSystemSection> <NetworkConnectionSection ... href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ networkConnectionSection/" ...> <ovf:Info>Specifies the available VM network connections</ovf:Info> <PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex> <NetworkConnection network="vAppNetwork"> <NetworkConnectionIndex>0</NetworkConnectionIndex> <IpAddress>10.147.122.134</IpAddress> <IsConnected>false</IsConnected> <MACAddress>00:50:56:01:01:49</MACAddress> <IpAddressAllocationMode>POOL</IpAddressAllocationMode> </NetworkConnection> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConnectionSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ networkConnectionSection/"/> </NetworkConnectionSection> <GuestCustomizationSection type="application/vnd.vmware.vcloud.guestCustomizationSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ guestCustomizationSection/" ovf:required="false"> <ovf:Info>Specifies Guest OS Customization Settings</ovf:Info> <Enabled>false</Enabled> <ChangeSid>false</ChangeSid> <VirtualMachineId>4</VirtualMachineId> <JoinDomainEnabled>false</JoinDomainEnabled> <UseOrgSettings>false</UseOrgSettings> <AdminPasswordEnabled>false</AdminPasswordEnabled> <AdminPasswordAuto>true</AdminPasswordAuto> <ResetPasswordRequired>false</ResetPasswordRequired> <CustomizationScript/> <ComputerName>ubuntu10-x86</ComputerName> <Link rel="edit" type="application/vnd.vmware.vcloud.guestCustomizationSection+xml " href="http://vcloud.example.com/api/v1.0/vApp/vm-4/ guestCustomizationSection/"/> </GuestCustomizationSection> <VAppScopedLocalId>20ea086f-1a6a-4fb2-8e2e-23372facf7de</VAppScopedLocalId> </Vm> </Children> </VApp>
76
VMware, Inc.
ReconfigurationlinksinthebodyofaVmcanappearintwoplaces:
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.networkconnectionsection+xml ... <NetworkConnectionSection ... href="http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/" ...> <ovf:Info>Specifies the available VM network connections</ovf:Info> <PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex> <NetworkConnection network="vAppNetwork"> <NetworkConnectionIndex>0</NetworkConnectionIndex> <IpAddress>10.147.122.134</IpAddress> <IsConnected>false</IsConnected> <MACAddress>00:50:56:01:01:49</MACAddress> <IpAddressAllocationMode>POOL</IpAddressAllocationMode> </NetworkConnection> <Link rel="edit" type="application/vnd.vmware.vcloud.networkConnectionSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-4 networkConnectionSection/"/> </NetworkConnectionSection>
ThemodifiedNetworkConnectionSectionintherequestbodychangesthevalueintheIpAddresselement. Example 5-14. Modify the Network Connection of a Virtual Machine Request:
PUT "http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/ Content-type: application/vnd.vmware.vcloud.networkConnectionSection+xml ... <NetworkConnectionSection ... href="http://vcloud.example.com/api/v1.0/vApp/vm-4/networkConnectionSection/" ...> <ovf:Info>Specifies the available VM network connections</ovf:Info> <PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex> <NetworkConnection network="vAppNetwork"> <NetworkConnectionIndex>0</NetworkConnectionIndex> <IpAddress>10.147.115.1</IpAddress> <IsConnected>false</IsConnected> <MACAddress>00:50:56:01:01:49</MACAddress> <IpAddressAllocationMode>POOL</IpAddressAllocationMode> </NetworkConnection> </NetworkConnectionSection>
VMware, Inc.
77
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Updating Virtual Application Linux FTP server (7)" ...> ... </Task>
Response:
200 OK Content-type: application/vnd.vmware.vcloud.rasdItem+xml ... <Item xmlns="http://www.vmware.com/vcloud/v1" xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/ CIM_ResourceAllocationSettingData" ... > <rasd:AllocationUnits>hertz * 10^6</rasd:AllocationUnits> <rasd:Description>Number of Virtual CPUs</rasd:Description> <rasd:ElementName>1 virtual CPU(s)</rasd:ElementName> <rasd:InstanceID>1</rasd:InstanceID> <rasd:ResourceType>3</rasd:ResourceType> <rasd:VirtualQuantity>1</rasd:VirtualQuantity> </Item>
ThemodifiedItemintherequestbodyaddsasecondCPUtotheVmbychangingtherasd:VirtualQuantity valueoftheItemto2. Example 5-16. Modify the CPU Configuration of a Virtual Machine Request:
PUT http://vcloud.example.com/api/v1.0/vApp/vm-4/virtualHardwareSection/cpu Content-type: application/vnd.vmware.vcloud.rasdItem+xml ... <Item xmlns="http://www.vmware.com/vcloud/v1" xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/ CIM_ResourceAllocationSettingData"> <rasd:AllocationUnits>hertz * 10^6</rasd:AllocationUnits> <rasd:Description>Number of Virtual CPUs</rasd:Description> <rasd:ElementName>1 virtual CPU(s)</rasd:ElementName> <rasd:InstanceID>1</rasd:InstanceID> <rasd:ResourceType>3</rasd:ResourceType> <rasd:VirtualQuantity>2</rasd:VirtualQuantity> </Item>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Updating Virtual Application Linux FTP server (7)" ...> ... </Task>
78
VMware, Inc.
Response:
200 OK Content-type: application/vnd.vmware.vcloud.guestcustomizationsection+xml ... <GuestCustomizationSection type="application/vnd.vmware.vcloud.guestCustomizationSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection/" ovf:required="false"> <ovf:Info>Specifies Guest OS Customization Settings</ovf:Info> <Enabled>false</Enabled> <ChangeSid>false</ChangeSid> <VirtualMachineId>4</VirtualMachineId> <JoinDomainEnabled>false</JoinDomainEnabled> <UseOrgSettings>false</UseOrgSettings> <AdminPasswordEnabled>false</AdminPasswordEnabled> <AdminPasswordAuto>true</AdminPasswordAuto> <ResetPasswordRequired>false</ResetPasswordRequired> <CustomizationScript/> <ComputerName>ubuntu10-x86</ComputerName> <Link rel="edit" type="application/vnd.vmware.vcloud.guestCustomizationSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-12/ guestCustomizationSection/"/> </GuestCustomizationSection>
ThemodifiedGuestCustomizationSectionintherequestbodychangesthevalueofthe JoinDomainEnabledelementtotrue.Thischangerequiresyoutospecifyadomaintojoin,alongwiththe nameandpasswordofadomainadministrator,sotherequestbodyincludesDomainName,DomainUserName, andDomainUserPasswordelements. Example 5-18. Modify the Guest Customization Section of a Virtual Machine Request:
PUT http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection Content-type: application/vnd.vmware.vcloud.guestcustomizationsection+xml ... <GuestCustomizationSection type="application/vnd.vmware.vcloud.guestCustomizationSection+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-12/guestCustomizationSection/" ovf:required="false"> <ovf:Info>Specifies Guest OS Customization Settings</ovf:Info> <Enabled>false</Enabled> <ChangeSid>false</ChangeSid> <VirtualMachineId>4</VirtualMachineId> <JoinDomainEnabled>true</JoinDomainEnabled> <UseOrgSettings>false</UseOrgSettings> <DomainName>EXAMPLE</DomainName> <DomainUserName>admin</DomainUserName> <DomainUserPassword>Pa55w0rd</DomainUserPassword> <AdminPasswordEnabled>false</AdminPasswordEnabled> <AdminPasswordAuto>true</AdminPasswordAuto> <ResetPasswordRequired>false</ResetPasswordRequired> <CustomizationScript/> <ComputerName>ubuntu10-x86</ComputerName>
VMware, Inc.
79
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Updating Virtual Application Win2K3 (12)" ...> ... </Task>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Starting Virtual Application Linux FTP server (7) ...> ... </Task>
RequesttoundeployaVm:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/action/undeploy Content-type: application/vnd.vmware.vcloud.undeployVAppParams+xml ... <UndeployVAppParams saveState="true" xmlns="http://www.vmware.com/vcloud/v1"/>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ...> ... </Task>
VMware, Inc.
81
Requesttopoweronavirtualmachine:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/powerOn
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Starting Virtual Application Linux FTP server (7) ...> ... </Task>
Requesttopoweroffavirtualmachine:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/powerOff
Response:
202 Accepted ... Content-Type: application/vnd.vmware.vcloud.task+xml <Task ...> ... </Task>
RequesttoresetaVm:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/reset
82
VMware, Inc.
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ...> ... </Task>
RequesttosuspendaVm:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/suspend
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ...> ... </Task>
RequesttodiscardthesuspendedstateofaVm:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/action/discardSuspendedState
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ...> ... </Task>
VMware, Inc.
83
RequesttoshutdownaVm:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/shutdown
Response:
204 No Content
RequesttorebootaVm:
POST http://vcloud.example.com/api/v1.0/vApp/vm-5/power/action/reboot
Response:
204 No Content
84
VMware, Inc.
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.rasditemslist+xml ... <RasdItemsList xmlns="http://www.vmware.com/vcloud/v1" ... href="http://vcloud.example.com/api/v1.0/vApp/vm-5/virtualHardwareSection/media" ... > <Item> <rasd:Address>0</rasd:Address> <rasd:Description>IDE Controller</rasd:Description> <rasd:ElementName>IDE Controller 0</rasd:ElementName> <rasd:InstanceID>1</rasd:InstanceID> <rasd:ResourceType>5</rasd:ResourceType> </Item> <Item> <rasd:AddressOnParent>0</rasd:AddressOnParent> <rasd:Description>CD/DVD Drive</rasd:Description> <rasd:ElementName>CD/DVD Drive 1</rasd:ElementName> <rasd:HostResource xmlns:vcloud="http://www.vmware.com/vcloud/v1" vcloud:connected="false"></rasd:HostResource> <rasd:InstanceID>3000</rasd:InstanceID> <rasd:Parent>1</rasd:Parent> <rasd:ResourceType>15</rasd:ResourceType> </Item> <Item> <rasd:AddressOnParent>0</rasd:AddressOnParent> <rasd:Description>Floppy Drive</rasd:Description> <rasd:ElementName>Floppy Drive 1</rasd:ElementName> <rasd:HostResource xmlns:vcloud="http://www.vmware.com/vcloud/v1" vcloud:connected="false"></rasd:HostResource> <rasd:InstanceID>8000</rasd:InstanceID> <rasd:ResourceType>14</rasd:ResourceType> </Item> </RasdItemsList>
VMware, Inc.
85
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ...> ... </Task>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ...> ... </Task>
Response:
200 OK Content-type image/png ...
...serializedcontentsofthumbnailinpngformat... EOF
86
VMware, Inc.
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.screenTicket+xml ... <ScreenTicket xmlns="http://www.vmware.com/vcloud/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1 ...> mks://10.147.43.171/vm-61?ticket=Pznh4HMb7k%2FlniSLwyAD1fmlPIXOuSACKgEReF7ylTIn4qRkxhFv9QT7I3 SLTAQu%2F7W5RxVpDxjVKuuHQ4VIwu59F%2FG1WL1OmYMWistJC9tkRjQ1RRQiB1Oem5E7qX9O </ScreenTicket>
Response:
200 OK Content-type: application/vnd.vmware.vcloud.vApp+xml ... <VApp name="Linux FTP server" status="5" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" ...> ... <Link rel="down" type="application/vnd.vmware.vcloud.vmPendingQuestion+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-5/question"/> ... <Description>Example FTP Server</Description> ... <Children> ... </Children> </vApp>
VMware, Inc.
87
Response:
200 OK Content-type: application/vnd.vmware.vcloud.vmPendingQuestion+xml ... <VmPendingQuestion xmlns="http://www.vmware.com/vcloud/v1" ... > <Link type="application/vnd.vmware.vcloud.vmPendingAnswer+xml" href="http://vcloud.example.com/api/v1.0/vApp/vm-5/question/action/answer"/> <Question>msg.parallel.file.open:Parallel port output file "/vmfs/volumes/d6162a46-58e50cab/linuxftp/vm-mgi.log" already exists. Do you want to replace it with any newly created content, or append new content to the end of the file? </Question> <QuestionId>50</QuestionId> <Choices> <Id>0</Id> <Text>Append</Text> </Choices> <Choices> <Id>1</Id> <Text>Replace</Text> </Choices> <Choices> <Id>2</Id> <Text>Cancel</Text> </Choices> </VmPendingQuestion>
Response:
204 No Content
88
VMware, Inc.
Retrieve a Task
Whenevertheresultofarequestcannotbereturnedimmediately,theservercreatesaTaskobjectandincludes itintheresponse,asamemberoftheTaskscontainerintheresponsebody.EachTaskhasanhrefvalue, whichisaURLthattheclientcanusetoretrievetheTaskelementalone,withouttherestoftheresponsein whichitwascontained.AllinformationaboutthetaskisincludedintheTaskelementwhenitisreturnedin theresponsesTaskscontainer,soaclientdoesnotneedtomakeanadditionalrequesttotheTaskURLunless itwantstofollowtheprogressofataskthatwasincomplete. Example 537retrievesthattaskthatwasreturnedintheresponseinExample 26onpage 25. Example 5-37. Retrieve a Task Request:
GET http://vcloud.example.com/api/v1.0/task/1awvdrn82atz7yzsdey
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task status="running" startTime="2010-06-25T08:00:55.402-07:00" operation="Creating Virtual Application Linux FTP server(7)" expiryTime="2010-09-23T08:00:55.402-07:00" type="application/vnd.vmware.vcloud.task+xml" href="http://vcloud.example.com/api/v1.0/task/1awvdrn82atz7yzsdey"> <Owner type="application/vnd.vmware.vcloud.vApp+xml" name="LinuxFtpServer" href="http://vcloud.example.com/vApp/vapp-7"/> </Task>
Tasksexpireafteraconfigurableinterval.Thedefaultintervalis24hours.
VMware, Inc.
89
90
VMware, Inc.
Administrative Operations
SummaryofAdministrativeRequestsonpage 91 AdministratorCredentialsandPrivilegesonpage 93 AdministrativeObjectsandURLsonpage 93 GetanAdministrativeViewofaCloudonpage 93 OrganizationAdministrationonpage 94 NetworkAdministrationonpage 99 vDCAdministrationonpage 102 CatalogAdministrationonpage 107 UserAdministrationonpage 110 GroupAdministrationonpage 113 RoleAdministrationonpage 114
APIURLisaURLoftheformhttp://vcloud.example.com/api/v1.0 idisaninteger
VMware, Inc.
91
RemoveavDC CreateaCatalog GetanAdministrativeViewofa Catalog PublishaCatalog ModifyCatalogMetadata RemoveaCatalog CreateorImportaUser GetanAdministrativeViewofaUser ModifyUserMetadata RemoveaUser ImportaGroup ViewGroupMetadata ModifyGroupMetadata RemoveaGroup CreateaRole ViewRoleMetadata ModifyaRole RemoveaRole ViewaRight
None Catalog None PublishCatalogParams Catalog None User None User None Group None Group None Role None Role None None
Task Catalog Catalog 204NoContent Catalog 204NoContent User User User 204NoContent Group Group Group 204NoContent Role Role Role 204NoContent Right
92
VMware, Inc.
Someadministrativeoperations(andallvSphereplatformoperations)arerestrictedtothesystem administrator.Beforeattemptinganyoftheseoperations,logintotheSystemorganizationwiththeusername andpasswordofthesystemadministratoraccountthatwascreatedwhenvCloudServiceDirectorwas installed.Forexample,ifthesystemadministratorsnameandpasswordhadbeendefinedasadministrator andPa55w0rd,thesystemadministratorlogincredentialswouldbetheMIMEBase64encodingofthestring administrator@System:Pa55w0rd. TheSystemorganizationiscreatedautomaticallywhenvCloudServiceDirectorisinstalled,andalwayshasa URLoftheformAPIURL/org/1.ItisnotlistedinanOrgList,butcanberetrievedwithanexplicitGET request,asshowninExample 61. Example 6-1. The System Organization Request:
GET http://vcloud.example.com/api/v1.0/org/1
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.org+xml ... <Org xmlns="http://www.vmware.com/vcloud/v1" name="System" ...> ... </Org>
VMware, Inc.
93
Response:
200 OK Content-Type: application/vnd.vmware.admin.vcloud+xml ... <VCloud name="vCloud" href="http://vcloud.example.com/api/v1.0/admin" ...> <Link rel="add" type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/roles"/> <Link rel="add" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0/admin/orgs"/> <Description>Example Corporations vCloud</Description> <OrganizationReferences> <OrganizationReference type="application/vnd.vmware.admin.organization+xml" name="Engineering" href="http://vcloud.example.com/api/v1.0/admin/org/44"/> <OrganizationReference ... /> ... </OrganizationReferences> <ProviderVdcReferences> <ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="Main Provider" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> <ProviderVdcReference ... /> ... </ProviderVdcReferences> <RightReferences> <RightReference type="application/vnd.vmware.admin.right+xml name="vApp_Deploy" href="http://vcloud.example.com/api/v1.0/admin/right/3"/> <RightReference type="application/vnd.vmware.admin.right+xml name="Catalog: Sharing" href="http://vcloud.example.com/api/v1.0/admin/right/7"/> <RightReference ... /> ... </RightReferences> <RoleReferences> <RoleReference type="application/vnd.vmware.admin.role+xml" name="Organization Administrator" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> <RoleReference type="application/vnd.vmware.admin.role+xml" name="Catalog Creator" href="http://vcloud.example.com/api/v1.0/admin/role/103"/> <RoleReference ... /> ... </RoleReferences> <Networks> <Network type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC1" href="http://vcloud.example.com/api/v1.0/admin/network/7"/> <Network type="application/vnd.vmware.admin.network+xml" name="ExternalNetwork-VC2" href="http://vcloud.example.com/api/v1.0/admin/network/33"/> <Network ... /> ... </Networks> </VCloud>
Organization Administration
AnAdminOrgisanextendedrepresentationofanOrgobject,andisaccessedatAPIURL/admin/org/id, ratherthanAPIURL/org/id.AlthoughsystemadministratorsworkwithAdminOrgelementstocreateand modifyorganizations,mostmodificationstoanAdminOrgalsomodifysomeuservisiblepropertyofthe correspondingOrg.
94
VMware, Inc.
Create an Organization
Tocreateanorganization,asystemadministratorPOSTsanAdminOrgbodytothevCloudsorgsURL,as showninExample 63. Theresponseechoestherequest,withseveralimportantadditions:
Response:
201 Created Content-Type: application/vnd.vmware.admin.organization+xml ... <AdminOrg xmlns="http://www.vmware.com/vcloud/v1" href="http://vcloud.example.com/api/v1.0/admin/org/26" name="ExampleFinance" type="application/vnd.vmware.admin.organization+xml"> <Link rel="down" type="application/vnd.vmware.vcloud.tasksList+xml" href="http://vcloud.example.com/api/v1.0/tasksList/26"/> <Link rel="add" type="application/vnd.vmware.admin.catalog+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/catalogs"/> <Link rel="add" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/users"/> <Link rel="add" type="application/vnd.vmware.admin.group+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/groups"/>
VMware, Inc.
95
<Link rel="add" type="application/vnd.vmware.admin.vdc+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/vdcs"/> <Link rel="add" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/networks"/> <Link rel="edit" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/org/26"/> <Link rel="disable" href="http://vcloud.example.com/api/v1.0/admin/org/26/action/disable"/> <Link rel="alternate" type="application/vnd.vmware.vcloud.org+xml" href="http://vcloud.example.com/api/v1.0/org/26"/> <Description>Example Corporations Finance Organization</Description> <FullName>Finance</FullName> <Settings> <IsEnabled>false</IsEnabled> <CanPublishCatalogs>true</CanPublishCatalogs> <DeployedVMQuota>0</DeployedVMQuota> <StoredVmQuota>0</StoredVmQuota> <OrgLeaseSettings> <DeleteOnStorageLeaseExpiration>false</DeleteOnStorageLeaseExpiration> <DeploymentLeaseSeconds>604800</DeploymentLeaseSeconds> <StorageLeaseSeconds>2592000</StorageLeaseSeconds> </OrgLeaseSettings> <OrgLdapMode>SYSTEM</OrgLdapMode> <OrgEmailSettings> <IsDefaultSmtpServer>true</IsDefaultSmtpServer> <IsDefaultOrgEmail>true</IsDefaultOrgEmail> <FromEmailAddress>Admin@example.com</FromEmailAddress> <DefaultSubjectPrefix>Attention</DefaultSubjectPrefix> <IsAlertEmailToAllAdmins>true</IsAlertEmailToAllAdmins> <SmtpServerSettings> <IsUseAuthentication>true</IsUseAuthentication> <Host>smtp.example.com</Host> <Username>admin@smtp.example.com</Username> </SmtpServerSettings> </OrgEmailSettings> </Settings> </AdminOrg>
Response:
200 OK Content-Type:application/vnd.vmware.admin.organization+xml ... <AdminOrg xmlns="http://www.vmware.com/vcloud/v1" href="http://vcloud.example.com/api/v1.0/admin/org/26" name="ExampleFinance" type="application/vnd.vmware.admin.organization+xml"> <Link rel="down" type="application/vnd.vmware.vcloud.tasksList+xml" href="http://vcloud.example.com/api/v1.0/tasksList/26"/> <Description>Example Corporations Finance Organization</Description>
96
VMware, Inc.
Response:
200 OK Content-Type: application/vnd.vmware.vcloud.tasksList+xml ... <TasksList name="Tasks Lists" type="application/vnd.vmware.vcloud.tasksList+xml" href="http://vcloud.example.com/api/v1.0/tasksList/18" ...> <Task... status="success" ... operation="Deleted Virtual Application Template (21)" ... > ... </Task> <Task... status="error" ... operation="Powered On Virtual Machine WIn2K8 (15)" ... > <Error stackTrace="com.vmware.ssdc.library.exceptions.VimInvalidStateException The operation could not be performed because the object is in an invalid state. Current state of the the VM is VMOn. at com.vmware.vcloud.val.internal.impl.VC20VirtualServer.throwVimInvalidStateE xception(VC20VirtualServer.java:292) at ..."> ... </Task> <Task... status="running" ... operation="Deleting Virtual Application (44)" ... > ... </Task> ... </TasksList>
Modify an Organization
AsshowninExample 63,anAdminOrgbodyincludesrel="add"linksfornetworks,vDCs,users,groups, andcatalogs.Anorganizationadministratorcanusetheselinkstoaddobjectsofthosetypestothe organization.TomodifyotherattributesorelementsofanAdminOrg,anorganizationadministratorcanmake aPUTrequesttoitsrel="edit"linkandsupplyamodifiedversionoftheAdminOrgbody.Therequestin Example 66modifiesthedefaultleasesettingsoftheorganizationcreatedinExample 63. NOTEIfyoumodifyanorganizationscatalogpublishingpolicyorLDAPoptionsormodifyarole,the changesdonottakeeffectforloggedinusersuntilthecacheforthecurrentsessionexpiresortheuserlogs outandlogsinagain.
VMware, Inc.
97
Response:
200 OK Content-Type: application/vnd.vmware.admin.organization+xml ... <AdminOrg name="ExampleFinance" type="application/vnd.vmware.admin.organization+xml" ...> <Link rel="add" type="application/vnd.vmware.admin.catalog+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/catalogs"/> <Link rel="add" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/users"/> ... <Settings> ... <OrgLeaseSettings> <DeleteOnStorageLeaseExpiration>true</DeleteOnStorageLeaseExpiration> <DeploymentLeaseSeconds>1209600</DeploymentLeaseSeconds> <StorageLeaseSeconds>7776000</StorageLeaseSeconds> </OrgLeaseSettings> </Settings> ... </AdminOrg>
Response:
204 No Content
98
VMware, Inc.
Remove an Organization
AnorganizationadministratorcanusetheremovelinkinanAdminOrgbodytoremovetheorganizationfrom thevCloud.Example 68doesthis,makingaDELETErequesttotheremovelinkreturnedinExample 64. NOTEBeforeyoucanremoveanorganization,youmustdisableitanddeleteorchangeownershipofall objectsthattheorganizationusersown. Example 6-8. Remove an Organization Request:
DELETE http://vcloud.example.com/api/v1.0/admin/org/26
Response:
204 No Content
Network Administration
Anewlycreatedorganizationhasnonetworksinit.Anorganizationadministratormustcreatean organizationnetworkfromresourcesprovidedbyoneoftheexternalnetworkslistedintheNetworkselement oftheVCloudresponse(seeExample 62onpage 94).
Response:
200 OK Content-Type:pplication/vnd.vmware.admin.network+xm ... <ExternalNetwork xmlns="http://www.vmware.com/vcloud/v1" href="http://vcloud.example.com/api/v1.0/admin/network/7" name="ExternalNetwork-VC1" ...> <Description>VLAN 7</Description> <Configuration> ... </Configuration> <ProviderInfo> NETWORK:dvportgroup-1587 on com.vmware.vcloud.entity.vimserver:1043863313 </ProviderInfo> </ExternalNetwork>
VMware, Inc.
99
Response:
201 Created Content-Type: application/vnd.vmware.admin.network+xm ... <OrgNetwork xmlns="http://www.vmware.com/vcloud/v1" name="Internet" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/54" ...> <Link rel="alternate" type="application/vnd.vmware.vcloud.network+xml" href="http://vcloud.example.com/api/v1.0/network/54"/> <Link rel="edit" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/54"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/network/54"/> <Link rel="up" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0//org/26"/> <Description>Bridged to the public Internet</Description> <Tasks> <Task ... operation="Creating Network Internet (2)" ... > ... </Task> </Tasks> <Configuration> <IpScope> <IsInherited>true</IsInherited> <Gateway>10.147.122.190</Gateway> <Netmask>255.255.255.192</Netmask> <Dns1>10.115.120.71</Dns1> <DnsSuffix>example.com</DnsSuffix> <IpRanges> <IpRange> <StartAddress>10.147.122.129</StartAddress> <EndAddress>10.147.122.189</EndAddress> </IpRange> </IpRanges> <AllocatedIpAddresses/> </IpScope>
100
VMware, Inc.
Theresponseechoestherequest,andcontainssomeadditionalelements:
Response:
200 OK Content-Type: application/vnd.vmware.admin.network+xm ... <OrgNetwork xmlns="http://www.vmware.com/vcloud/v1" name="Internet" type="application/vnd.vmware.admin.network+xml" ref="http://vcloud.example.com/api/v1.0/admin/network/54" ...> ... <Description>Bridged to the public Internet</Description> ... </OrgNetwork>
VMware, Inc.
101
<IsEnabled>false</IsEnabled> <DefaultLeaseTime>3600</DefaultLeaseTime> <MaxLeaseTime>7200</MaxLeaseTime> <IpRange> <StartAddress>10.6.35.3</StartAddress> <EndAddress>10.6.255.254</EndAddress> </IpRange> </DhcpService> <FirewallService> <IsEnabled>true</IsEnabled> </FirewallService> <NatService> <IsEnabled>false</IsEnabled> <NatType>portForwarding</NatType> <Policy>allowTraffic</Policy> </NatService> </Features> </Configuration> </OrgNetwork>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Updating Network Internet (2)" ...> ... </Task>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Removing Network Internet (2)" ...> ... </Task>
vDC Administration
AnewlycreatedorganizationhasnovDCsinit.vDCadministrationinvolvesthefollowingobjects:
102
VMware, Inc.
AnadministratorcanusethevalueofthehrefattributeinanyProviderVdcReferenceasthetargetofaGET request.TheresponseisaProviderVdcbody,asshowninExample 614. Example 6-14. Examine the Contents of a Provider vDC Request:
GET http://vcloud.example.com/api/v1.0/admin/providervdc/2
Response:
200 OK Content-Type: application/vnd.vmware.admin.providervdc+xml ... <ProviderVdc xmlns="http://www.vmware.com/vcloud/v1" status="1" name="PVDC_VC2" type="application/vnd.vmware.admin.providervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2" ... > <Link rel="up" href="http://vcloud.example.com/api/v1.0/admin/"/> <Link rel="down" type="application/vnd.vmware.admin.vdcReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2/vdcReferences"/> <Description>PVDC_VC2</Description> <ComputeCapacity> <Cpu> <Units>MHz</Units> <Allocation>21929</Allocation> <Total>24675</Total> <Used>10053</Used> <Overhead>384</Overhead> </Cpu> <Memory> <Units>MB</Units> <Allocation>16207</Allocation> <Total>24475</Total> <Used>15771</Used> <Overhead>977</Overhead> </Memory> </ComputeCapacity> <StorageCapacity> <Units>MB</Units> <Allocation>1311368</Allocation> <Total>2097152</Total> <Used>489361</Used> <Overhead>2436</Overhead> </StorageCapacity> <AvailableNetworks> <Network type="application/vnd.vmware.admin.network+xml" name="External Network VC2" href="http://vcloud.example.com/api/v1.0/admin/network/54"/> </AvailableNetworks> <IsEnabled>true</IsEnabled> <NetworkPoolReferences> <NetworkPoolReference type="application/vnd.vmware.admin.networkPool+xml" name="VC2-Direct" href="http://vcloud.example.com/api/v1.0/admin/extension/ networkPool/22"/>
VMware, Inc.
103
Response:
<VdcReferences xmlns="http://www.vmware.com/vcloud/v1" ... > <Link rel="up" type="application/vnd.vmware.admin.providervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> <VdcReference type="application/vnd.vmware.admin.vdc+xml" name="org3vdc1" href="http://vcloud.example.com/api/v1.0/admin/vdc/44"/> </VdcReferences>
104
VMware, Inc.
<Units>MHz</Units> <Allocated>2048</Allocated> <Limit>2048</Limit> </Cpu> <Memory> <Units>MB</Units> <Allocated>2048</Allocated> <Limit>2048</Limit> </Memory> </ComputeCapacity> <NicQuota>0</NicQuota> <NetworkQuota>0</NetworkQuota> <ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="Main Provider" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> </AdminVdc>
Response:
201 Created Content-Type: application/vnd.vmware.admin.vdc+xm ... <AdminVdc name="org26vdc1" type="application/vnd.vmware.admin.vdc+xml" href="http://vcloud.example.com/api/v1.0/admin/vdc/44" ...> <Link rel="up" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26"/> <Link rel="edit" type="application/vnd.vmware.admin.vdc+xml" href="http://vcloud.example.com/api/v1.0/admin/vdc/44"/> <Link rel="disable" href="http://vcloud.example.com/api/v1.0/admin/vdc/44/action/disable"/> <Link rel="alternate" href="http://vcloud.example.com/api/v1.0/vdc/44"/> <Description>Example vDC</Description> <Tasks> <Task status="running" ... operation="Creating Virtual Datacenter (44)" ...> ... </Task> </Tasks> <AllocationModel>AllocationPool</AllocationModel> <StorageCapacity> <Units>MB</Units> <Allocated>3072</Allocated> <Limit>4096</Limit> </StorageCapacity> <ComputeCapacity> <Cpu> <Units>MHz</Units> <Allocated>2048</Allocated> <Limit>2048</Limit> </Cpu> <Memory> <Units>MB</Units> <Allocated>2048</Allocated> <Limit>2048</Limit> </Memory> </ComputeCapacity> <ResourceEntities/> <AvailableNetworks> <Network type="application/vnd.vmware.admin.network+xml" name="Internet" href="http://vcloud.example.com/api/v1.0/admin/network/54"/> </AvailableNetworks> <NicQuota>0</NicQuota> <NetworkQuota>0</NetworkQuota> <ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="Main Provider" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> </AdminVdc>
VMware, Inc.
105
Modify a vDC
TomodifyavDC,makeaPUTrequesttoitseditlink,andsupplyamodifiedversionoftheVdcbody.In Example 617,theclientmodifiesthevDCcreatedinExample 63tochangethevaluesintheCpuelement,then includesthemodifiedbodyinaPUTrequesttotheeditlinkthatwasreturnedwhenthevDCwascreated. Theresponse,onlypartofwhichisshownintheexample,isanAdminVdcbodycontainingthemodified values. Example 6-17. Modify a vDC Request:
PUT http://vcloud.example.com/api/v1.0/admin/vdc/44 Content-Type: application/vnd.vmware.admin.vdc+xm <AdminVdc name="org3vdc1" xmlns="http://www.vmware.com/vcloud/v1"> <Description>Example vDC</Description> <AllocationModel>AllocationPool</AllocationModel> <StorageCapacity> <Units>MB</Units> <Allocated>4096</Allocated> <Limit>8192</Limit> </StorageCapacity> <ComputeCapacity> <Cpu> <Units>MHz</Units> <Allocated>4096</Allocated> <Limit>4096</Limit> </Cpu> <Memory> <Units>MB</Units> <Allocated>2048</Allocated> <Limit>4096</Limit> </Memory> </ComputeCapacity> <NicQuota>0</NicQuota> <NetworkQuota>0</NetworkQuota> <ProviderVdcReference type="application/vnd.vmware.admin.providervdc+xml" name="Main Provider" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> </AdminVdc>
Response:
200 OK Content-Type: application/vnd.vmware.admin.vdc+xm ... <AdminVdc name="org26vdc1" type="application/vnd.vmware.admin.vdc+xml" href="http://vcloud.example.com/api/v1.0/admin/vdc/44" ...> ... <Tasks> <Task status="running" ... operation="Updating Virtual Datacenter (44)"...> ... </Task> </Tasks>
106
VMware, Inc.
<ComputeCapacity> <Cpu> <Units>MHz</Units> <Allocated>4096</Allocated> <Limit>4096</Limit> </Cpu> ... </ComputeCapacity> ... </AdminVdc>
Remove a vDC
BeforeyoucanremoveavDC,youmustdisableit.AfterthevDChasbeendisabled,itsrepresentationincludes arel="remove"link.AnadministratorcanmakeaDELETErequesttothatlinktoremoveavDCfroman organization. Example 6-18. Remove a vDC Request:
DELETE http://vcloud.example.com/api/v1.0/admin/vdc/6
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Deleted Virtual Datacenter (6)" ...> ... </Task>
Catalog Administration
Anewlycreatedorganizationhasnocatalogsinit.Anorganizationadministratormustcreatethemand specifytheirscopebeforeitemscanbecatalogued.Youdonothavetobeanadministratortoaddorremove CatalogItemelements.SeeCatalogingvAppTemplatesandMediaImagesonpage 54.
Create a Catalog
EveryorganizationhasanaddURLforcatalogs.AnadministratorcancreateacatalogbyPOSTingaCatalog bodytothisURL.Example 619doesthis,usingtheURLinthisLinkshowninExample 63.
<Link rel="add" type="application/vnd.vmware.admin.catalog+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26/catalogs"/>
Theresponseechoestherequest,andincludestheseadditionscreatedbytheserver.
VMware, Inc.
107
ATaskthattracksthecreationofthecatalog AnIsPublishedelementwhosecontentisthestringfalse.
Response:
201 Created Content-Type: application/vnd.vmware.admin.catalog+xml ... <Catalog href="http://vcloud.example.com/api/v1.0/catalog/32" name="Custom Catalog" ...> <Description>Custom Catalog</Description> <Tasks> <Task ...> ... <Task> <Tasks> <Link rel="up" type="application/vnd.vmware.admin.organization+xml" href="http://vcloud.example.com/api/v1.0/admin/org/26"/> <Link rel="alternate" href="http://vcloud.example.com/api/v1.0/catalog/32"/> <Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/catalogItems"/> <Link rel="edit" type="application/vnd.vmware.vcloud.catalog+xml" href="http://vcloud.example.com/api/v1.0/catalog/32"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/catalog/32"/> <Link rel="publish" href="http://vcloud.example.com/api/v1.0/catalog/32/action/publish"/> <CatalogItems/> <IsPublished>false</IsPublished> </Catalog>
Response:
200 OK Content-Type: application/vnd.vmware.admin.catalog+xml ... <Catalog .... > ... <Link rel="edit" href="http://vcloud.example.com/api/v1.0/admin/catalog/32"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/catalog/32"/>
108
VMware, Inc.
Publish a Catalog
PublishingacatalogmakesthecatalogvisibletoallorganizationsinavCloud.Anadministratorofan organizationthatcanpublishcatalogs(onewhoseCanPublishCatalogselementhasavalueoftrue)can publishacatalogbymakingaPOSTrequesttothecatalogspublishURLandsupplyinga PublishCatalogParamsbodythatsetsthevalueofthecatalogsIsPublishedelementtotrue.Example 621 publishesthecatalogcreatedinExample 619. Example 6-21. Publish a Catalog Request:
POST http://vcloud.example.com/api/v1.0/admin/catalog/32/action/publish Content-Type: application/vnd.vmware.admin.publishCatalogParams+xml ... <PublishCatalogParams xmlns="http://www.vmware.com/vcloud/v1"> <IsPublished>true</IsPublished> </PublishCatalogParams>
Response:
204 No Content
Response:
200 OK Content-Type: application/vnd.vmware.admin.catalog+xml <Catalog href="http://vcloud.example.com/api/v1.0/catalog/32" name="TechOps Catalog 01" ...> <Description>TechOps Approved Templates Catalog</Description> <Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalog/32/catalogItems"/>
VMware, Inc.
109
<CatalogItems> <CatalogItem name="Ubuntu Template with vsftpd" type="application/vnd.vmware.vcloud.catalogItem+xml" href="http://vcloud.example.com/api/v1.0/catalogItem/221"> <Description>Approved template for public FTP sites</Description> <Entity href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-111"/> <Property key="Owner">Tech Ops</Property> </CatalogItem> </CatalogItems> </Catalog>
Remove a Catalog
AnadministratorcanremoveacatalogbymakingaDELETErequesttothecatalogsrel="remove"URL. Example 623removesthecatalogcreatedinExample 619. Example 6-23. Remove a Catalog Request:
DELETE http://vcloud.example.com/api/v1.0/admin/catalog/32
Response:
204 No Content
User Administration
UserscanbecreatedinanorganizationorimportedintotheorganizationfromanLDAPdirectoryservice.
110
VMware, Inc.
Response:
201 Created Content-Type: application/vnd.vmware.admin.user+xml ... <User name="ExampleUser" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85" ...> <Link rel="edit" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85"/> <FullName>Example User Full Name</FullName> <EmailAddress>user@example.com</EmailAddress> <IsEnabled>true</IsEnabled> <IsAlertEnabled>false</IsAlertEnabled> <IsDefaultCached>false</IsDefaultCached> <StoredVmQuota>0</StoredVmQuota> <DeployedVmQuota>0</DeployedVmQuota> <Role type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/105"/> <GroupReferences/> </User>
ToimportauserfromanLDAPdirectoryservice,POSTaUserbodywhosenameattributespecifiestheusers nameintheLDAPdirectory,andincludesanIsExternalelementwithavalueoftrue.Theservermatches thevalueofthenameattributeintherequestbodywiththevalueoftheLDAPattributethattheorganization hasspecifiedfortheusername(thevalueoftheUserNameelementinUserAttributes),andimportsthatuser fromLDAP.SeeUserAttributesonpage 184. Example 625illustratesthissortofrequest. Example 6-25. Import a User from LDAP Request:
POST http://vcloud.example.com/api/v1.0/admin/org/26/users Content-Type: application/vnd.vmware.admin.user+xml ... <User name="user@example.com" type="application/vnd.vmware.admin.user+xml" xmlns="http://www.vmware.com/vcloud/v1"> <IsExternal>true</IsExternal> <Role type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/105"/> </User>
Response:
201 Created Content-Type: application/vnd.vmware.admin.user+xml ... <User name="user@example.com" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85" ...> <Link rel="edit" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85"/> <FullName>Example User</FullName> <EmailAddress>user@example.com</EmailAddress> <IsEnabled>false</IsEnabled> <IM/> <NameInSource>\F4\D3\42\8E\6A\BC\D3</NameInSource> <IsAlertEnabled>false</IsAlertEnabled> <IsDefaultCached>false</IsDefaultCached> <StoredVmQuota>0</StoredVmQuota> <DeployedVmQuota>0</DeployedVmQuota> <Role type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/105"/> <GroupReferences/> </User>
VMware, Inc.
111
Response:
200 OK Content-Type: application/vnd.vmware.admin.user+xml ... <User name="user@example.com" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85" ...> <Link rel="edit" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85"/> <FullName>Example User Full Name</FullName> <EmailAddress>user@example.com</EmailAddress> <Telephone/> <IsEnabled>true</IsEnabled> <IM/> <NameInSource>user@example.com</NameInSource> <IsAlertEnabled>false</IsAlertEnabled> <IsDefaultCached>false</IsDefaultCached> <StoredVmQuota>1000</StoredVmQuota> <DeployedVmQuota>100</DeployedVmQuota> <Role type="application/vnd.vmware.admin.role+xml" name="User" href="http://vcloud.example.com/api/v1.0/admin/role/1"/> <GroupReferences/> </User>
112
VMware, Inc.
Response:
200 OK Content-Type: application/vnd.vmware.admin.user+xml ... <User name="user@example.com" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85" ...> <Link rel="edit" type="application/vnd.vmware.admin.user+xml" href="http://vcloud.example.com/api/v1.0/admin/user/85"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/user/85"/> <FullName>Example User Full Name</FullName> <EmailAddress>user@example.com</EmailAddress> <Role type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/105"/> <IsEnabled>false</IsEnabled> </User>
Remove a User
Beforeyoucanremoveauser,youmustdisabletheUserobjectbychangingthevalueofitsIsEnabled elementtofalse,asshowninExample 627.Afterithasbeendisabled,theUserelementcontainsalink whererel="remove".Anadministratorcanusethislinkremovetheuserfromtheorganization,asshownin Example 628. Example 6-28. Remove a User Request:
DELETE http://vcloud.example.com/api/v1.0/admin/user/85
Response:
204 No Content
Group Administration
GroupsmustbeimportedfromLDAP.YoucannotusethevCloudAPItoaddorremovegroupmembers,or changethenameofthegroup.Instead,youmustmakethechangesinthesourceLDAPdatabaseandthen importthegroupagain.
Import a Group
ToimportagroupfromanLDAPdirectoryservice,POSTanemptyGroupbodytotheorganizationsaddURL forgroups.Thevalueofthenameattributeintherequestbodymustmatchthevalueofthegroupsname attributeinLDAP. Example 6-29. Import a Group from LDAP Request:
POST http://vcloud.example.com/api/v1.0/admin/org/26/groups Content-Type: application/vnd.vmware.admin.group+xml <Group name="Engineering" xmlns="http://www.vmware.com/vcloud/v1"> <Role type="application/vnd.vmware.admin.role+xml" name="vApp Wrangler" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> </Group>
VMware, Inc.
113
Response:
201 Created Content-Type: application/vnd.vmware.admin.user+xml ... <Group name="Engineering" type="application/vnd.vmware.admin.group+xml" href="http://vcloud.example.com/api/v1.0/admin/group/44" ...> <Link rel="edit" type="application/vnd.vmware.admin.group+xml" href="http://vcloud.example.com/api/v1.0/admin/group/44"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/group/44"/> <Description>Research and development</Description> ... <UsersList/> <Role type="application/vnd.vmware.admin.role+xml" name="vApp Wrangler" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> </Group>
Remove a Group
AnadministratorcanusetheremovelinkinaGroupbodytoremoveagroupfromavCloud.Example 630 removesthegroupimportedinExample 629. Example 6-30. Remove a Group Request:
DELETE http://vcloud.example.com/api/v1.0/admin/group/44
Response:
204 No Content
Role Administration
Aroleassociatesthenameofauserorgroupwithasetofrights.RolenamesmustbeuniqueinavCloud instance.
Create a Role
AsystemadministratorcancreatearolebyaggregatingasetofrightsinaRolebody,andthenPOSTingthe bodytotheaddURLforroles.Example 631createsanewrolenamedvAppWranglerandaddsittothe vCloudshowninExample 62.Theresponse,likeotherresponsestorequeststhatcreateanobject,includes thePOSTedcontent,alinktothenewobject,andlinksoftypeeditandremovethatanadministratorcanuse tomanagethisrole.
114
VMware, Inc.
Response:
201 Created Content-Type: application/vnd.vmware.admin.role+xml ... <Role name="vAppWrangler" type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/102" ...> <Link rel="edit" type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> <Description>Create and manage vApps</Description> <RightReferences> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: View" href="http://vcloud.example.com/api/v1.0/admin/right/16"/> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: Power Operations" href="http://vcloud.example.com/api/v1.0/admin/right/9"/> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: Download" href="http://vcloud.example.com/api/v1.0/admin/right/11"/> <RightReference ... /> ... </RightReferences> </Role>
Response:
200 OK Content-Type: application/vnd.vmware.admin.role+xml ... <Role name="vApp Wrangler" type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/102" ...>
VMware, Inc.
115
<Link rel="edit" type="application/vnd.vmware.admin.role+xml" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> <Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/role/102"/> <Description>Create and manage vApps</Description> <RightReferences> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: View" href="http://vcloud.example.com/api/v1.0/admin/right/16"/> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: Power Operations" href="http://vcloud.example.com/api/v1.0/admin/right/9"/> <RightReference type="application/vnd.vmware.admin.right+xml" name="vApp: Download" href="http://vcloud.example.com/api/v1.0/admin/right/11"/> <RightReference ... /> ... </RightReferences> </Role>
Modify a Role
AsystemadministratorcanmodifyaroletoaddorremoverightsorchangethenameoftherolebyPUTting amodifiedRolebodytotheeditURLoftheRole.SeeExample 627foranexampleoftheworkflowforthis typeofrequest.
Remove a Role
AsystemadministratorcanusetheremovelinkinaRoleelementtoremovearolefromavCloud. Example 633removestherolecreatedinExample 631. Example 6-33. Remove a Role Request:
DELETE http://vcloud.example.com/api/v1.0/admin/role/102
Response:
204 No Content
View a Right
Asystemadministratorcanview,butnotmodify,thecontentsofaRightelement,asshowninExample 634, whichprovidesaviewofoneoftheRightReferencesshowninExample 62. Example 6-34. View a Right Request:
GET http://vcloud.example.com/api/v1.0/admin/right/7
Response:
200 OK Content-Type: application/vnd.vmware.admin.right+xml ... <Right xmlns="http://www.vmware.com/vcloud/v1" name="Catalog: Sharing" type="application/vnd.vmware.admin.right+xml" href="http://vcloud.example.com/api/v1.0/admin/right/7" ... > <Description>Share a Catalog</Description> <Category>catalog</Category> </Right>
116
VMware, Inc.
SummaryofvSpherePlatformOperationsRequestsonpage 117 ListvSpherePlatformOperationsandObjectsforavCloudonpage 119 ListProvidervDCsinavCloudonpage 120 ListNetworkPoolsinavCloudonpage 120 ListvCenterServersRegisteredtoavCloudonpage 120 ListESX/ESXiHostsinavCloudonpage 124 CreateaProvidervDConpage 127 CreateanExternalNetworkonpage 133 CreateaNetworkPoolonpage 136 ImportaVirtualMachinefromvCenteronpage 138
APIURLisaURLoftheformhttp://vcloud.example.com/api/v1.0. idisaninteger.
ListvSpherePlatform GETAPIURL/admin/extension OperationsandObjects foravCloud ListProvidervDCsina GETAPIURL/admin/extension/ vCloud providerVdcReferences ListExternalNetworks GETAPIURL/admin/extension/ inavCloud externalNetworkReferences
None None
VMWProviderVdcReferences VMWExternalNetworkReferences
VMware, Inc.
117
GetInformationAbout GETAPIURL/admin/extension/ avCenterServer vimServer/id ListAvailableResource GETAPIURL/admin/extension/ vimServer/id/resourcePoolList PoolsonavCenter Server ModifyvCenterServer PUTAPIURL/admin/extension/ Settings vimServer/id/ RegisteravCenter ServerandvShield Manager UnregisteravCenter ServerandvShield Manager POSTAPIURL/admin/extension/ action/registervimserver POSTAPIURL/admin/extension/ vimServer/id/action/unregister
VimServer RegisterVimServerParams
Task RegisterVimServerParams
None
Task
None
204NoContent
GetInformationAbout GETAPIURL/admin/extension/ aHost host/id PrepareaHost UnprepareaHost EnableorDisablea Host POSTAPIURL/admin/extension/ host/id/action/prepare POSTAPIURL/admin/extension/ host/id/action/unprepare POSTAPIURL/admin/extension/ host/id/action/enable POSTAPIURL/admin/extension/ host/id/action/disable RepairaHost UpgradeaHostAgent CreateaProvidervDC ExaminethevSphere ObjectsinaProvider vDC ModifyaProvidervDC EnableorDisablea ProvidervDC POSTAPIURL/admin/extension/ host/id/action/repair POSTAPIURL/admin/extension/ host/id/action/upgrade POSTAPIURL/admin/extension/ providervdcs GETAPIURL/admin/extension/ providervdc/id PUTAPIURL/admin/extension/ providervdcs POSTAPIURL/admin/extension/ providervdc/id/action/enable POSTAPIURL/admin/extension/ providervdc/id/action/disable DELETE APIURL/admin/extension/ providervdc/id POSTAPIURL/admin/extension/ externalnets
VMWProviderVdc None
VMWProviderVdc 204NoContent
None
Task
VMWExternalNetwork
VMWExternalNetwork
118
VMware, Inc.
GetInformationAbout GETAPIURL/admin/extension/ anExternalNetwork externalnet/id ModifyanExternal Network RemoveanExternal Network CreateaNetworkPool PUTAPIURL/admin/extension/ externalnet/id DELETE APIURL/admin/extension/ externalnet/id POSTAPIURL/admin/extension/ networkPools
GetInformationAbout GETAPIURL/admin/extension/ aNetworkPool networkPool/id ModifyaNetworkPool RemoveaNetwork Pool ImportaVirtual MachineasavApp ImportaVirtual MachineasavApp Template PUTAPIURL/admin/extension/ networkPool/id PUTAPIURL/admin/extension/ networkPool/id POSTAPIURL/admin/extension/ vimServer/id/importVmAsVapp POSTAPIURL/admin/extension/ vimServer/id/ importVmAsVappTemplate
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmwextension+xml ... <vmext:VMWExtension xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" ... > <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwProviderVdcReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/ providerVdcReferences"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwExternalNetworkReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/ externalNetworkReferences"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwNetworkPoolReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/ networkPoolReferences"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwVimServerReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/ vimServerReferences"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmwHostReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/hostReferences"/> <vcloud:Link rel="add" type="application/vnd.vmware.admin.vmwprovidervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdcs"/> <vcloud:Link rel="add" type="application/vnd.vmware.admin.vmwexternalnet+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnets"/>
VMware, Inc.
119
<vcloud:Link rel="add" type="application/vnd.vmware.admin.networkPool+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPools"/> <vcloud:Link rel="register" type="application/vnd.vmware.admin.registerVimServerParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/action/ registervimserver"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.licensingReportList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/licensing/reports"/> </vmext:VMWExtension>
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmwprovidervdcreferences+xml ... <vmext:VMWProviderVdcReferences xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" ... > <vcloud:Link rel="up" type="application/vnd.vmware.admin.vmwExtension+xml" href="http://vcloud.example.com/api/v1.0/admin/extension"/> <vmext:ProviderVdcReference type="application/vnd.vmware.admin.vmwprovidervdc+xml" name="PVDC-VC3" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/1"/> <vmext:ProviderVdcReference ... > <vmext:ProviderVdcReference ... > </vmext:VVMWProviderVdcReferences>
120
VMware, Inc.
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmwvirtualcenter+xml ... <vmext:VimServer xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="VC-02" ... > <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmsObjectRefsList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/ vmsList"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.resourcePoolList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/ resourcePoolList"/> <vcloud:Link rel="add" type="application/vnd.vmware.admin.importVmAsVAppParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/ importVmAsVApp"/> <vcloud:Link rel="add" type="application/vnd.vmware.admin.importVmAsVAppTemplateParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/ importVmAsVAppTemplate"/> <vcloud:Link rel="unregister" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/action/ unregister"/> <vcloud:Description>vCenter created by the Configuration Wizard</vcloud:Description> <vmext:Username>administrator</vmext:Username> <vmext:Url>http://10.147.40.234:443</vmext:Url> <vmext:IsEnabled>true</vmext:IsEnabled> <vmext:ShieldManagerIP>10.147.44.59</vmext:ShieldManagerIP> <vmext:ShieldManagerUserName>admin</vmext:ShieldManagerUserName> </vmext:VimServer>
Response:
200 OK Content-Type: application/vnd.vmware.admin.resourcepoollist+xml ... <vmext:ResourcePoolList xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" ...> <vcloud:Link rel="up" type="application/vnd.vmware.admin.vmwvirtualcenter+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/> <vmext:ResourcePool name="Cluster-1"> <vmext:MoRef>resgroup-1159</vmext:MoRef> <vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType> <vmext:DataStoreRefs/> </vmext:ResourcePool> <vmext:ResourcePool name="Cluster-2"> <vmext:MoRef>resgroup-1064</vmext:MoRef>
VMware, Inc.
121
<vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType> <vmext:DataStoreRefs> <vmext:VimObjectRef> <vmext:MoRef>datastore-10</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> <vmext:VimObjectRef> <vmext:MoRef>datastore-11</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> <vmext:VimObjectRef> <vmext:MoRef>datastore-12</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> </vmext:DataStoreRefs> </vmext:ResourcePool> </vmext:ResourcePoolList>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Updating VirtualCenter (100)" ...> ... </Task>
122
VMware, Inc.
Response:
200 OK Content-Type: application/vnd.vmware.admin.registerVimServerParams+xml ... <vmext:RegisterVimServerParams xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" type="application/vnd.vmware.admin.vmwprovidervdc+xml"> <vmext:VimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC-22" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"> <vmext:Username>Administrator</vmext:Username> <vmext:Url>https://10.100.121.123:443</vmext:Url> <vmext:IsEnabled>false</vmext:IsEnabled> </vmext:VimServer> <vmext:ShieldManager> <vmext:AssociatedVimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VSM-VC-22" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/> <vmext:Username>Administrator</vmext:Username> <vmext:Url>https://10.100.121.66</vmext:Url> </vmext:ShieldManager> </vmext:RegisterVimServerParams>
VMware, Inc.
123
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... > ... </Task>
Response:
204 No Content
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmwhostreferences+xml ... <vmext:VMWHostReferences xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" ... > <vcloud:Link rel="up" type="application/vnd.vmware.admin.vmwExtension+xml" href="http://vcloud.example.com/api/v1.0/admin/extension"/> <vmext:HostReference type="application/vnd.vmware.admin.host+xml" name="10.115.121.12" href="http://vcloud.example.com/api/v1.0/admin/extension/host/180"/> <vmext:HostReference ... > <vmext:HostReference ... > </vmext:VMWHostReferences>
124
VMware, Inc.
Response:
200 OK Content-Type: application/vnd.vmware.admin.host+xml ... <vmext:Host xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="10.115.121.14" href="http://vcloud.example.com/api/v1.0/admin/extension/host/22" ... > <vcloud:Link rel="disable" href="http://vcloud.example.com/api/v1.0/admin/extension/host/22/action/disable"/> <vcloud:Description/> <vmext:Ready>true</vmext:Ready> <vmext:Available>true</vmext:Available> <vmext:Enabled>true</vmext:Enabled> <vmext:Busy>false</vmext:Busy> <vmext:EnableHostForHostSpanning>true</vmext:EnableHostForHostSpanning> <vmext:CpuType>Intel(R) Xeon(R) CPU E5310 @ 1.60GHz</vmext:CpuType> <vmext:NumOfCpusPackages>2</vmext:NumOfCpusPackages> <vmext:NumOfCpusLogical>8</vmext:NumOfCpusLogical> <vmext:CpuTotal>1600</vmext:CpuTotal> <vmext:MemUsed>0.0</vmext:MemUsed> <vmext:MemTotal>8187.5546875</vmext:MemTotal> <vmext:HostOsName>VMware ESXi</vmext:HostOsName> <vmext:HostOsVersion>4.0.0</vmext:HostOsVersion> <vmext:VimPropertyPageUrl> vpxclient://7416E531-05B9-4C1F-854D-97EF7C546CB0::HostSystem:host-20/ </vmext:VimPropertyPageUrl> <vmext:VmMoRef>host-20</vmext:VmMoRef> </vmext:Host>
Prepare a Host
WhenyouaddahosttoavSphereclusterthatCloudDirectoruses,youmustpreparethehostbeforea providervDCcanusethehostsresources. Youcannotprepareahostthatisinlockdownmode.Afteryouprepareahost,youcanenablelockdownmode. AsystemadministratorcanprepareahostbymakingaPOSTrequesttothehostsaction/prepareURLand supplyingaPrepareHostParamsrequestbodythatincludestheusernameandpasswordofahost administrator,asshowninExample 711. Example 7-11. Prepare a Host Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/prepare Content-Type: application/vnd.vmware.admin.prepareHostParams+xml ... <vmext:PrepareHostParams xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" type="application/vnd.vmware.admin.vmwprovidervdc+xml"> <vmext:Username>Administrator</vmext:Username> <vmext:Password>Pa55w0rd</vmext:Password> </vmext:PrepareHostParams>
VMware, Inc.
125
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Preparing Host (1)" ...> ... </Task>
Unprepare a Host
UnprepareahosttomakeitunavailableforuseintheCloudDirectorenvironment.Asystemadministrator canunprepareahostbymakingaPOSTrequesttothehostsaction/unprepareURL.Example 712 unpreparesthehostreferencebyhttp://vcloud.example.com/api/v1.0/admin/extension/host/1. Example 7-12. Unprepare a Host Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/host/1/action/unprepare
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... > ... </Task>
Response:
204 No Content
Repair a Host
IftheCloudDirectoragentonahostcannotbecontacted,asystemadministratorcantrytorepairthehost POSTrequesttothehostsaction/repairURL.Example 714upgradesthehostagentforthehostreferenced byhttp://vcloud.example.com/api/v1.0/admin/extension/host/1.
126
VMware, Inc.
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... > ... </Task>
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Upgrading Host (1)" ...> ... </Task>
VMware, Inc.
127
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmwvirtualcenter+xml ... <vmext:VimServer xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101" ...> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vmsObjectRefsList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/ vmsList"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.resourcePoolList+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/ resourcePoolList"/> <vcloud:Link rel="add" type="application/vnd.vmware.admin.importVmAsVAppParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/ importVmAsVApp"/> <vcloud:Link rel="add" type="application/vnd.vmware.admin.importVmAsVAppTemplateParams+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/ importVmAsVAppTemplate"/> <vcloud:Link rel="edit" type="application/vnd.vmware.admin.vmwvirtualcenter+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> <vcloud:Link rel="unregister" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/action/ unregister"/> <vcloud:Link rel="reconnect" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101/action/ forcevimserverreconnect"/> <vmext:Username>administrator</vmext:Username> <vmext:Url>https://10.147.20.155:443</vmext:Url> <vmext:IsEnabled>true</vmext:IsEnabled> <vmext:ShieldManagerIP>10.147.41.67</vmext:ShieldManagerIP> <vmext:ShieldManagerUserName>admin</vmext:ShieldManagerUserName> </vmext:VimServer>
Response:
200 OK Content-Type: application/vnd.vmware.admin.resourcepoollist+xml ... <vmext:ResourcePoolList xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" ... > <vcloud:Link rel="up" type="application/vnd.vmware.admin.vmwvirtualcenter+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> <vmext:ResourcePool name="gasare-vc2-rp"> <vmext:MoRef>resgroup-3582</vmext:MoRef> <vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType> <vmext:DataStoreRefs> <vmext:VimObjectRef> <vmext:MoRef>datastore-418</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> <vmext:VimObjectRef>
128
VMware, Inc.
<vmext:MoRef>datastore-322</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> <vmext:VimObjectRef> <vmext:MoRef>datastore-350</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> </vmext:DataStoreRefs> </vmext:ResourcePool> </vmext:ResourcePoolList>
YoucanusethisinformationtogetvaluesfortheDataStoreRefsandResourcePoolRefelementsinthe VMWProviderVdc,thenPOSTtheVMWProviderVdcbodytotherel="add"linkforprovidervdcsinthe VMWExtensionelement,asshowninExample 718. Example 7-18. Create a Provider vDC Request:
POST http://vcloud.example.com/api/v1.0/admin/extension/providervdcs Content-Type: application/vnd.vmware.admin.vmwprovidervdc+xml ... <vmext:VMWProviderVdc xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="PvDC-VC2" type="application/vnd.vmware.admin.vmwprovidervdc+xml"> <vcloud:Description>New Provider vDC</vcloud:Description> <vcloud:ComputeCapacity> <vcloud:Cpu> <vcloud:Units>MHz</vcloud:Units> <vcloud:Allocation>2241</vcloud:Allocation> <vcloud:Total>24675</vcloud:Total> </vcloud:Cpu> <vcloud:Memory> <vcloud:Units>MB</vcloud:Units> <vcloud:Allocation>1319056</vcloud:Allocation> <vcloud:Total>2097152</vcloud:Total> </vcloud:Memory> </vcloud:ComputeCapacity> <vcloud:StorageCapacity> <vcloud:Units>MB</vcloud:Units> <vcloud:Allocation>18944</vcloud:Allocation> <vcloud:Total>2260224</vcloud:Total> </vcloud:StorageCapacity> <vmext:DataStoreRefs> <vmext:VimObjectRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/ 101"/> <vmext:MoRef>datastore-418</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> </vmext:DataStoreRefs> <vmext:ResourcePoolRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> <vmext:MoRef>resgroup-220</vmext:MoRef> <vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType> </vmext:ResourcePoolRef> <vmext:VimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> </vmext:VMWProviderVdc>
Response:
201 Created Content-Type: application/vnd.vmware.admin.vmwprovidervdc+xml
VMware, Inc.
129
... <vmext:VMWProviderVdc xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" status="0" name="PvDC-VC2" xmlns:vcloud="http://www.vmware.com/vcloud/v1" type="application/vnd.vmware.admin.vmwprovidervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2"> <vcloud:Link rel="enable" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2/action/ enable"/> <vcloud:Link rel="edit" type="application/vnd.vmware.admin.vmwprovidervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2"/> <vcloud:Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/extension/providervdc/2"/> <vcloud:Link rel="alternate" type="application/vnd.vmware.admin.providervdc+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2"/> <vcloud:Link rel="down" type="application/vnd.vmware.admin.vdcReferences+xml" href="http://vcloud.example.com/api/v1.0/admin/providervdc/2/vdcReferences"/> <vcloud:Description>New Provider vDC</vcloud:Description> <vcloud:Tasks> <vcloud:Task ... operation="Creating Provider Virtual Datacenter PvDC-VC2(2)" ... > ... </vcloud:Task> </vcloud:Tasks> <vcloud:Description>PVDC_VC2</vcloud:Description> <vcloud:ComputeCapacity> <vcloud:Cpu> <vcloud:Units>MHz</vcloud:Units> <vcloud:Allocation>21929</vcloud:Allocation> <vcloud:Total>24675</vcloud:Total> <vcloud:Used>10053</vcloud:Used> <vcloud:Overhead>384</vcloud:Overhead> </vcloud:Cpu> <vcloud:Memory> <vcloud:Units>MB</vcloud:Units> <vcloud:Allocation>16207</vcloud:Allocation> <vcloud:Total>24475</vcloud:Total> <vcloud:Used>15771</vcloud:Used> <vcloud:Overhead>977</vcloud:Overhead> </vcloud:Memory> </vcloud:ComputeCapacity> <vcloud:StorageCapacity> <vcloud:Units>MB</vcloud:Units> <vcloud:Allocation>1311368</vcloud:Allocation> <vcloud:Total>2097152</vcloud:Total> <vcloud:Used>489361</vcloud:Used> <vcloud:Overhead>2436</vcloud:Overhead> </vcloud:StorageCapacity> <vcloud:AvailableNetworks> <vcloud:Network type="application/vnd.vmware.admin.network+xml" name="External Network VC2" href="http://vcloud.example.com/api/v1.0/admin/network/7"/> </vcloud:AvailableNetworks> <vcloud:IsEnabled>false</vcloud:IsEnabled> <vcloud:NetworkPoolReferences> <vcloud:NetworkPoolReference type="application/vnd.vmware.admin.networkPool+xml" name="s-org-vdc-vc2-DirectNET" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/ 22"/> <vcloud:NetworkPoolReference type="application/vnd.vmware.admin.networkPool+xml" name="Netpool_VC2_VLAN_Backed" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/2"/> </vcloud:NetworkPoolReferences> <vmext:DataStoreRefs> <vmext:VimObjectRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/ 101"/> <vmext:MoRef>datastore-418</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType>
130
VMware, Inc.
</vmext:VimObjectRef> </vmext:DataStoreRefs> <vmext:ResourcePoolRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> <vmext:MoRef>resgroup-220</vmext:MoRef> <vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType> </vmext:ResourcePoolRef> <vmext:VimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> <vmext:HostReferences> <vmext:HostReference type="application/vnd.vmware.admin.host+xml" name="10.115.121.11" href="http:// vcloud.example.com/api/v1.0/admin/extension/host/1"/> <vmext:HostReference type="application/vnd.vmware.admin.host+xml" name="10.115.121.9" href="http:// vcloud.example.com/api/v1.0/admin/extension/host/2"/> </vmext:HostReferences> </vmext:VMWProviderVdc>
VMware, Inc.
131
</vcloud:Memory> </vcloud:ComputeCapacity> <vcloud:StorageCapacity> <vcloud:Units>MB</vcloud:Units> <vcloud:Allocation>18944</vcloud:Allocation> <vcloud:Total>2260224</vcloud:Total> </vcloud:StorageCapacity> <vmext:DataStoreRefs> <vmext:VimObjectRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/ 101"/> <vmext:MoRef>datastore-418</vmext:MoRef> <vmext:VimObjectType>DATASTORE</vmext:VimObjectType> </vmext:VimObjectRef> </vmext:DataStoreRefs> <vmext:ResourcePoolRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> <vmext:MoRef>resgroup-220</vmext:MoRef> <vmext:VimObjectType>RESOURCE_POOL</vmext:VimObjectType> </vmext:ResourcePoolRef> <vmext:VimServer type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="VC2" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/101"/> </vmext:VMWProviderVdc>
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmwprovidervdc+xml ... <vmext:VMWProviderVdc xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="PvDC-VC2" type="application/vnd.vmware.admin.vmwprovidervdc+xml" ... > ... </vmext:VMWProviderVdc>
Theresponse,mostofwhichisnotshownhere,echoestherequest.
Response:
204 No Content
132
VMware, Inc.
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Deleting Provider Virtual Datacenter (43)" ...> ... </Task>
VMware, Inc.
133
Response:
201 Created Content-Type: application/vnd.vmware.admin.vmwexternalnet+xml ... <vmext:VMWExternalNetwork xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="ExternalNet-VC100" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Link rel="alternate" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/27"/> <vcloud:Link rel="edit" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Description>Portgroup-25 on VC-100</vcloud:Description> <vcloud:Tasks> <vcloud:Task status="running"... operation="Creating External Network ExternalNet-VC100(27)" href="http:// vcloud.example.com/api/v1.0/task/579"/> </vcloud:Tasks> ... </vmext:VMWExternalNetwork>
TheresponseechoestherequestandincludesLinkelementsforactionsandrelatedreferences,andaTask elementthattrackscreationoftheexternalnetwork.
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmwexternalnet+xml ... <vmext:VMWExternalNetwork xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="ExternalNet-VC100" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Link rel="alternate" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/network/27"/> <vcloud:Link rel="edit" type="application/vnd.vmware.admin.network+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Link rel="remove" href="http://vcloud.example.com/api/v1.0/admin/extension/externalnet/27"/> <vcloud:Description>Portgroup-25 on VC-100</vcloud:Description> <vcloud:Configuration> ... </vcloud:Configuration> <vmext:VimPortGroupRef> <vmext:VimServerRef type="application/vnd.vmware.admin.vmwvserver+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/> <vmext:MoRef>dvportgroup-25</vmext:MoRef> <vmext:VimObjectType>NETWORK</vmext:VimObjectType> </vmext:VimPortGroupRef> </vmext:VMWExternalNetwork>
134
VMware, Inc.
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmwexternalnet+xml ... <vmext:VMWExternalNetwork xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" name="ExternalNet-VC100"> ... </vmext:VMWExternalNetwork>
VMware, Inc.
135
Response:
202 Accepted Content-Type: application/vnd.vmware.vcloud.task+xml ... <Task ... operation="Deleting External Network (27)" ...> ... </Task>
Response:
201 Created Content-Type: application/vnd.vmware.admin.networkPool+xml ... <vmext:VMWNetworkPool xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" xsi:type="vmext:VlanPoolType" name="NewVlanPool" type="application/vnd.vmware.admin.networkPool+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41" ... > <vcloud:Description>Extra pool for new Orgs</vcloud:Description> <vmext:VlanRange> <vmext:Start>100</vmext:Start> <vmext:End>120</vmext:End> </vmext:VlanRange> <vmext:VimSwitchRef>
136
VMware, Inc.
Response:
200 OK ... <vmext:VMWNetworkPool xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" xsi:type="vmext:VlanPoolType" name="NewVlanPool" type="application/vnd.vmware.admin.networkPool+xml" href="http://vcloud.example.com/api/v1.0/admin/extension/networkPool/41" ... > <vcloud:Description>Extra pool for new Org Nets</vcloud:Description> ... </vmext:VMWNetworkPool>
VMware, Inc.
137
Response:
200 OK ... <vmext:VMWNetworkPool xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" xsi:type="vmext:VlanPoolType" name="NewVlanPool"> ... <vmext:VMWNetworkPool>
Theresponse,mostofwhichisnotshownhere,echoestherequest.
Response:
204 No Content
Response:
200 OK Content-Type: application/vnd.vmware.admin.vmsobjectrefslist+xml ... <vmext:VmObjectRefsList xmlns:vmext="http://www.vmware.com/vcloud/extension/v1" xmlns:vcloud="http://www.vmware.com/vcloud/v1" ...> <vmext:VmObjectRef name="Win2K8"> <vcloud:VimServerRef type="application/vnd.vmware.admin.vmwvirtualcenter+xml" name="vCenter-PA-001" href="http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100"/> <vcloud:MoRef>vm-642</vcloud:MoRef> <vcloud:VimObjectType>VIRTUAL_MACHINE</vcloud:VimObjectType> </vmext:VmObjectRef> <vmext:VmObjectRef ...> ... </vmext:VmObjectRef> </vmext:VmObjectRefsList>
138
VMware, Inc.
where prepresentsanintegerpagenumber(startingwith1)andsrepresentsanintegerpagesize.Therequest showninExample 730couldberewrittenasshowninExample 731toreturnthefirsttenentriesinthe vmsList. Example 7-31. vmsList with Page Number and Page Size Query Request:
GET http://vcloud.example.com/api/v1.0/admin/extension/vimServer/100/vmsList?page=1&pageSize=10
Toreturnthecompletelistofvirtualmachines,makeadditionalrequeststhatincrementthevalueofpage.
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.vApp+xml <VApp status="0" name="ImportedWin2K8" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-102" ...> ... <Description/> <Tasks> <Task ... operation=Busy Virtual Application Win2K8 ...> ... </Task> </Tasks> </VApp>
VMware, Inc.
139
Response:
201 Created Content-Type: application/vnd.vmware.vcloud.vAppTemplate+xml ... <VAppTemplate status="0" name="ImportedWin2K8-Template" type="application/vnd.vmware.vcloud.vAppTemplate+xml" href="http://vcloud.example.com/api/v1.0/vAppTemplate/vappTemplate-64" ...> ... <Description/> <Tasks> <Task ... operation=Busy Virtual Application Template Win2K8 ...> ... </Task> </Tasks> </VApp>
140
VMware, Inc.
AboutObjectRepresentationsonpage 141 CommonDatatypesonpage 142 CommonAttributesonpage 143 CommonElementsonpage 146 APIVersioningonpage 147 Extensibilityonpage 148
Schema
EachvCloud APIobjectisdefinedinanXMLschemadocument.Someobjectsaredefinedintheirownschema documents.Othersaredefinedinthecontextofthelargerschemainwhichtheyareused.Stillothersare definedinacommonschemadocument,fromwhichotherschemasinherit.Thisguidepresentsreference informationaboutXMLschemasintabularform,asshowninTable 81. Table 8-1. Schema Reference Table Columns
Name Nameofanelementor attributecontained. Elementnamesbegin withanuppercase character.Attribute namesbeginwitha lowercasecharacter. Min Minimumnumberof thisattributeor elementrequiredby theschema. Max Maximumnumberof thisattributeor elementallowedbythe schema.Avalueofn meansthatthe maximumnumberis unlimited. Type Typeoftheattributeor element,eithera primitiveXML datatypeoracomplex typedefinedbythe vCloud API. Description Descriptionofthe attributeorelement
VMware, Inc.
141
NOTEInthereferencematerial,elementsthataresimplycontainersarelistedbyname,alongwithan explanationofthepurposeofthecontainer,butdonotincludeaschemareference.
Schema Validation
ThisreleaseofCloudDirectorusesavalidatingXMLparserthatrequireselementsinXMLdocumentstoagree inbothorderandnumberwiththeschema.Requiredelementsmustappearinrequestbodies.Allelements thatappearinrequestbodiesmustappearintheorderestablishedbytheschema,andwithcontentthat conformstothetypeconstraintspecifiedintheschema.Defaultvalues,wheredefined,aresuppliedfor elementsthatareempty. IfarequestcontainselementsfrommultipleXMLnamespaces,namespaceidentifiersmustbesuppliedin requestbodiesandprependedtoelementnames.SeeXMLNamespaceIdentifiersonpage 145.
Content Type
AllrequeststhathaveabodymustincludeanHTTPContentTypeheaderthatspecifiesthecontenttypeof thebody.Contenttypeshavebeendefinedforanyelementthatcanbeusedasarequestbody,andareshown alongwiththeschemaandotherreferenceinformationfortheelement.
Foreachprototype,APIURLhastheformhttp://vcloud.example.com/api/v1.0,andidisaninteger.An objecthrefprototypeisincludedinthereferenceinformationforeachobjecttypethathasanhrefattribute.
Common Datatypes
ThevCloud APIusesanumberofprimitiveXMLdatatypes,asdefinedinW3CRecommendation28 (http://www.w3.org/TR/xmlschema2/).Italsodefinesanumberofcomplextypes,ofwhichvCloud API elementsareinstances.
142
VMware, Inc.
Table 8-2. Primitive XML Data Types Used by the vCloud API (Continued)
Value xs:long xs:int xs:string Description Numericvalueintherange9223372036854775808to9223372036854775807. Numericvalueintherange2147483648to2147483647. Anycharacterdata.
Complex Types
XMLelementsdefinedbythevCloud APIareinstancesofcomplextypes.Formostelements,thecomplextype nameistheelementnameconcatenatedwiththestringType(forexample,theOrgelementisaninstanceof OrgType,thevDCelementisaninstanceofVdcType,andsoon).Inmostofthesecases,theschema representationoftheelementprovidesanadequatereferencefortheunderlyingcomplextype. Therearealsoafewgenerictypesofwhichmanydifferentkindsofelementcanbeaninstance.Becausethese typesarenotassociatedwithaparticularkindofelement,weprovideschemainformationforthemhere.
EntityType
ThisisthebasecomplextypeforelementssuchasOrg,vDC,andvApp. Schema
Name name Description Tasks Min 1 0 0 Max 1 1 1 Type xs:string xs:string TasksInProgressType Description Nameoftheobject Optionaldescriptionoftheobject ReadonlycontainerforTaskelements.Eachelementin thecontainerrepresentsaqueued,running,orfailedtask ownedbythisobject.Successfullycompletedtasksarenot listed.
IpAddressType
TheIpAddressTypeimposesapatternontheprimitivexs:stringtype.ThepatterndefinesanIPv4address:
<xs:pattern value = "((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0 -9][0-9]|[1-9][0-9]|[0-9])"/>
Attributesofthistypeareinvalidunlesstheyconformtothepattern
ReferenceType
Manycontainerelementsarepopulatedwithreferencestocontainedobjects.Eachreferenceconsistsofa hyperlink,anoptionalmediatype,andaname. Schema
Name href type name Min 1 0 0 Max 1 1 1 Type xs:anyURI xs:string xs:string Description Hyperlinktothereferencedobject Objecttype,expressedasthemediatypeoftheXML representingoftheobject Nameofthereferencedobject.
Common Attributes
ElementssuchasOrg,Catalog,andvDChaveanumberofcommonattributes.Withtheexceptionofname, noneoftheseattributesarerequiredinrequestbodies,andareignoredifincluded.Allofthemareincluded inresponsebodies.
VMware, Inc.
143
name
Everyobjectrequiresanameattributewhosestringvalueprovidesthedisplaynamefortheobject.Thevalue ofnamemustbeuniquewithinagivenscope,asshowninTable 83. Table 8-3. Requirements for Unique Object Names
Object Type ProviderVdc Org,AdminOrg Vdc Catalog CatalogItem vAppTemplate vApp Vm Media Network Name Scope vCloud vCloud Containingorganization Containingorganization Containingcatalog Notconstrained Containingorganization ContainingvApp Notconstrained Container(Org,vApp,orvCloud)
href
EveryobjecthasuniquereferenceencodedinthehrefattributeofitsXMLrepresentation.SeeObject ReferencePrototypeonpage 142.
type
EveryobjectallowsatypeattributeinitsXMLrepresentation.Thevalueofthisattributeistheobjecttype expressedasastring,whichclientsshouldinterpretasthemediatype(HTTPContentType)ofthe representation.Thisstringiscaseinsensitiveinrequests,andcanbereturnedineithermixedcaseorlowercase charactersinresponses.Formoreinformation,seeContentTypeonpage 142.
status
ObjectssuchasvAppTemplate,vApp,andVm,thatextendtheResourceEntitytypehaveastatusattribute whosevalueindicatesthestateoftheobject,asshowninTable 84,whereYESindicatesthatastatusvalueis allowedfortheobjectlistedinthecolumnheader.Statusforanobject,suchasavAppTemplateorvApp,whose Children(Vmobjects)eachhaveastatusoftheirown,iscomputedfromthestatusoftheChildren. NOTEThedeploymentstatusofanobjectisindicatedbythevalueofitsdeployedattribute. Table 8-4. vAppTemplate, vApp, and Vm status Attribute Values
Value 1 0 1 2 3 4 5 6 7 Description Theobjectcouldnotbecreated. Theobjectisunresolved. Theobjectisresolved. Theobjectisdeployed. Theobjectissuspended. Theobjectispoweredon. Theobjectiswaitingforuserinput. Theobjectisinanunknownstate. Theobjectisinanunrecognizedstate. vAppTemplate YES YES YES No No No No YES YES vApp YES YES YES No YES YES
144
VMware, Inc.
Vm YES YES No No No No No No
IndicatesthatallChildrenhavethisstatus
xmlns:xsi
Notrequiredinrequestbodies.
XMLnamespaceidentifiersareomittedfrommostoftheexampleresponses(seeAbouttheExampleson page 19).Example 81showshowtheyappearinatypicalresponsebody. Example 8-1. Response Body Showing XML Namespace Identifiers
<VApp xmlns="http://www.vmware.com/vcloud/v1" status="8" name="Linux FTP server" type="application/vnd.vmware.vcloud.vApp+xml" href="http://vcloud.example.com/api/v1.0/vApp/vapp-7" xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1 http://vcloud.example.com/api/v1.0/schema/master.xsd"> ... </vApp>
VMware, Inc.
145
Common Elements
ThevCloud APIdefinesanumberofelementsthatcanbecontainedbytherepresentationsofmanykindsof objects.
Description
TheDescriptionelementcontainsastringthatdescribestheobject.Thiselementisalwaysoptional.
Error
Errorelementsareusedtotransmitreadonlyerrorinformationinaresponse. Content-Type application/vnd.vmware.vcloud.error+xml Schema
Name message majorErrorCode minorErrorCode vendorSpecificErrorCode stackTrace Min 1 1 1 0 0 Max 1 1 1 1 1 Type xs:string xs:int xs:string xs:string xs:string Description Messagedescribingtheerror MatchestheHTTPstatuscode.SeeStatusCodesonpage 18. Errorcodespecifictothefailedoperation Emptyinthisrelease Stacktraceoftheerror,ifavailable.Thisattributeisreturned onlytoasystemadministrator.
146
VMware, Inc.
Link
ALinkelementdefinesahyperlinkwitharelationship,URI,andanoptionalnameandmediatype.Formore informationabouthowLinkelementsareusedandalistofthevaluesallowedfortherelattribute,seeLinks andLinkRelationsonpage 15. Thiselementisreadonly. Schema
Name rel href type name Min 1 1 0 0 Max 1 1 1 1 Type RelationType xs:anyURI xs:string xs:string Description Relationofthelinktothereferencedobject Hyperlinktothereferencedobject Mediatypeofthereferencedobject.Linkstoactionsdonot haveamediatype. Nameofthereferencedobject.LinkstoTasksandactions donothavenames.
API Versioning
vCloud APIschemaversioninformationappearsinthevaluesofthexsi:schemaLocationandxmlns attributesinaresponsedocument.Forexample,aresponsebodythatusedschemaversion1.0wouldinclude thefollowingattributes:
xsi:schemaLocation="http://vcloud.example.com/api/v1.0/schema/master.xsd" xmlns="http://www.vmware.com/vcloud/v1"
Todiscovertheschemaversionssupportedbyaserver,aclientcanmakeanunauthenticatedGETrequestto awellknownURLontheserver,asshowninExample 82.Theresponsetothiskindofrequestisa SupportedVersionsdocument,fromwhichtheclientcanderiveinformationaboutthemediatypesand schemalocationsusedbytheversionoftheAPIthattheserversupports.Theresponsecontainsa MediaTypeMappingelementforeachmediatypedefinedbytheAPI.(Theexampleshowsonlyafewofthese elements.)TheresponsealsoincludesaLoginUrlelement,whichcontainsaURLthataclientcanusetoobtain anauthenticationtoken.FormoreinformationaboutusingtheLoginUrl,seeAuthenticationonpage 18. Example 8-2. API Version Request Request:
GET http://vcloud.example.com/api/versions
Response:
200 OK Content-Type: text/xml ... <SupportedVersions ...> <VersionInfo> <Version>1</Version> <LoginUrl>http://vcloud.example.com/api/v1/login</LoginUrl> <MediaTypeMapping> <MediaType>application/vnd.vmware.vcloud.org+xml</MediaType> <ComplexTypeName>CatalogType</ComplexTypeName> <SchemaLocation>http://vcloud.example.com/api/v1.0/schema/master.xsd</SchemaLocation> </MediaTypeMapping> <MediaTypeMapping>
VMware, Inc.
147
SupportedVersions
ASupportedVersionselementisacontainerforVersionInfoelements.
VersionInfo
AVersionInfoelementdefinestheloginURLandmediatypessupportedbyaversionofthevCloud API. Thiselementisreadonly. Schema
Name Version LoginUrl MediaTypeMapping Min 1 1 0 Max 1 1 n Type xs:string xs:string MediaTypeMappingType Description Versionnumber URLforloggingintothisversion Mediatypeofthereferencedobject.Linksto actionsdonothaveamediatype.
MediaTypeMapping
AMediaTypeMappingelementdefinesthename,MIMEcontenttype,andschemalocationofacomplextype supportedbythisversionofthevCloud API. Thiselementisreadonly. Schema
Name MediaType ComplexTypeName SchemaLocation Min 1 1 1 Max 1 1 1 Type xs:string xs:string xs:anyURI Description MIMEcontenttypeofthiscomplextype Nameofthiscomplextype URLfortheXMLschemadefinitiondocumentthatdefines thiscomplextype
Extensibility
ThevCloud APIisdesignedtobeextensible.AllcomplextypesdefinedbytheAPIextendasingleabstract complextype.Thiscomplextypeandalltypesbasedonitcanincludezeroormoreinstancesofanextension elementthatcancontainanarbitrarynumberofelementsandattributes. VCloudExtensibleTypeisanabstracttypethatallcomplextypesdefinedinthevCloud APInamespace (http://www.vmware.com/vcloud/v1)extend.Thistypeallowscustomattributestobeaddedtoanytypeand supportsdefinitionofcustomelementswithintheVCloudExtensionelement. TheVCloudExtensionelementhasanattributenamedrequiredthatspecifieshowclientsandservers proceedwhentheyseeunknownextension.Therequiredattributeisoptionalbutifomittedisassumedto bepresentwithavalueoftrue.Thatistosay,allVCloudExtensionelementsareassumedtorequireaserver thatunderstandsthem.
148
VMware, Inc.
VCloudExtension
AclientshouldbepreparedtoencounteraVCloudExtensionelementinanyresponse.Iftheelementdeclares required=trueandclientdoesnotknowhowtointerpretthecontentsoftheelement,theclientcanignore it,butitmustincludetheVCloudExtensioninanyrequesttomodifytheelementthatcontainsit.Aserver mustreturnafailurewhenarequestincludesaVCloudExtensionelementthatdeclaresrequired=true buttheserverdoesnotunderstandtheextension. Schema
Name required anyattributename anyelementname Min 0 0 0 Max 1 n n Type xs:boolean xs:any xs:any Description Trueifthisextensionmustbeunderstoodbytheserver Anarbitrarynumberofattributesofanytype Anarbitrarynumberofelementsofanytype
VMware, Inc.
149
150
VMware, Inc.
OrgListonpage 151 Orgonpage 151 Vdconpage 152 OrgNetworkonpage 154 Catalogonpage 160 Mediaonpage 161 VAppTemplateonpage 161 VApponpage 162 Vmonpage 163 Sectiononpage 163 ScreenTicketonpage 168 TasksListonpage 168
OrgList
AnOrgListelementisacontainerforreferencestoorganizations.Itisreturnedintheresponsetoasuccessful loginoraGETAPIURL/orgrequest,andcontainsareferencetoeachorganizationtowhichtheloggedinuser hasaccess. Thiselementisreadonly. Content-Type application/vnd.vmware.vcloud.orgList+xml Object href prototype APIURL/org
Org
TheOrgelementrepresentstheuserviewofavCloudorganizationobject,whichisacontainerandunitof administrationforresourcesandusers. Content-Type application/vnd.vmware.vcloud.org+xml
VMware, Inc.
151
FullName
xs:string
Vdc
AvDCisadeploymentenvironmentforvApps.AVdcelementprovidesauserviewofavDC. Content-Type application/vnd.vmware.vcloud.vdc+xml Object href prototype APIURL/vdc/id Schema
Name name anyattributename status Min 1 0 0 Max 1 n 1 Type xs:string any xs:int Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers ThecreationstatusofthevDC:
Description Tasks
0 0
1 1
xs:string TasksInProgressType
Optionaldescription ReadonlycontainerforTaskelements.Each elementinthecontainerrepresentsaqueued, running,orfailedtaskownedbythisobject. DefineshowresourcesareallocatedbythevDC. Thevalueofthiselementissetbytheadministrator whocreatedthevDC.Itisreadonlytousers. DefinesthestoragecapacityavailableinthevDC DefinesthecomputecapacityavailableinthevDC ReadonlycontainerforResourceEntity elements ReadonlycontainerforOrgNetworkelementsthat representorganizationnetworkscontainedbythe vDC MaximumnumberofvirtualNICsallowedinthis vDC.Defaultsto0,whichspecifiesanunlimited number. MaximumnumberofOrgNetworkobjectsthatcan bedeployedinthisvDC.Defaultsto0,which specifiesanunlimitednumber.
AllocationModel
AllocationModelType
1 1 0 0
1 1 1 1
NicQuota
xs:int
NetworkQuota
xs:int
152
VMware, Inc.
Schema (Continued)
Name VmQuota Min 0 Max 1 Type xs:int Description Maximumnumberofvirtualmachinesthatcanbe deployedinthisvDC.Defaultsto0,whichspecifies anunlimitednumber. TrueifthisvDCisenabled
IsEnabled
xs:boolean
StorageCapacity
TheStorageCapacityelementreportsstorageresourceconsumptioninavDC. Schema
Name Used Overhead Min 0 0 Max 1 1 Type xs:long xs:long Description Percentageoftheallocationinuse.Thisvalueisreadonly. NumberofUnitsallocatedtovShieldManagervirtualmachinesprovisioned fromthisvDC.Thisvalueisreadonly.
ComputeCapacity
TheComputeCapacityelementreportsCPUandmemoryresourceconsumptioninavDC. Schema
Name Cpu Memory Min 1 1 Max 1 1 Type CapacityWithUsageType CapacityWithUsageType Description ReportsCPUresourceconsumptioninavDC ReportsmemoryresourceconsumptioninavDC
Cpu
TheCpuelementreportsCPUresourceconsumptioninavDC. Schema
Name Used Overhead Min 0 0 Max 1 1 Type xs:long xs:long Description Percentageoftheallocationinuse.Thisvalueisreadonly. NumberofUnitsallocatedtovShieldManagervirtualmachinesprovisioned fromthisvDC.Thisvalueisreadonly.
Memory
TheMemoryelementreportsmemoryresourceconsumptioninavDC. Schema
Name Used Overhead Min 0 0 Max 1 1 Type xs:long xs:long Description Percentageoftheallocationinuse.Thisvalueisreadonly. NumberofUnitsallocatedtovShieldManagervirtualmachinesprovisioned fromthisvDC.Thisvalueisreadonly.
AvailableNetworks
TheAvailableNetworkselementisareadonlycontainerforOrgNetworkelements.
Network
EachNetworkelementcontainsareferencetoanOrgNetworkobjectinthesameorganizationasthisvDC.
VMware, Inc.
153
ResourceEntities
TheResourceEntitieselementisareadonlycontainerforResourceEntityelements.
ResourceEntity
TheResourceEntityelementisareadonlyreferencetoavAppTemplateorMediaobjectcontainedbya vDC. Schema
Name name status anyattributename Files Min 1 0 0 0 Max 1 1 n 1 Type xs:string xs:int any FilesListType Description Commonobjectnameattribute Creationstatusofthereferencedobject. Includestype,href,XMLnamespaceidentifiers ReadonlycontainerforFileelements
Files
TheFileselementisacontainerforFileelements.
File
Fileelementsareconstructedbytheserverinresponsetoanuploadordownloadrequest. Schema
Name name size bytesTransferred Min 1 0 0 Max 1 1 1 Type xs:string xs:long xs:long Description Commonobjectnameattribute Sizeofthefileinbytes Ifanuploadordownloadofthisfileisinprogress,this attributeindicatesthenumberofbytesthathavebeen transferredbytheuploadordownload Ignoredinthisrelease Optionaldescription ReadonlycontainerforTaskelements.Eachelementin thecontainerrepresentsaqueued,running,orfailed taskownedbythisobject.
0 0 0
1 1 1
OrgNetwork
AnOrgNetworkelementdefinesanetworkthathasbeenallocatedtoanorganizationbythesystem administrator. Content-Type application/vnd.vmware.vcloud.network+xml Object href prototype APIURL/network/id Schema
Name name anyattributename Description Min 1 0 0 Max 1 n 1 Type xs:string any xs:string Description Commonobjectnameattribute Includestype,href,XMLnamespace identifiers Optionaldescription
154
VMware, Inc.
Schema (Continued)
Name Tasks Min 0 Max 1 Type TasksInProgressType Description ReadonlycontainerforTaskelements. Eachelementinthecontainer representsaqueued,running,orfailed taskownedbythisobject. Propertiesofthenetwork Areferencetothenetworkpoolfrom whichthisnetworkisprovisioned.This element,whichisrequiredwhen creatinganatRoutedorisolated network,isreturnedinresponsetoa creationrequestbutnotshownin subsequentGETrequests. ListofexternalIPaddressesthatthis networkcanuseforNAT.
Configuration NetworkPool
0 0
1 1
NetworkConfigurationType ReferenceType
AllowedExternalIpAddresses
IpAddressesType
Configuration
TheConfigurationelementspecifiespropertiesofanetwork. Schema
Name IpScope ParentNetwork FenceMode Features Min 0 0 1 0 Max 1 1 1 1 Type IpScopeType ReferenceType FenceModeValuesType NetworkFeaturesType Description Definestheaddressrange,gateway,netmask,andother propertiesofthenetwork Referencetoanetworktowhichthisnetworkconnects Defineshowthisnetworkisconnectedtoits ParentNetwork Definesasetofnetworkfeatures.
FenceMode
TheFenceModeelementdefineshowthisnetworkisconnectedtoitsParentNetwork.Table 91shows permittedvaluesforelementcontentandtheresultstheyproduce. Table 9-1. FenceMode Element Values
Value bridged isolated natRouted Result Thetwonetworksarebridged Thetwonetworksarenotconnected. ThetwonetworksareconnectedasspecifiedintheirNatServiceelements.
IpScope
TheIpScopeelementdefinestheaddressrange,gateway,netmask,andotherpropertiesofthenetwork. Schema
Name IsInherited Min 1 Max 1 Type xs:boolean Description TrueifthevaluesinthisIpScopeelementare inheritedfromtheParentNetworkofthe containingConfiguration IPaddressofthenetworkgateway Netmasktoapplytoaddressesonthenetwork IPaddressoftheprimaryDNSserverforthis network
0 0 0
1 1 1
VMware, Inc.
155
Schema (Continued)
Name Dns2 DnsSuffix IpRanges AllocatedIpAddresses Min 0 0 0 0 Max 1 1 1 1 Type IpAddressType xs:string IpRangesType IpAddressesType Description IPaddressofthesecondaryDNSserverforthis network Suffixtobeappliedwhenresolvinghostnamesthat arenotfullyqualified. ReadonlycontainerforIpRangeelements. Listofaddressesallocatedtoconnectionstothis network.MustfallwithinanyspecifiedIpRanges.
IpRange
TheIpRangeelementdefinesarangeofIPaddressesavailableonanetwork. Schema
Name StartAddress EndAddress Min 1 1 Max 1 1 Type IpAddressType IpAddressType Description LowestIPaddressintherange HighestIPaddressintherange
Features
TheFeatureselementdefinestheDHCPandfirewallfeaturesofanetwork. Schema
Name DhcpService FirewallService NatService Min 0 0 0 Max 1 1 1 Type DhcpServiceType FirewallServiceType NatServiceType Description SpecifiesthepropertiesofthenetworksDHCPservice Definesthefirewallservicecapabilitiesofthenetwork DefinestheNATservicecapabilitiesofthenetwork
DhcpService
TheDhcpServiceelementspecifiesthepropertiesofthenetworksDHCPservice. Schema
Name IsEnabled DefaultLeaseTime MaxLeaseTime IpRange Min 0 0 0 0 Max 1 1 1 1 Type xs:boolean xs:int xs:int IpRangeType Description Trueiftheserviceisenabled DefaultdurationofaDCHPaddresslease MaximumdurationofaDCHPaddresslease. RangeofIPaddressesavailabletoDHCPclients
FirewallService
TheFirewallServiceelementdefinesthefirewallservicecapabilitiesofanetwork. Schema
Name IsEnabled FirewallRule Min 0 0 Max 1 n Type xs:boolean FirewallRuleType Description Trueiftheserviceisenabled Definesasinglefirewallrule
156
VMware, Inc.
FirewallRule
TheFirewallRuleelementdefinesasinglefirewallrule. Schema
Name IsEnabled Description Policy Protocols Port DestinationIp Min 0 0 0 0 1 1 Max 1 1 1 1 1 1 Type xs:boolean xs:string FirewallPolicyType ProtocolsType xs:int IpAddressType Description Trueiftheruleisenabled descriptionoftherule Specifieshowpacketsarehandledbythefirewall Specifiestheprotocolstowhichthisfirewallruleapplies Specifiesthenetworkporttowhichthisfirewallruleapplies. Avalueof1matchesanyport. SpecifiesthedestinationIPaddress,insidethefirewall,to whichthisfirewallruleapplies
Policy
ThePolicyelementofaFirewallRulespecifieshowpacketsarehandledbythefirewall.Table 92shows permittedvaluesforelementcontentandtheresultstheyproduce. Table 9-2. FirewallRule Policy Element Values
Value drop allow Result Droppacketsofthistype Allowpacketsofthistypetopassthroughthefirewall
Protocols
TheProtocolselementspecifiestheprotocolstowhichfirewallrulesapply. Schema
Name Tcp Udp Min 0 0 Max 1 1 Type xs:boolean xs:boolean Description TrueifthefirewallrulesapplytotheTCPprotocol TrueifthefirewallrulesapplytotheUDPprotocol
NatService
TheNatServiceelementdefinesthenetworkaddresstranslationcapabilitiesofanetwork. Schema
Name IsEnabled NatType Policy NatRule Min 0 0 0 0 Max 1 1 1 n Type xs:boolean NatTypeType NatPolicyType NatRuleType Description Trueiftheserviceisenabled SpecifieshowNetworkAddressTranslationis implementedbytheNATservice SpecifieshowpacketsarehandledbytheNATservice SpecifiesasingleNATrule
VMware, Inc.
157
NatType
TheNatTypeelementspecifieshownetworkaddresstranslationisimplementedbytheNATservice.Table 93 showspermittedvaluesforelementcontentandtheresultstheyproduce. Table 9-3. NatType Element Values
Value ipTranslation portForwarding Result NATserviceimplementedbyIPaddresstranslation NATserviceimplementedbynetworkportforwarding
Policy
ThePolicyelementofaNatServiceelementspecifieshowpacketsarehandledbytheNATservice.Table 94 showspermittedvaluesforelementcontentandtheresultstheyproduce. Table 9-4. NatService Policy Element Values
Value allowTraffic allowTrafficIn Result Packetsofthistypepassthroughthefirewallinbothdirections Onlyinboundpacketsofthistypepassthroughthefirewall
NatRule
TheNatRuleelementspecifiesasinglenetworkaddresstranslationrule. Schema
Name Description OneToOneBasicRule OneToOneVmRule PortForwardingRule VmRule Min 0 0 0 0 0 Max 1 1 1 1 1 Type xs:string NatOneToOneBasicRuleType NatOneToOneVmRuleType NatPortForwardingRuleType NatVmRuleType Description Optionaldescriptionoftherule Ignoredinthisrelease Specifiesnetworkaddresstranslationdetailsfor asinglevirtualmachine MapsanIPaddressandportinanorganization networktoanexternalIPaddressandport MapsanIPaddressandportinavAppnetwork toanexternalIPaddressandport
OneToOneVmRule
TheOneToOneVmRuleelementdescribesaNATrulethatspecifiesnetworkaddresstranslationdetailsfora singlevirtualmachine.TheexternalIPaddresscanbespecifiedmanuallyorassignedautomaticallyat deploymenttime.TheinternalIPaddressisdiscoveredbylookingupthespecifiedVmReferenceandNICID. Schema
Name MappingMode ExternalIP VAppScopedVmId VmNicId Min 1 0 1 1 Max 1 1 1 1 Type NatMappingModeType IpAddressType xs:string xs:int Description SpecifieshowIPaddressmappingisimplementedby theNATservice IfMappingModeismanual,specifiestheexternalIP addressofthisVm Readonlyidentifiercreatedonimport DevicenumberoftheNIConthereferencedvirtual machine
158
VMware, Inc.
MappingMode
TheMappingModeelementspecifieshowIPaddressmappingisimplementedbytheNATservice.Table 95 showspermittedvaluesforelementcontentandtheresultstheyproduce. Table 9-5. MappingMode Element Values
Value manual automatic Result TheexternalIPaddressisspecifiedintheExternalIPelement TheexternalIPaddressisassignedautomatically
PortForwardingRule
ThePortForwardingRuleelementdescribesaNATrulethatmapsanIPaddressandportinanorganization networktoanexternalIPaddressandport. Schema
Name ExternalIP ExternalPort InternalIP InternalPort Protocol Min 1 1 1 1 1 Max 1 1 1 1 1 Type IpAddressType xs:int IpAddressType xs:int Layer4ProtocolType Description IPaddresstowhichthisNATrulemapstheIPaddress specifiedintheInternalIPelement NetworkporttowhichthisNATrulemapstheportnumber specifiedintheInternalPortelement IPaddresstowhichthisNATrulemapstheIPaddress specifiedintheExternalIpelement. NetworkporttowhichthisNATrulemapstheportnumber specifiedintheExternalPortelement. Specifiesthenetworkprotocoltowhichthisruleapplies
VmRule
TheVmRuleelementdescribesaNATrulethatmapsanIPaddressandportinavAppnetworktoanexternal IPaddressandport.TheexternalIPaddress,externalport,andinternalportarespecifiedintheelement.The internalIPaddressisdiscoveredbylookingupthespecifiedVmReferenceandVmNicId. Schema
Name ExternalIP ExternalPort VAppScopedVmId VmNicId InternalPort Protocol Min 0 1 1 1 1 1 Max 1 1 1 1 1 1 Type IpAddressType xs:int xs:string xs:int xs:int Layer4ProtocolType Description IPaddresstowhichthisNATrulemapstheIPaddress specifiedintheInternalIPelement. ThenetworkporttowhichthisNATrulemapstheport numberspecifiedintheInternalPortelement. Readonlyidentifiercreatedonimport ThedevicenumberoftheNIConthereferencedvirtual machine. ThenetworkporttowhichthisNATrulemapstheport numberspecifiedintheExternalPortelement. Specifiesthenetworkprotocoltowhichthisruleapplies
VMware, Inc.
159
Protocol
TheProtocolelementofaVmRuleelementspecifiesthenetworkprotocoltowhichthisruleapplies.Table 96 showspermittedvaluesforelementcontentandtheresultstheyproduce. Table 9-6. VmRule Protocol Element Values
Value TCP UDP TCP_UDP Result TheruleappliestotheTCPprotocol TheruleappliestotheUDPprotocol TheruleappliestotheTCPandUDPprotocols
Catalog
ACatalogelementisacontainerforCatalogItems.Anorganizationcancontainzeroormorecatalogs.Users withappropriateprivilegescanaddorremoveCatalogItemelementsfromacatalog. Content-Type application/vnd.vmware.vcloud.catalog+xml Object href prototype APIURL/catalog/id Schema
Name name anyattributename Link Description Tasks Min 1 0 0 0 0 Max 1 n n 1 1 Type xs:string any LinkType xs:string TasksInProgressType Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers Linkstoactionsandcontainedobjects Optionaldescription ReadonlycontainerforTaskelements.Each elementinthecontainerrepresentsaqueued, running,orfailedtaskownedbythisobject. ReadonlycontainerforCatalogItemelements. Readonlyelement,trueifthecatalogispublished
CatalogItems IsPublished
0 0
1 1
CatalogItemsType xs:boolean
CatalogItems
TheCatalogItemselementisareadonlycontainerforindividualCatalogItemelements.
CatalogItem
TheCatalogItemelementcontainsareferencetoamediaimageorvApptemplateandoptionalrelated metadata. Content-Type application/vnd.vmware.vcloud.catalogItem+xml Object href prototype APIURL/catalogItem/id Schema
Name Entity Property Min 1 0 Max 1 n Type ReferenceType PropertyType Description Referencetothecataloguedobject Expressesakey=valuerelationship.(Inthisrelease, themaximumnumberoftheseelementsina CatalogItemislimitedtoten).
160
VMware, Inc.
Property
EachCatalogItemcanhaveuptotenPropertyelements,eachofwhichexpressesakey=valuerelationship. Thekeyisanattributevalue,andthevalueisthecontentofthePropertyelementitself.Thiselementcanbe usedtoholdarbitrarymetadataattachedtoaCatalogItem.ThevCloudAPIitselfmakesnouseofthis information. Schema
Name key Min 1 Max 1 Type xs:string Description Keyassociatedwiththestringvaluecontainedinthe element.Thelengthofthekeycannotexceed80 characters.Thelengthofthevaluecannotexceed256 characters.
Media
TheMediaelementrepresentsvirtualmedia,suchasanISOorfloppyimage. Content-Type application/vnd.vmware.vcloud.media+xml Object href prototype APIURL/media/id Schema
Name name anyattributename status imageType Min 1 0 0 1 Max 1 n 1 1 Type xs:string any xs:int ImageType Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers Creationstatusoftheobject Oneof:
1 0 0
1 1 1
VAppTemplate
AVAppTemplateisanabstractdescriptionofavApp.ItiscreatedwhenyouuploadanOVFpackagetoavDC. Content-Type application/vnd.vmware.vcloud.vAppTemplate+xml Object href prototype APIURL/vAppTemplate/vAppTemplateid Schema
Name status name Min 0 1 Max 1 1 Type xs:int xs:string Description CreationstatusoftheVAppTemplate. Commonobjectnameattribute
VMware, Inc.
161
Schema (Continued)
Name ovfDescriptorUploaded anyattributename Link Description Tasks Min 0 0 0 0 0 Max 1 n n 1 1 Type xs:boolean any LinkType xs:string TasksInProgressType Description TrueiftheOVFdescriptorforthetemplatehasbeen uploadedtothecontainingvDC. Includestype,href,XMLnamespaceidentifiers Linkstoactionsandcontainedobjects Optionaldescription ReadonlycontainerforTaskelements.Each elementinthecontainerrepresentsaqueued, running,orfailedtaskownedbythisobject. Filesthatarepartofthetemplate ReadonlycontainerforVmelementsrepresenting virtualmachines Anyofthefollowingovf:Section_Typeelements:
0 0 0
n 1 n
VAppScopedLocalId
xs:string
Readonlyidentifiercreatedonimport
Children
TheChildrenelementisareadonlycontainerforthevirtualmachines(Vmelements)thataremembersofa vApporvAppTemplate.
VApp
AVAppelementrepresentsavApp,whichistheresultofinstantiationofavApptemplate. Content-Type application/vnd.vmware.vcloud.vApp+xml Object href prototype APIURL/vApp/vappid Schema
Name deployed status name ovfDescriptorUploaded anyattributename Link Description Tasks Min 0 0 1 0 0 0 0 0 Max 1 1 1 1 n n 0 1 Type xs:boolean xs:int xs:string xs:boolean any LinkType xs:string TasksInProgressType Description TrueifthevAppisdeployed CreationstatusofthevApp Commonobjectnameattribute TrueiftheassociatedOVFdescriptorhasbeen uploaded Includestype,href,XMLnamespaceidentifiers ActionlinkstovAppoperations Optionaldescription ReadonlycontainerforTaskelements.Eachelement inthecontainerrepresentsaqueued,running,or failedtaskownedbythisobject. Unsupportedinthisrelease
VAppParent
ReferenceType
162
VMware, Inc.
Schema (Continued)
Name Section Min 0 Max n Type ovf:Section_Type Description Anyofthefollowingovf:Section_Typeelements:
Children
VAppChildrenType
ReadonlycontainerforVmelementsrepresenting virtualmachines
Vm
AVmrepresentsavirtualmachine,amemberofavAppsChildrencontainer. Content-Type application/vnd.vmware.vcloud.vApp+xml Object href prototype APIURL/vAppTemplate/vmidorAPIURL/vApp/vmid Schema
Name deployed status name anyattributename Link Description Tasks Min 0 0 1 0 0 0 0 Max 1 1 1 n n 1 1 Type xs:boolean xs:int xs:string any LinkType xs:string TasksInProgressType Description TrueiftheVmisdeployed CreationstatusoftheVm Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers Actionlinkstooperations Optionaldescription ReadonlycontainerforTaskelements.Eachelement inthecontainerrepresentsaqueued,running,or failedtaskownedbythisobject. Unsupportedinthisrelease Anyofthefollowingovf:Section_Typeelements:
VAppParent Section
0 0
1 n
ReferenceType ovf:Section_Type
VAppScopedLocalId
xs:string
Readonlyidentifiercreatedonimportorcomposition
Section
AVAppTemplate,VApp,andVmcancontainanarbitrarynumberofovf:SectionTypeelements.InavAppor Vm,someoftheseelementscanbespecifiedasinstantiationparameters.Theothersarecopiedfromthesource OVFEnvelopeandtreatedasreadonlybythevCloudAPI. ThefollowingsectiontypesareallowedinavApporvAppTemplate:
VMware, Inc.
163
ThefollowingsectiontypesareallowedinaVm:
LeaseSettingsSection
TheLeaseSettingsSectionelementdefinesthetermsofstorageanddeploymentleasesforavApp. Content-Type application/vnd.vmware.vcloud.leaseSettingsSection+xml Schema
Name ovf:required type href ovf:Info Min 0 0 0 1 Max 1 1 1 1 Type xs:boolean xs:string xs:anyURI ovf: Msg_Type LinkType xs:string xs:string xs:dateTime xs:dateTime Description Optionalindicationofwhetherthiselementisrequired Mediatypeofthissection URLtoaccessthissection Requiredbythebaseovf:Section_Type.Itcancontain xs:stringinformationaboutthecontainingelement,or canbeempty Configurationlinks Durationofthedeploymentlease,inseconds Durationofthestoragelease,inseconds Dateandtimewhenthedeploymentleaseexpires Dateandtimewhenthestorageleaseexpires
0 0 0 0 0
n 1 1 1 1
StartupSection
InanOVFpackageorVAppthatcontainsmultiplevirtualmachines,theStartupSectionspecifiestheorder inwhichthevirtualmachines(VirtualSystemsinanOVFVirtualSystemCollectionorthe VAppChildrenofaVApp)arepoweredon. Content-Type application/vnd.vmware.vcloud.startupSection+xml
CustomizationSection
TheCustomizationSectionelementofaVAppcontainsinformationabouthowcustomizationistobe appliedtothevirtualmachinesinthevApp. Content-Type application/vnd.vmware.vcloud.customizationSection+xml Schema
Name ovf:required type href ovf:Info Min 0 0 0 1 Max 1 1 1 1 Type xs:boolean xs:string xs:anyURI ovf:Msg_Type Description Optionalindicationofwhetherthiselementisrequired Mediatypeofthissection URLtoaccessthissection Requiredbythebaseovf:Section_Type.Itcancontain xs:stringinformationaboutthecontainingelement,or canbeempty
164
VMware, Inc.
Schema (Continued)
Name CustomizeOnInstantiate Min 1 Max 1 Type xs:boolean Description Iftrue,thencustomizationisexecutedforallchildrenthat includeaGuestCustomizationSection.Defaultvalueis false. Configurationlinks
Link
LinkType
NetworkConfigSection
TheNetworkConfigSectionelementspecifiestheconfigurationofavAppnetwork. Content-Type application/vnd.vmware.vcloud.networkConfigSection+xml Schema
Name ovf:required type href ovf:Info Min 0 0 0 1 Max 1 1 1 1 Type xs:boolean xs:string xs:anyURI ovf:Msg_Type Description Optionalindicationofwhetherthiselementis required Mediatypeofthissection URLtoaccessthissection Requiredbythebaseovf:Section_Type.Itcan containxs:stringinformationaboutthe containingelement,orcanbeempty Configurationlinks DefinestheconfigurationofaVAppnetwork
Link NetworkConfig
0 0
n n
LinkType VAppNetworkConfigurationType
NetworkConfig
TheNetworkConfigelementdefinestheconfigurationofavAppnetwork. Schema
Name networkName Description Configuration IsDeployed Min 1 0 1 0 Max 1 1 1 1 Type xs:string xs:string NetworkConfigurationType xs:boolean Description NameofthevAppNetwork Optionaldescriptionofthenetwork Propertiesofthenetwork Trueifthenetworkhasbeendeployed (readonly)
NetworkConnectionSection
TheNetworkConnectionSectionelementspecifieshowaVmisconnectedtoavAppnetwork.Itextendsthe ovf:NetworkConnectionelement. NOTETheOVFNetworkSectionelementandthevCloudAPINetworkConnectionSectionelement specifymanyofthesameparametersforanetworkconnection.IfbotharepresentinaVmbody,thevalues specifiedintheNetworkConnectionSectionoverridethosespecifiedintheNetworkSection. Content-Type application/vnd.vmware.vcloud.networkConnectionSection+xml Schema
Name ovf:required type Min 0 0 Max 1 1 Type xs:boolean xs:string Description Optionalindicationofwhetherthis elementisrequired Mediatypeofthissection
VMware, Inc.
165
Schema (Continued)
Name href ovf:Info Min 0 1 Max 1 1 Type xs:anyURI ovf:Msg_Type Description URLtoaccessthissection Requiredbythebase ovf:Section_Type.Itcancontain xs:stringinformationaboutthe containingelement,orcanbeempty Thevalueofthe rasd:AddressOnParentelementof thedevice(NIC)supportingthe primarynetworkconnectiontothe containingvirtualmachine. Describesasinglenetworkconnection Configurationlinks
PrimaryNetworkConnectionIndex
xs:int
NetworkConnection Link
0 0
n n
NetworkConnectionType LinkType
NetworkConnection
TheNetworkConnectionelementdescribesasinglenetworkconnection. Schema
Name anyattributename network NetworkConnectionIndex Min 0 1 1 Max n 1 1 Type any xs:string xs:int Description Includestype,href,XMLnamespace identifiers Thenameofthenetworktowhichthis connectionconnects. Thevalueinthe rasd:AddressOnParentelementofthe devicesupportingthisconnection. IPaddressofthisconnection IfthenetworkthattheNICisconnected tohasNATorportmapping,the externaladdressispopulatedinthis element. IfthevAppisdeployed,specifiesthe currentstateofitsconnection.Ifthe vAppisundeployed,specifieswhether thisconnectionshouldbeconnectedat deploymenttime. MACaddressofthisconnection SpecifieshowanIPaddressisallocated tothisconnection
IpAddress ExternalIpAddress
0 0
1 1
IpAddressType IpAddressType
IsConnected
xs:boolean
MACAddress IpAddressAllocationMode
0 1
1 1
xs:string IpAddressAllocationModeType
IpAddressAllocationMode
TheIpAddressAllocationModeelementspecifieshowanIPaddressisallocatedtothisconnection.Table 97 showspermittedvaluesforelementcontentandtheresultstheyproduce. Table 9-7. IpAddressAllocationMode Element Values
Value NONE MANUAL POOL DHCP Result NoIPaddressingmodespecified StaticIPaddressassignedmanually StaticIPaddressallocatedfromapool IPaddressassignedbyDHCP
166
VMware, Inc.
VirtualHardwareSection
TheVirtualHardwareSectionelementofanovf:VirtualSystemorVmcontainsadescriptionofthevirtual hardwaresupportedbyavirtualmachine. Content-Type application/vnd.vmware.vcloud.virtualHardwareSection+xml
OperatingSystemSection
TheOperatingSystemSectionelementofanovf:VirtualSystemorVmspecifiestheguestoperatingsystem installedonthevirtualmachine. Content-Type application/vnd.vmware.vcloud.operatingSystemSection+xml
GuestCustomizationSection
TheGuestCustomizationSectionelementofaVmcontainscustomizationparametersfortheguest operatingsystemofthevirtualmachine. Content-Type application/vnd.vmware.vcloud.guestCustomizationSection+xm Schema
Name ovf:required type href ovf:Info Min 0 0 0 1 Max 1 1 1 1 Type xs:boolean xs:string xs:anyURI ovf:Msg_Type Description Optionalindicationofwhetherthiselementisrequired Mediatypeofthissection URLtoaccessthissection Requiredbythebaseovf:Section_Type.Itcancontain xs:stringinformationaboutthecontainingelement,or canbeempty Configurationlinks Iftrue,toenableguestcustomizationatpoweron Iftrue,customizationwillrunsyspreptochangethe WindowsSIDforthisvirtualmachine Uniqueidentifierforthisvirtualmachine(readonly) Iftrue,thisvirtualmachinecanjoinaWindowsdomain Iftrue,thisvirtualmachineusesthecontaining organizationsdefaultvaluesforWindowsdomainname, domainusername,anddomainuserpassword IfUseOrgSettingsisfalse,specifiestheWindows domaintojoin.RequiredifJoinDomainEnabledistrue. IfUseOrgSettingsisfalse,specifiestheWindows domainusername.RequiredifJoinDomainEnabledis true. IfUseOrgSettingsisfalse,specifiestheWindows domainuserspassword.Requiredif JoinDomainEnabledistrue. Trueiftheadministratorpasswordshouldbereset. Trueifthelocaladministratorpasswordshouldbe automaticallygenerated Localadministratorpasswordforthisvirtualmachine Iftrue,thelocaladministratormustresethispasswordon firstuse Thiselementcontainsthecustomizationscripttorun NameofthisvirtualmachineinDNSorWindowsdomain
0 0 0 0 0 0
n 1 1 1 1 1
DomainName DomainUserName
0 0
1 1
xs:string xs:string
DomainUserPassword
xs:string
0 0 0 0 0 0
1 1 1 1 1 1
VMware, Inc.
167
RasdItemsList
ARasdItemsListelementisareadonlycontainerforgroupsofrelatedovf:Itemelementssuchashard disks,networkcards,andmediadevices.VmelementstypicallycontainseveralLinkelementsthatreference elementsofthistype. Content-Type application/vnd.vmware.vcloud.rasdItemsList+xml
ScreenTicket
AScreenTicketelementcontainsastringthatrepresentsascreenticket(requiredtoaccessavirtual machinesconsole). Content-Type application/vnd.vmware.vcloud.screenTicket+xml
TasksList
TheTasksListelementisareadonlycontainerforTaskelementsthatrepresentqueued,running,orrecently completedtasksownedbyamemberoftheorganizationthatcontainstheTasksList. Content-Type application/vnd.vmware.vcloud.tasksList+xml
Tasks
TheTaskselementisareadonlycontainerforTaskelementsownedbythecontainingobject.Tasksshown inthiselementalsoappearintheTasksListoftheorganizationthatcontainstheobject.
Task
Whenevertheresultofarequestcannotbereturnedimmediately,theservercreatesaTaskobject.Tasks ownedbyanobjectsuchasavApporvDCarecontainedintheTaskselementoftheobjectsXML representation.EachTaskinaTasksorTasksListelementcontainsalltheinformationaboutthetask.AGET requesttoanindividualtaskshrefdoesnotreturnanyadditionalinformationaboutthetask. Thiselementisreadonly. Content-Type application/vnd.vmware.vcloud.taskt+xml Schema
Name status Min 1 Max 1 Type TaskStatusType Description Thecurrentstatusofthetask.Oneof:
queued Thetaskhasbeenqueuedforexecution. running Thetaskisrunning. success Thetaskhascompletedandreturnedavalueindicating success. error Thetaskhascompletedandreturnedavalueindicatingan error.
0 0 0 0 0
1 1 1 1 1
168
VMware, Inc.
Schema (Continued)
Name Owner Min 0 Max 1 Type ReferenceType Description Alinktotheobjectthatownsthetask.Forcopyoperations,theowner isthecopythatisbeingcreated.Fordeleteoperations,theowneristhe deletedobject,sothiselementisnotincluded.Forallotheroperations, theowneristheobjecttowhichtherequestwasmade. Errormessageorrelatedinformationreturnedbythetask
Error
ErrorType
VMware, Inc.
169
170
VMware, Inc.
10
10
UploadVAppTemplateParamsonpage 171 InstantiateVAppTemplateParamsonpage 172 InstantiationParamsonpage 172 ComposeVAppParamsonpage 173 RecomposeVAppParamsonpage 174 DeployVAppParamsonpage 175 UndeployVAppParamsonpage 175 CaptureVAppParamsonpage 175 CloneMediaParamsonpage 176 CloneVAppTemplateParamsonpage 176 CloneVAppParamsonpage 176 MediaInsertOrEjectParamsonpage 177 VmPendingQuestiononpage 177 VmQuestionAnsweronpage 177 ControlAccessParamsonpage 177
UploadVAppTemplateParams
TheUploadVAppTemplateParamselementformsthebodyofanuploadVappTemplaterequest. Content-Type application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml Schema
Name name Description transferFormat manifestRequired Min 1 0 0 0 Max 1 1 1 1 Type xs:string xs:string xs:string xs:boolean Description Specifiesthenamegiventothetemplate Descriptionofthetemplate Ignoredinthisrelease Trueiftheuploadincludesamanifestfile
VMware, Inc.
171
InstantiateVAppTemplateParams
TheInstantiateVAppTemplateParamselementformsthebodyofaninstantiateVappTemplaterequest. Content-Type application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml Schema
Name name linkedClone deploy powerOn Description VAppParent Source IsSourceDelete InstantiationParams Min 1 0 0 0 0 0 1 0 0 Max 1 1 1 1 1 1 1 1 1 Type xs:string xs:boolean xs:boolean xs:boolean xs:string ReferenceType ReferenceType xs:boolean InstantiationParamsType Description SpecifiesthenameofthevAppcreatedbythis instantiation Ignoredinthisrelease TrueifthevAppshouldbedeployedafter instantiation.Defaultstofalse. TrueifthevAppshouldbedeployedandpoweredon afterinstantiation.Defaultstofalse. Optionaldescription.UsedfortheDescriptionofthe vAppcreatedbythisinstantiation. Unsupportedinthisrelease AreferencetothevApptemplatetoinstantiate TrueiftheobjectreferencedbySourceshouldbe deletedafterthecopyismade Containerforanyofthefollowing ovf:Section_Typeelements:
AllEULAsAccepted
xs:boolean
Trueifyouacceptthetermsandconditionsinthe templatesEULAsections.Instantiationfailsiffalse.
InstantiationParams
TheInstantiationParamselementcontainszeroormoreovf:Section_Typeelementsthatspecifythe configurationofavApporvirtualmachine. Schema
Name Section Min 0 Max n Type ovf:Section_Type Description AnypermittedOVFSectiontype
InstantiationParamscontainedbyanItemelementthatspecifiesaVmasitsSourcecancontainthe followingsectiontypes:
172
VMware, Inc.
InstantiationParamscontainedbyanyotherelementapplytoavAppandcancontainthefollowing sectiontypes:
ComposeVAppParams
TheComposeVAppParamselementformsthebodyofacomposeVapprequest. Content-Type application/vnd.vmware.vcloud.composeVAppParams+xml Schema
Name name Description deploy powerOn Min 1 0 0 0 Max 1 1 1 1 Type xs:string xs:string xs:boolean xs:boolean Description SpecifiesthenameofthevAppcreatedbythis composition Optionaldescription.Usedforthe DescriptionofthecomposedvApp TrueifthevAppshouldbedeployedafter composition.Defaultstofalse. TrueifthevAppshouldbedeployedand poweredonaftercomposition.Defaultsto false. Ignoredinthisrelease. Unsupportedinthisrelease. Containerforanyofthefollowing ovf:Section_Typeelements:
0 0 0
1 1 1
Item AllEULAsAccepted
0 0
n 1
CompositionItemParamsType xs:boolean
Item
AnItemelementisacontainerforinformationaboutavApptemplate,vApp,orvirtualmachinetobeused whencomposingorrecomposingavApp. Schema
Name sourceDelete Min 0 Max 1 Type xs:boolean Description IftheobjectreferencedinSourceisaVm,this attributespecifieswhethertheVmshouldbe removedfromitsparentvApporcopied. IgnorediftheobjectreferencedinSourceisnot aVm. AreferencetoavAppTemplate,vApp,orVmto includeinthecomposition
Source
ReferenceType
VMware, Inc.
173
Schema (Continued)
Name VAppScopedLocalId Min 0 Max 1 Type xs:string Description IftheobjectreferencedinSourceisaVm,this elementcanbeusedtoprovideaunique identifierforthisVminthecomposedvApp. RequiredifSourceisaVm,andcancontainfor anyofthefollowingovf:Section_Type elements:
InstantiationParams
InstantiationParamsType
NetworkAssignment
NetworkAssignmentType
MapslogicalnetworksintheSourcetological networksinthecomposedvApp
Formoreinformation,seeComposeavApponpage 65.
NetworkAssignment
WhenavAppincludesVmelementsthatconnecttonetworkswithdifferentnames,youcanusea NetworkAssignmentelementtoassignthenetworkconnectionforeachVmtoaspecificnetworkintheparent vApp. Schema
Name innerNetwork containerNetwork Min 1 1 Max 1 1 Type xs:string xs:string Description NameofthenetworkintheVm NameofthevAppnetworktowhichinnerNetworkismapped
RecomposeVAppParams
TheRecomposeVAppParamselementformsthebodyofarecomposeVapprequest.Thiselementallowsan arbitrarynumberofDeleteItemelements,butisotherwiseidenticaltoComposeVAppParams. Content-Type application/vnd.vmware.vcloud.recomposeVAppParams+xml Schema
Name name Description deploy powerOn Min 1 0 0 0 Max 1 1 1 1 Type xs:string xs:string xs:boolean xs:boolean Description SpecifiesthenameofthevAppcreatedbythis composition Optionaldescription.Usedforthe DescriptionofthecomposedvApp TrueifthevAppshouldbedeployedafter composition.Defaultstofalse. TrueifthevAppshouldbedeployedand poweredonaftercomposition.Defaultsto false. Ignoredinthisrelease. Unsupportedinthisrelease containerforanyofthefollowing ovf:Section_Typeelements:
0 0 0
1 1 1
174
VMware, Inc.
Schema (Continued)
Name Item DeleteItem AllEULAsAccepted Min 0 0 0 Max n n 1 Type CompositionItemParamsType ReferenceType xs:boolean Description SpecifiesasourcevAppTemplate,vApp,orVm toincludeinthecomposition ReferencetoaVmtoremovefromthevApp Trueifyouacceptthetermsandconditionsin thetemplatesEULAsections.Composition failsiffalse.
DeployVAppParams
TheDeployVAppParamselementformsthebodyofadeployrequest. Content-Type application/vnd.vmware.vcloud.deployVAppParams+xml Schema
Name powerOn deploymentLeaseSeconds Min 0 0 Max 1 1 Type xs:boolean xs:int Description TrueifthevAppshouldbepoweredonafterdeployment Durationofthedeploymentlease,inseconds
UndeployVAppParams
TheUndeployVAppParamselementformsthebodyofanundeployrequest. Content-Type application/vnd.vmware.vcloud.undeployVAppParams+xml Schema
Name saveState Min 0 Max 1 Type xs:boolean Description Trueifpoweredonchildrenshouldbesuspendedandtheirstatesaved beforeundeployment.Defaultisfalse,specifyingthatchildrenarepowered off.
CaptureVAppParams
TheCaptureVAppParamselementformsthebodyofacaptureVapprequest. Content-Type application/vnd.vmware.vcloud.captureVAppParams+xml Schema
Name name Description Source Min 1 0 1 Max 1 1 1 Type xs:string xs:string ReferenceType Description SpecifiesthenameofthevAppTemplatecreatedbythisoperation Optionaldescription.UsedfortheDescriptionofthevAppTemplate createdbythisoperation. ReferencetothevApptocapture.
VMware, Inc.
175
CloneMediaParams
TheCloneMediaParamselementformsthebodyofacloneMedia request. Content-Type application/vnd.vmware.vcloud.cloneMediaParams+xml Schema
Name name Description Source IsSourceDelete Min 1 0 1 0 Max 1 1 1 1 Type xs:string xs:string ReferenceType xs:boolean Description Specifiesthenameofthenewmediaimagecreatedbytheclone operation Optionaldescription.UsedfortheDescriptionofthecloned Mediaimage. Referencetothemediaimagetoclone(copy) TrueiftheobjectreferencedbySourceshouldbedeletedafter thecopyismade
CloneVAppTemplateParams
TheCloneVAppTemplateParamselementformsthebodyofacloneVAppTemplaterequest. Content-Type application/vnd.vmware.vcloud.cloneVAppTemplateParams+xml Schema
Name name Description Source IsSourceDelete Min 1 0 1 0 Max 1 1 1 1 Type xs:string xs:string ReferenceType xs:boolean Description SpecifiesthenameofthenewvApptemplate createdbythecloneoperation Optionaldescription.UsedfortheDescriptionof theclonedvApptemplate ReferencetothevAppTemplatetoclone(copy) TrueiftheobjectreferencedbySourceshould bedeletedafterthecopyismade
CloneVAppParams
TheCloneVAppParamselementformsthebodyofacloneVapprequest. Content-Type application/vnd.vmware.vcloud.cloneVAppParams+xml Schema
Name name Description deploy powerOn linkedClone VAppParent InstantiationParams Min 1 0 0 0 0 0 0 Max 1 1 1 1 1 1 1 Type xs:string xs:string xs:boolean xs:boolean xs:boolean ReferenceType InstantiationParamsType Description SpecifiesthenameoftheclonedvApp CommonDescriptionelement.Usedforthe Descriptionoftheclone Trueifthecloneshouldbedeployed.Defaultsto false. Trueifthecloneshouldbedeployedand poweredon.Defaultstofalse. Ignoredinthisrelease Unsupportedinthisrelease Containerforanyofthefollowing ovf:Section_Typeelements:
176
VMware, Inc.
Schema (Continued)
Name Source IsSourceDelete Min 1 0 Max 1 1 Type ReferenceType xs:boolean Description ReferencetothevApptoclone(copy) TrueiftheobjectreferencedbySourceshould bedeletedafterthecopyismade
MediaInsertOrEjectParams
AMediaInsertOrEjectParamselementformsthebodyofaninsertMediaorejectMediarequest. Content-Type application/vnd.vmware.vcloud.mediaInsertOrEjectParams+xml Schema
Name Media Min 1 Max 1 Type ReferenceType Description Referencetoamediaimagetoinsertoreject
VmPendingQuestion
TheVmPendingQuestionelementcontainsarequestfromavirtualmachineforuserinput. Content-Type application/vnd.vmware.vcloud.vmPendingQuestion+xml Schema
Name Question QuestionId Choices Min 1 1 1 Max 1 1 n Type xs:string xs:int VmQuestionAnswerChoiceType Description Thequestionrequiringuseinput. Questionidentifier Allowableanswers
VmQuestionAnswer
TheVmQuestionAnswerelementcontainsuserinputtoaspecificVmPendingQuestionrequest. Content-Type application/vnd.vmware.vcloud.vmPendingAnswer+xml Schema
Name ChoiceId QuestionId Min 1 1 Max 1 1 Type xs:int xs:int Description Theanswertoprovide Questionidentifier
ControlAccessParams
TheControlAccessParamselementappearsinCatalogsandvApps.Thiselementcanbereadbyallusersbut canbemodifiedonlybyadministratorsandprivilegedusers. Content-Type application/vnd.vmware.vcloud.controlAccess+xml Schema
Name IsSharedToEveryone EveryoneAccessLevel AccessSettings Min 1 0 0 Max 1 1 1 Type xs:boolean AccessLevelType AccessSettingsType Description Trueifthisobjectissharedwitheveryoneinthe organization.Defaultstofalse. IfIsSharedToEveryoneistrue,thiselementmustbe presentanddeterminestheaccesslevel AcontainerforAccessSettingelements.Thiselement mustbepresentandnotemptyifIsSharedToEveryone isfalse.
VMware, Inc.
177
AccessSettings
TheAccessSettingselementisacontainerforAccessSettingelements.Thiscontainermustbepresentand notemptyifthevalueofIsSharedToEveryoneinthecontainingControlAccessParamselementissetto false.
AccessSetting
AnAccessSettingelementdefinesthelevelofaccessgrantedtotheuserorgroupreferencedintheSubject element. Schema
Name Subject AccessLevel Min 1 1 Max 1 1 Type ReferenceType AccessLevelType Description ReferencetotheuserorgrouptowhichthespecifiedAccessLevel applies. Specifiestheaccesslevelallowedfortheuserorgroupsspecifiedin Subject
AccessLevel
TheAccessLevelelementspecifiestheaccesslevelallowedfortheuserorgroupspecifiedinSubject. Table 101showspermittedvaluesforelementcontentandtheresultstheyproduce. Table 10-1. AccessLevel Element Values
Value FullControl Change ReadOnly Result Subjecthasfullcontrolofthisobject Subjectcanchangethisobject Subjecthasreadaccesstothisobject
178
VMware, Inc.
11
11
VCloudonpage 179 ExternalNetworkonpage 180 AdminOrgonpage 180 ProviderVdconpage 186 Useronpage 190 Grouponpage 191 Roleonpage 191
VCloud
ThevCloudelementisareadonlycontainerforreferencestotoplevelobjectsinavCloudinstance. Content-Type application/vnd.vmware.admin.vcloud+xml Object href prototype APIURL/admin Schema
Name OrganizationReferences ProviderVdcReferences RightReferences RoleReferences Networks Min 0 0 0 0 0 Max 1 1 1 1 1 Type OrganizationReferencesType ProviderVdcReferencesType RightReferencesType RoleReferencesType NetworksType Description AcontainerforreferencestoAdminOrgobjects inthevCloud AcontainerforreferencestoProviderVdc objectsinthevCloud AcontainerforreferencestoRightobjectsin thevCloud AcontainerforreferencestoRoleobjectsin thevCloud Acontainerforreferencesto ExternalNetworkobjectsinthevCloud.
VMware, Inc.
179
OrganizationReferences
TheOrganizationReferenceselementisareadonlycontainerforReferenceTypeelementsthatreference AdminOrgobjectsavCloud.Tocreateaneworganization,seeCreateanOrganizationonpage 95.
ProviderVdcReferences
TheProviderVdcReferenceselementisareadonlycontainerforReferenceTypeelementsthatreference ProviderVdcobjectsavCloud.TocreateaProviderVdc,seeCreateaProvidervDConpage 127.
RightReferences
TheRightReferenceselementisareadonlycontainerforReferenceTypeelementsthatreferencethe predefinedRightobjectsinavCloud.
RoleReferences
TheRoleReferenceselementisareadonlycontainerforReferenceTypeelementsthatreferenceRole objectsinavCloud.Tocreatearole,seeCreateaRoleonpage 114.
Networks
TheNetworkselementisareadonlycontainerforReferenceTypeelementsthatreferenceExternalNetwork objectsinavCloud.ToaddanetworktoanAdminOrg,seeAddaNetworktoanOrganizationonpage 100.
ExternalNetwork
AExternalNetworkelementdefinesanetworkthathasbeenallocatedtoanorganizationbythesystem administrator. Content-Type application/vnd.vmware.vcloud.admin.network+xml Object href prototype APIURL/admin/network/id Schema
Name name anyattributename Description Configuration ProviderInfo Min 1 0 0 0 1 Max 1 n 1 1 1 Type xs:string any xs:string NetworkConfigurationType xs:string Description Commonobjectnameattribute Includestype,href,XMLnamespace identifiers Optionaldescription Propertiesofthenetwork Readonlyinformationaboutthe underlyingvCenternetwork
AdminOrg
TheAdminOrgelementprovidesanadministrativeviewofanorganization.ItincludesallmembersoftheOrg element,andaddsseveralelementsthatcanbeviewedandmodifiedonlybysystemadministrators. Content-Type application/vnd.vmware.admin.organization+xml Object href prototype APIURL/admin/organization/id Schema
Name name anyattributename Min 1 0 Max 1 n Type xs:string any Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers
180
VMware, Inc.
Schema (Continued)
Name Description Tasks Min 0 0 Max 1 1 Type xs:string TasksInProgressType Description Optionaldescription ReadonlycontainerforTaskelements.Eachelementinthe containerrepresentsaqueued,running,orfailedtask ownedbythisobject. Fullnameoftheorganization Establishesquotasandpolicies,specifieshowthe organizationconnectstoLDAPandemailservices ContainerforReferenceTypeelementsthatreference usersintheorganization. ContainerforReferenceTypeelementsthatreference groupsintheorganization. ContainerforReferenceTypeelementsthatreference catalogsintheorganization. ContainerforReferenceTypeelementsthatreference vDCsintheorganization. ContainerforReferenceTypeelementsthatreference networksintheorganization.
1 1 0 0 0 0 0
1 1 1 1 1 1 1
Settings
TheSettingselementestablishesquotasandpoliciesfortheorganization.Italsocontainselementsthat specifythedetailsofhowtheorganizationconnectstoLDAPandemailservices. Schema
Name IsEnabled Min 0 Max 1 Type xs:boolean Description Trueifthisorganizationisenabled.Ifenabled, theorganizationallowsloginandallother operations. Trueifthisorganizationisallowedtopublish catalogs Maximumnumberofvirtualmachinesthatcan bedeployedsimultaneouslybyamemberof thisorganization MaximumnumberofvAppsorvApptemplates thatcanbestored(inanundeployedstate)bya memberofthisorganization Definesdefaultleasedurationsandrelated policies Defineswhetherthisorganizationisconnected toanLDAPservice,andwhetheritusesthe systemdefaultLDAPserviceoracustomLDAP service.Cannotbechangedafterthe organizationhasbeencreated. IfOrgLdapModeisSYSTEM,specifiesanLDAP attribute=valuepairtouseforOU (organizationalunit) Definesthehostnameandconnectiondetailsfor theorganizationsprimaryLDAPservice Definestheemailsettingsforthisorganization
CanPublishCatalogs DeployedVmQuota
0 0
1 1
xs:boolean xs:int
StoredVmQuota
xs:int
OrgLeaseSettings OrgLdapMode
0 0
1 1
OrgLeaseSettingsType LdapModeType
CustomUsersOu
xs:string
OrgLdapSettings OrgEmailSettings
0 0
1 1
OrgLdapSettingsType OrgEmailSettingsType
VMware, Inc.
181
Schema (Continued)
Name UseServerBootSequence DelayAfterPowerOnSeconds Min 0 0 Max 1 1 Type xs:boolean xs:int Description Trueifvirtualmachinesinthisorganizationuse theserverbootsequencebydefault Specifiesanorganizationdefaultforvirtual machinebootdelayafterpoweron
OrgLeaseSettings
TheOrgLeaseSettingselementdefinesdefaultleasedurationsandpoliciesfortheorganization. Schema
Name DeleteOnStorageLeaseExpiration Min 0 Max 1 Type xs:boolean Description Iftrue,storageforavAppisdeletedwhenthevApps leaseexpires.Iffalse,thestorageisflaggedfor deletion,butnotdeleted. DefaultdurationofavAppdeploymentlease,in seconds. Defaultdurationofastoragelease,inseconds.
DeploymentLeaseSeconds StorageLeaseSeconds
0 0
1 1
xs:int xs:int
OrgLdapMode
TheOrgLdapModeelementdefineswhetherthisorganizationisconnectedtoanLDAPservice,andwhetherit usesthesystemdefaultLDAPserviceoracustomLDAPservice.Table 111showspermittedvaluesfor elementcontentandtheresultstheyproduce. NOTEThevalueofOrgLdapModecannotbechangedaftertheorganizationhasbeencreated. Table 11-1. OrgLdapMode Element Values
Value NONE SYSTEM CUSTOM Result OrganizationdoesnotuseanLDAPservice. OrganizationusesthesystemdefaultLDAPservice. OrganizationusesacustomLDAPservicedefinedinOrgLdapSettings
OrgLdapSettings
IfOrgLdapModeisCUSTOM,theOrgLdapSettingselementdefinesthehostnameandconnectiondetailsforthe organizationsLDAPservice. Schema
Name HostName Port IsSsl IsSslAcceptAll Realm SearchBase Min 1 1 0 0 0 0 Max 1 1 1 1 1 1 Type xs:string xs:int xs:boolean xs:boolean xs:string xs:string Description HostnameoftheLDAPserver. PortatwhichtoconnecttotheLDAP service TrueiftheLDAPservicerequiresan SSLconnection TrueiftheLDAPserviceacceptsallSSL certificates LDAPrealmtousewhenlookingup users LDAPsearchbase
182
VMware, Inc.
Schema (Continued)
Name UserName Min 0 Max 1 Type xs:string Description Usernametousewhenlogginginto LDAP,specifiedusingLDAP attribute=valuepairs(forexample: cn="ldap-admin", dc="example", dc="com") Passwordfortheuseridentifiedby UserName.Thisvalueisnever returnedbyGET.Itisinspectedon createandmodify.Onmodify,the absenceofthiselementindicatesthat thepasswordshouldnotbechanged. Definestheauthenticationmechanism usedbytheLDAPservice LDAPgroupsearchbase Trueifthegroupsearchbaseisenabled DefinesthetypeoftheLDAPservice DefineshowLDAPattributesareused whenimportingauser DefineshowLDAPattributesareused whenimportingagroup
Password
xs:string
1 0 1 1 1 1
1 1 1 1 1 1
AuthenticationMechanism
TheAuthenticationMechanismelementdefinestheauthenticationmechanismusedbytheLDAPservice. Table 112showspermittedvaluesforelementcontentandtheresultstheyproduce. Table 11-2. AuthenticationMechanism Element Values
Value SIMPLE KERBEROS MD5DIGEST NTLM Result LDAPconnectionusessimpleauthenticationasspecifiedinRFC2251andRFC2829. LDAPconnectionusesKerberosauthentication. LDAPconnectionusesDigestMD5authenticationasspecifiedinRFC2831. LDAPconnectionusesWindowsNTLMauthentication.
ConnectorType
TheConnectorTypeelementdefinesthetypeofanLDAPservice.Table 113showspermittedvaluesfor elementcontentandtheresultstheyproduce. Table 11-3. ConnectorType Element Values
Value ACTIVE_DIRECTORY OPEN_LDAP Result LDAPserviceisprovidedbyWindowsActiveDirectory LDAPserviceisprovidedbyOpenLDAP(seehttp://www.openldap.org).
VMware, Inc.
183
UserAttributes
IfOrgLdapModeisCUSTOM,theUserAttributeselementdefineshowLDAPattributesareusedwhen importingauser. Schema
Name ObjectClass ObjectIdentifier UserName Min 1 1 1 Max 1 1 1 Type xs:string xs:string xs:string Description LDAPobjectClassofwhichimportedusersare members.Forexample,userorperson LDAPattributetouseastheuniqueidentifierfora user.Forexample,objectGuid LDAPattributetousewhenlookingupausername toimport.Forexample,userPrincipalNameor samAccountName LDAPattributetousefortheusersemailaddress. Forexamplemail LDAPattributetousefortheusersfullname.For exampledisplayName LDAPattributetousefortheusersgivenname.For example,givenName LDAPattributetousefortheuserssurname.For examplesn LDAPattributetousefortheuserstelephone number.ForexampletelephoneNumber LDAPattributethatidentifiesauserasamemberof agroup.Forexample,dn LDAPattributethatreturnstheidentifiersofallthe groupsofwhichtheuserisamember
1 1 1 1 1 1 0
1 1 1 1 1 1 1
GroupAttributes
IfOrgLdapModeisCUSTOM,theGroupAttributeselementdefineshowagroupisimportedfromLDAP. Schema
Name ObjectClass ObjectIdentifier GroupName Membership MembershipIdentifier BackLinkIdentifier Min 1 1 1 1 1 0 Max 1 1 1 1 1 1 Type xs:string xs:string xs:string xs:string xs:string xs:string Description LDAPobjectClassofwhichimportedgroupsaremembers.For example,group LDAPattributetouseastheuniqueidentifierforagroup.For example,objectGuid LDAPattributetouseforthegroupname.Forexample,cn LDAPattributetousewhengettingthemembersofagroup.For example,member LDAPattributethatidentifiesagroupasamemberofanother group.Forexample,dn LDAPgroupattributeusedtoidentifyagroupmember
184
VMware, Inc.
OrgEmailSettings
TheOrgEmailSettingselementdefinestheemailsettingsforanorganization. Schema
Name IsDefaultSmtpServer IsDefaultOrgEmail FromEmailAddress Min 1 1 1 Max 1 1 1 Type xs:boolean xs:boolean xs:string Description Trueifthisorganizationusesthesystemdefault SMTPserver Trueifthisorganizationusesthesystemdefault emailproperties. IfIsDefaultOrgEmailisfalse,specifiesthe sendersemailaddressthatappearsinemail notifications. IfIsDefaultOrgEmailisfalse,specifiesaprefix forsystememailnotifications. Trueifsystememailnotificationsshouldbesent toalluserswhohavetheAdministratorrole IfIsAlertEmailToAllAdminsisfalse,specifies alistofuserstoreceivesystememail notifications. IfIsDefaultSmtpServerisFalse,thiselement specifiesconnectiondetailsforanSMTPserver touse.
1 1 0
1 1 n
SmtpServerSettings
SmtpServerSettingsType
SmtpServerSettings
IfIsDefaultSmtpServer(inOrgEmailSettings)isfalse,theSmtpServerSettingselementspecifies connectiondetailsfortheorganizationsSMTPserver. Schema
Name IsUseAuthentication Host Username Password Min 1 1 1 0 Max 1 1 1 1 Type xs:boolean xs:string xs:string xs:string Description TrueiftheSMTPserverrequiresauthentication HostnameoftheSMTPserver. UsernametousewhenloggingintotheSMTPservice. (RequiredifIsUseAuthenticationisTrue). PasswordfortheuseridentifiedbyUsername.Thisvalue isneverreturnedbyGET.Itisinspectedoncreateand modify.Onmodify,theabsenceofthiselementindicates thatthepasswordshouldnotbechanged.Requiredif IsUseAuthenticationistrue.
Users
TheUserselementisareadonlycontainerforReferenceTypeelementsthatreferenceusersinan organization.Toadduserstoanorganization,seeCreateorImportaUseronpage 110.
Groups
TheGroupselementisareadonlycontainerforReferenceTypeelementsthatreferencegroupsinan organization.Toaddgroupstoanorganization,seeImportaGrouponpage 113.
Catalogs
TheCatalogselementisareadonlycontainerforReferenceTypeelementsthatreferencethecatalogsinan organization.Toaddcatalogstoanorganization,seeCreateaCatalogonpage 107.
VMware, Inc.
185
Catalog
ACatalogelementisacontainerforCatalogItems.AnOrgorAdminOrgmaycontainzeroormoreCatalog elements.Tocreate,delete,ormodifyacatalog,anadministratormustaccessitusingtheadminURLand contenttypeshownhere. Content-Type application/vnd.vmware.vcloud.admin.catalog+xml Object href prototype vCloudURL/admin/catalog/catalogid FormoreinformationabouttheCatalogelementschema,seeCatalogonpage 160.Forinformationabout useroperationsonCatalogs,seeCatalogingvAppTemplatesandMediaImagesonpage 54.
PublishCatalogParams
ThePublishCatalogParamselementformsthebodyofapublishrequestforacatalog. Schema
Name IsPublished Min 1 Max 1 Type xs:boolean Description Settotruetopublishacatalog(makeitvisibletoallorganizations).Setto falsetounpublishacatalog.Thiselementcanbechangedonlyinapublish request.ItisReadonlyinaCatalogbody.
Vdcs
TheVdcselementisareadonlycontainerforReferenceTypeelementsthatreferencevDCsinan organization.ToaddavDCtoanorganization,seeAllocateavDCtoanOrganizationonpage 104.
ProviderVdc
AProviderVdcelementrepresentsaprovidervDCobject. Content-Type application/vnd.vmware.admin.providervdc+xml Object href prototype APIURL/admin/providervdc/id Schema
Name name anyattributename status Min 1 0 0 Max 1 n 1 Type xs:string any xs:int Description Commonobjectnameattribute Includestype,href,XMLnamespace identifiers creationstatusoftheProviderVdc:
Description Tasks
0 0
1 1
xs:string TasksInProgressType
Optionaldescription ReadonlycontainerforTaskelements.Each elementinthecontainerrepresentsa queued,running,orfailedtaskownedby thisobject Definesthecomputecapacityavailablein thisprovidervDC Definesthestoragecapacityavailableinthis providervDC Containerforreferencesto ExternalNetworkobjectsprovisionedfrom thisprovidervDC.
0 0 0
1 1 1
186
VMware, Inc.
Schema (Continued)
Name Vdcs IsEnabled NetworkPoolReferences Min 0 0 0 Max 1 1 1 Type VdcsType xs:boolean NetworkPoolReferencesType Description ContainerforVdcobjectsthatare provisionedfromthisprovidervDC. TrueifthisprovidervDCisenabled ContainerforNetworkPoolReference objectsthatareprovisionedfromthis providervDC
ComputeCapacity
TheadministrativeviewofaComputeCapacityelementincludestwoelements:IsElasticandIsHa,thatan administratorcanchange.Theseelementsarenotvisibleintheuserview. Schema
Name Cpu Memory IsElastic IsHA Min 1 1 0 0 Max 1 1 1 1 Type ProviderVdcCapacityType ProviderVdcCapacityType xs:boolean xs:boolean Description DefinesCPUcapacityavailableintheprovidervDC DefinesmemorycapacityavailableintheprovidervDC Trueifcomputecapacitycangroworshrinkbasedondemand Trueifcomputecapacityishighlyavailable.
Cpu
UnliketheCpuelementthatappearsintheComputeCapacityofaVdc,theCpuelementthatappearsinthe ComputeCapacityofaProviderVdcisaninstanceofProviderVdcCapacityType.ItdefinestheCPU capacitythatcanbeallocatedfromavDCandoptionallyreportshowmuchofthatcapacityisinuse. Schema
Name Units Allocation Total Used Overhead Min 1 0 1 0 0 Max 1 1 1 1 1 Type xs:string xs:long xs:long xs:long xs:long Description Unitsinwhichthecapacityismeasured.ForCPUdevices,thisisalways Megahertz,representedbythestringMHz. NumberofUnitsthathavebeenallocatedtoconsumers MaximumnumberofUnitsthatcanbeallocatedtoallconsumers Percentageoftheallocationinuse.Thisvalueisreadonly,andisalways0if AllocationModelisAllocationVApp. NumberofUnitsallocatedtovShieldManagervirtualmachinesprovisioned fromthisvDC.Thisvalueisreadonly,andisalways0ifAllocationModelis AllocationVApp.
Memory
UnliketheMemoryelementthatappearsintheComputeCapacityofaVdc,theMemoryelementthatappears intheComputeCapacityofaProviderVdcisaninstanceofProviderVdcCapacityType.Itdefinesthe memorycapacitythatcanbeallocatedfromavDCandoptionallyreportshowmuchofthatcapacityisinuse. Schema
Name Units Allocation Total Min 1 0 1 Max 1 1 1 Type xs:string xs:long xs:long Description Specifiestheunitsinwhichthecapacityismeasured.Forstoragedevices,thisis alwaysMegabytes,representedbythestringMB. NumberofUnitsthathavebeenallocatedtoconsumers.Thisvalueisreadonly, andisalways0ifAllocationModelisAllocationVApp. MaximumnumberofUnitsthatcanbeallocatedtoallconsumers.Thisvalueis readonly,andisalways0ifAllocationModelisAllocationVApp.
VMware, Inc.
187
Schema
Name Used Overhead Min 0 0 Max 1 1 Type xs:long xs:long Description Percentageoftheallocationinuse.Thisvalueisreadonly. NumberofUnitsallocatedtovShieldManagervirtualmachinesprovisioned fromthisvDC.Thisvalueisreadonly.
StorageCapacity
TheadministrativeviewofaStorageCapacitydefinestheamountofstorageavailableinaProvidervDCand optionallyreportshowmuchofthatcapacityisinuse. Schema
Name Units Allocation Total Used Overhead Min 1 0 1 0 0 Max 1 1 1 1 1 Type xs:string xs:long xs:long xs:long xs:long Description Unitsinwhichthecapacityismeasured.ForCPUdevices,thisisalways Megahertz,representedbythestringMHz. NumberofUnitsthathavebeenallocatedtoconsumers TotalnumberofUnitsthatcanbeallocatedtoallconsumers Percentageoftheallocationinuse.Thisvalueisreadonly. NumberofUnitsallocatedtovShieldManagervirtualmachinesprovisioned fromthisprovidervDC.Thisvalueisreadonly.
NetworkPoolReferences
TheNetworkPoolReferenceselementisareadonlycontainerforNetworkPoolReferenceelements.
NetworkPoolReference
ANetworkPoolReferenceelementisaReferenceTypeelementthatreferencesanetworkpoolinaprovider vDC.Thiselementisreadonly.
VdcReferences
TheVdcReferenceselementisareadonlycontainerforVdcReferenceelementsthatreferenceorganization vDCssupportedbythisprovidervDC. Content-Type application/vnd.vmware.vcloud.admin.vdcreferences+xml Schema
Name anyattributename Link VdcReference Min 0 0 0 Max n n n Type any LinkType ReferenceType Description Includestype,href,XMLnamespace identifiers LinktocontainingprovidervDC ReferencetoanorganizationvDCs supportedbythisprovidervDC
AdminVdc
TheAdminVdcelementprovidesanadministrativeviewofavDC.ItincludesallmembersoftheVdcelement, andaddsseveralelementsthatcanbeviewedandmodifiedonlybyadministrators. Content-Type application/vnd.vmware.admin.vdc+xml Object href prototype APIURL/admin/vdc/id
188
VMware, Inc.
Schema
Name name anyattributename status Min 1 0 0 Max 1 n 1 Type xs:string any xs:int Description Commonobjectnameattribute Includestype,href,XMLnamespace identifiers ThecreationstatusofthevDC:
Description Tasks
0 0
1 1
xs:string TasksInProgressType
Optionaldescription ReadonlycontainerforTaskelements. Eachelementinthecontainerrepresents aqueued,running,orfailedtaskowned bythisobject. Defineshowresourcesareallocatedby thevDC Definesthestoragecapacityavailablein thevDC Definesthecomputecapacityavailable inthevDC ContainerforResourceEntityelements ContainerforNetworkelementsthat referenceOrgNetworkobjectscontained bythevDC MaximumnumberofvirtualNICs allowedinthisvDC.Defaultsto0,which specifiesanunlimitednumber. MaximumnumberofOrgNetwork objectsthatcanbedeployedinthisvDC. Defaultsto0,whichspecifiesan unlimitednumber. Maximumnumberofvirtualmachines thatcanbedeployedinthisvDC. Defaultsto0,whichspecifiesan unlimitednumber. TrueifthisvDCisenabled Percentageofallocatedmemory resourcesguaranteedtovApps deployedinthisvDC.Forexample,if thisvalueis0.75,then75%ofallocated resourcesareguaranteed.Required whenAllocationModelis AllocationVApporAllocationPool. Valuedefaultsto1.0iftheelementis empty. PercentageofallocatedCPUresources guaranteedtovAppsdeployedinthis vDC.Forexample,ifthisvalueis0.75, then75%ofallocatedresourcesare guaranteed.Requiredwhen AllocationModelisAllocationVApp orAllocationPool.Valuedefaultsto 1.0iftheelementisempty.
1 1 1 0 0
1 1 1 1 1
NicQuota
xs:int
NetworkQuota
xs:int
VmQuota
xs:int
IsEnabled ResourceGuaranteedMemory
0 0
1 1
xs:boolean xs:double
ResourceGuaranteedCpu
xs:double
VMware, Inc.
189
Schema (Continued)
Name VCpuRatingMHz Min 0 Max 1 Type xs:long Description Specifiesaclockfrequency,in Megahertz,foreachvirtualCPUcore provisionedfromthisvDC Trueifthinprovisioninghasbeen enabledforthisvDC Referencetoanetworkpoolinthe providervDCreferencedby ProviderVdcReference ReferencetotheProviderVdcfrom whichthisvDCisprovisioned
IsThinProvision NetworkPoolReference
0 0
1 1
xs:boolean ReferenceType
ProviderVdcReference
ReferenceType
AllocationModel
TheAllocationModelelementdefineshowresourcesareallocatedinavDC.Table 114showspermitted valuesforelementcontentandtheresultstheyproduce. Table 11-4. AllocationModel Element Values
Value AllocationVApp AllocationPool ReservationPool Result ResourcesarecommittedtoavDConlywhenvAppsarecreatedinit OnlyapercentageoftheresourcesyouallocatearecommittedtotheorganizationvDC. AlltheresourcesyouallocatearecommittedasapooltotheorganizationvDC.vAppsinvDCs thatsupportthisallocationmodelcanspecifyvaluesforresourceandlimit.
User
AUserobjectdefinesamemberofanorganizationorgroup. Content-Type application/vnd.vmware.admin.user+xml Object href prototype APIURL/admin/user/id Schema
Name name anyattributename Description FullName EmailAddress Telephone IsEnabled IM NameInSource IsAlertEnabled AlertEmailPrefix AlertEmail isExternal IsDefaultCached IsGroupRole Min 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 Max 1 n 1 1 1 1 1 1 1 1 1 1 1 1 1 Type xs:string any xs:string xs:string xs:string xs:string xs:boolean xs:string xs:string xs:boolean xs:string xs:string xs:boolean xs:boolean xs:boolean Description Commonobjectnameattribute.Thenameoftheuser. Includestype,href,XMLnamespaceidentifiers Optionaldescription Usersfullname. Usersemailaddress Userstelephonenumber Trueiftheusercanlogin Usersinstantmessagingaddress Usernameasretrievedfrom,andintheencodingused by,LDAP Trueifalertsareenabledfortheuser StringtoprependtoalertmessageSubjectline Alertemailaddress TrueifthisuserwasimportedfromLDAP Trueifthisuseriscached Trueifthisuserhasagrouprole
190
VMware, Inc.
Schema (Continued)
Name StoredVmQuota DeployedVmQuota Role Min 0 0 0 Max 1 1 1 Type xs:int xs:int ReferenceType Description QuotaofvAppsthatthisusercanstore.Avalueof0 specifiesanunlimitedquota. QuotaofvAppsthatthisusercandeployconcurrently. Avalueof0specifiesanunlimitedquota Areferencetotheusersrole.Whenyouarecreatinga User,therequestbodymustcontainexactlyoneRole element. Theuserspassword.Thisvalueisneverreturnedby GET.Itisinspectedoncreateandmodify.Onmodify, theabsenceofthiselementindicatesthatthepassword shouldnotbechanged. ContainerforReferenceTypeelementsthatreference groupsofwhichthisuserisamember
Password
xs:string
GroupReferences
GroupsListType
Group
AGroupobjectdefinesagroup. Content-Type application/vnd.vmware.admin.group+xml Object href prototype APIURL/admin/group/id Schema
Name name anyattributename Description NameInSource UsersList Role Min 1 0 0 0 0 0 Max 1 n 1 1 1 1 Type xs:string any xs:string xs:string UsersListType ReferenceType Description Commonobjectnameattribute.TheGroupsname. Includestype,href,XMLnamespaceidentifiers Optionaldescription Groupnameasretrievedfrom,andintheencoding usedby,LDAP Alistofreferencestousersinthegroup Referencetothegroupsrole.
Role
TheRoleelementcontainsasingleRightReferenceselement,whichisacontainerforRightReference elements. Content-Type application/vnd.vmware.admin.role+xml Object href prototype APIURL/admin/role/id
RightReferences
TheRightReferenceselementisacontainerforzeroormoreRightReferenceelements.
RightReference
TheRightReferenceelementcontainsareferencetoaRight. Schema
Name Right Min 1 Max 1 Type ReferenceType Description AreferencetoarightdefinedinthevCloud.
VMware, Inc.
191
Right
RightelementsarepredefinedbyServiceManager.Theyarereadonlytousersandadministrators,andcan beretrievedwithaGEToperationthatspecifiestheURLinaRightReference.Formoreinformation,see GetanAdministrativeViewofaCloudonpage 93. Content-Type application/vnd.vmware.admin.right+xml Object href prototype APIURL/admin/right/id Schema
Name name Description Category Min 1 0 1 Max 1 1 1 Type xs:string xs:string xs:string Description Nameoftheright Optionaldescriptionoftheright. Optionalcategoryname
192
VMware, Inc.
12
12
VMWExtensiononpage 193 VimServeronpage 194 VmObjectRefsListonpage 195 ResourcePoolListonpage 196 ShieldManageronpage 196 VMWProviderVdconpage 197 VMWNetworkPoolonpage 198 VMWExternalNetworkonpage 199 VMWHostReferencesonpage 199 RequestParametersonpage 200
VMWExtension
TheVMWExtensionelementisareadonlycontainerforlinkstovCenterserversregisteredtoCloudDirector andvSphereobjectssuchasESX/ESXihosts,resourcepoolsandnetworks. Content-Type application/vnd.vmware.admin.vmwExtension+xml Object href prototype APIURL/admin/extension Schema
Name href type anyattributename Link Min 1 0 0 0 Max 1 1 n n Type xs:anyURI xs:string any LinkType Description Objectreference Mediatypeoftheelement (application/vnd.vmware.admin.vmwExtension+xml) IncludesXMLNamespaceIdentifiers. Linkstoactionsandcontainedobjects.
VMware, Inc.
193
VMWProviderVdcReferences
TheVMWProviderVdcReferenceselementisareadonlycontainerforProviderVdcReferenceelements. Content-Type application/vnd.vmware.admin.vmwProviderVdcReferences+xml Object href prototype APIURL/admin/extension/providerVdcReferences
VMWExternalNetworkReferences
TheVMWExternalNetworkReferenceselementisareadonlycontainerforExternalNetworkReference elements. Content-Type application/vnd.vmware.admin.vmwExternalNetworkReferences+xml Object href prototype APIURL/admin/extension/externalNetworkReferences
VMWNetworkPoolReferences
TheVMWNetworkPoolReferenceselementisareadonlycontainerforNetworkPoolReferenceelements. Content-Type application/vnd.vmware.admin.vmwNetworkPoolReferences+xml Object href prototype APIURL/admin/extension/networkPoolReferences
VMWVimServerReferences
TheVMWVimServerReferenceselementisareadonlycontainerforVimServerReferenceelements. Content-Type application/vnd.vmware.admin.vmwVimServerReferences+xml Object href prototype APIURL/admin/extension/vimServerReferences
VMWHostReferences
TheVMWHostReferenceselementisareadonlycontainerforHostReferenceelements. Content-Type application/vnd.vmware.admin.vmwHostReferences+xml Object href prototype APIURL/admin/extension/hostReferences
VimServer
AVimServerobjectrepresentsavCenterserver. Content-Type application/vnd.vmware.admin.vmwvirtualcenter+xml Object href prototype APIURL/admin/extension/vimServer/id Schema
Name name anyattributename Description Tasks Min 1 0 0 0 Max 1 n 1 1 Type xs:string any xs:string TasksInProgressType Description Commonobjectnameattribute Includestype,href,XMLNamespaceIdentifiers Optionaldescription ReadonlycontainerforTaskelements.Each elementinthecontainerrepresentsaqueued, running,orfailedtaskownedbythisobject. UsernameoftheadministratorofthisvCenter server
Username
xs:string
194
VMware, Inc.
Schema (Continued)
Name Password Min 0 Max 1 Type xs:string Description PasswordfortheuseridentifiedbyUsername.This valueisneverreturnedbyGET.Itisinspectedon createandmodify.Onmodify,theabsenceofthis elementindicatesthatthepasswordshouldnotbe changed. URL,includingport,tousewhenconnectingtothis vCenterserverwithavSphereclient TrueiftheserverisenabledforusewithCloud Director TrueifthisvCenterisreadytobeusedbythe vCloud IPaddressoftheassociatedvShieldManager UsernameofvShieldManageradministrator
1 1 0 0 0
1 1 1 1 1
VmObjectRefsList
TheVmObjectRefsListelementisareadonlycontainerforVmObjectRefelements. Content-Type application/vnd.vmware.admin.vmsobjectrefslist+xml Object href prototype APIURL/admin/extension/vimServer/id/vmsList
VimObjectRef
TheVimObjectRefelementisareferencetoaVirtualInfrastructureManagementobject. Schema
Name VimServerRef MoRef VimObjectType Min 1 1 1 Max 1 1 1 Type ReferenceType xs:string VimObjectTypeEnum Description Referencetotheserverhostingthisobject ManagedobjectIDofthisobject Typeofthisobject
VimObjectType
TheVimObjectTypeelementdefinesthetypeofaVirtualInfrastructureManagementobject.Table 121shows permittedvaluesforelementcontent.Thesevaluesarereadonly. Table 12-1. VimObjectType Element Values
Value RESOURCE_POOL DATASTORE HOST VIRTUAL_MACHINE VIRTUAL_APP NETWORK DV_PORTGROUP DV_SWITCH Object Type Theobjectisaresourcepool. TheobjectisavSpheredatastore. TheobjectisanESXhost. Theobjectisavirtualmachine. TheobjectisavApp. Theobjectisanexternalnetwork. Theobjectisadistributedvirtualportgroup Theobjectisadistributedvirtualswitch.
VMware, Inc.
195
ResourcePoolList
TheResourcePoolListelementisareadonlycontainerforResourcePoolelements. Content-Type application/vnd.vmware.admin.resourcepoollist+xml Object href prototype APIURL/admin/extension/vimServer/id/resourcePoolList
ResourcePool
TheResourcePoolelementincludestheMoRef(managedobjectID)ofthepoolitselfandadditional DataStoreRefsforeachdatastoreinapool. Schema
Name MoRef VimObjectType DataStoreRefs Min 1 1 0 Max 1 1 1 Type xs:string VimObjectTypeEnum VimObjectRefsType Description ManagedobjectIDofthisobject Typeofthisobject Readonlycontainerforreferencestodatastoresin thisresourcepool
ShieldManager
TheShieldManagerobjectrepresentsavShieldManagerserver. Content-Type application/vnd.vmware.admin.vmwvirtualcenter+xml Object href prototype APIURL/admin/extension/shieldmanager/id Schema
Name name anyattributename Description Tasks Min 1 0 0 0 Max 1 n 1 1 Type xs:string any xs:string TasksInProgressType Description Commonobjectnameattribute Includestype,href,XMLNamespaceIdentifiers Optionaldescription ReadonlycontainerforTaskelements.Eachelement inthecontainerrepresentsaqueued,running,or recentlycompletedTaskownedbythisorganization. UsernameoftheadministratorofthisvShield Managerserver PasswordfortheuseridentifiedbyUsername.This valueisneverreturnedbyGET.Itisinspectedon createandmodify.Onmodify,theabsenceofthis elementindicatesthatthepasswordshouldnotbe changed. URL,includingport,tousewhenconnectingtothis vShieldManagerserverwithavSphereclient ReferencetothevCenterserverassociatedwiththis vShieldManagerserver
Username Password
1 0
1 1
xs:string xs:string
Url AssociatedVimServer
1 0
1 1
xs:anyURI ReferenceType
196
VMware, Inc.
VMWProviderVdc
AVMWProviderVdcobjectrepresentsaprovidervDC. Content-Type application/vnd.vmware.admin.vmwprovidervdc+xml Object href prototype APIURL/admin/extension/providervdc/id Schema
Name name anyattributename status Min 1 0 0 Max 1 n 1 Type xs:string any xs:int Description Commonobjectnameattribute Includestype,href,XMLNamespace Identifiers ThecreationstatusoftheProviderVdc:
Description Tasks
0 0
1 1
xs:string TasksInProgressType
Optionaldescription ReadonlycontainerforTaskelements.Each elementinthecontainerrepresentsa queued,running,orrecentlycompletedTask ownedbythisorganization. Definesthecomputecapacityavailablein thisprovidervDC Definesthestoragecapacityavailableinthis providervDC ReadonlycontainerforNetworkelements thatreferenceexternalnetworkscontained bytheprovidervDC ReadonlycontainerforreferencestoVdc objectsthatareprovisionedfromthis providervDC. TrueifthisprovidervDCisenabled ContainerforNetworkPoolReference elements ContainerforVimObjectRefelementsof typeDATASTORE Referencetotheresourcepoolbackingthis providervDC(VimObjectRefelementof typeRESOURCE_POOL) ReferencetothevCenterserverhostingthe datastorescontainedinDataStoreRefsand theresourcepoolcontainedin ResourcePoolRef ReadonlycontainerforHostobjects
0 0 0
1 1 1
Vdcs
VdcsType
0 0 1 1
1 1 1 1
VimServer
ReferenceType
HostReferences
HostsType
VMware, Inc.
197
VMWNetworkPool
TheVMWNetworkPoolelementrepresentsanetworkpool.Therearethreedifferenttypesofthiselement,allof whichhavethesamename,VMWNetworkPool,andaredistinguishedinrequestbodiesbythevalueofthe HTTPContentTypeheader.
FencePoolType
AVMWNetworkPooloftheFencePoolTyperepresentsanetworkpoolbackedbyoneormorevSphereisolated networks. Content-Type application/vnd.vmware.admin.fencePool+xml Schema
Name name anyattributename Description FenceIdCount VlanId VimSwitchRef UsedNetworksCount Min 1 0 0 1 1 1 0 Max 1 n 1 1 1 1 1 Type xs:string any xs:string xs:int xs:int VimObjectRefType xs:int Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers Optionaldescription NumberoffenceIDsinthispool Setto0fornoVLAN ReferencetotheswitchthatsupportsthisVLAN Readonlyindicationofhowmanynetworksinthis poolareinuse
PortGroupPoolType
AVMWNetworkPoolofthePortGroupPoolTyperepresentsanetworkpoolbackedbyoneormorevSphere portgroups. Content-Type application/vnd.vmware.admin.portGroupPool+xml Schema
Name name anyattributename Description PortGroupRefs VimServer UsedNetworksCount Min 1 0 0 1 1 0 Max 1 n 1 1 1 1 Type xs:string any xs:string VimObjectRefsType ReferenceType xs:int Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers Optionaldescription ReferencestotheportgroupsthatsupportthisVLAN Referencetotheserverhostingthisobject Readonlyindicationofhowmanynetworksinthis poolareinuse
VlanPoolType
AVMWNetworkPooloftheVlanPoolTyperepresentsanetworkpoolbackedbyoneormorevSphereVLANs. Content-Type application/vnd.vmware.admin.vlanPool+xml Schema
Name name anyattributename Description VlanRange Min 1 0 0 1 Max 1 n 1 n Type xs:string any xs:string NumericRangeType Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers Optionaldescription DefinesarangeofVLANIDs
198
VMware, Inc.
Schema (Continued)
Name VimSwitchRef UsedNetworksCount Min 1 0 Max 1 1 Type VimObjectRefType xs:int Description ReferencetotheswitchthatsupportsthisVLAN Readonlyindicationofhowmanynetworksinthis poolareinuse
VMWExternalNetwork
TheVMWExternalNetworkelementdefinesanexternalnetwork. Content-Type application/vnd.vmware.vcloud.admin.network+xml Object href prototype APIURL/admin/extension/externalnet/id Schema
Name name anyattributename Description Configuration VimPortGroupRef Min 1 0 0 0 1 Max 1 n 1 1 1 Type xs:string any xs:string NetworkConfigurationType VimObjectRefType Description Commonobjectnameattribute Includestype,href,XMLnamespaceidentifiers Optionaldescription Propertiesofthenetwork Referencetotheportgroupthatsupportsthis network
VlanRange
TheVlanpRangeelementdefinesarangeofVLANIDs. Schema
Name Start End Min 1 1 Max 1 1 Type xs:int xs:int Description LowestVLANIDintherange HighestVLANIDintherange
VMWHostReferences
TheVMWHostReferenceselementisareadonlycontainerforHostelementsrepresentingthehostsina specificprovidervDC.
Host
AHostobjectrepresentsanESX/ESXihostinaprovidervDC. Content-Type application/vnd.vmware.admin.+xml Object href prototype APIURL/admin/extension/host/id Schema
Name name anyattributename Description Tasks Min 1 0 0 0 Max 1 n 1 1 Type xs:string any xs:string TasksInProgressType Description Commonobjectnameattribute Includestype,href,XMLNamespaceIdentifiers. Optionaldescription ReadonlycontainerforTaskelements.Each elementinthecontainerrepresentsaqueued, running,orfailedTaskownedbythisobject. Linkstocontainedobjects.
Link
LinkType
VMware, Inc.
199
Schema (Continued)
Name Ready Available Enabled Busy EnableHostForHostSpanning Min 1 1 1 1 1 Max 1 1 1 1 1 Type xs:boolean xs:boolean xs:boolean xs:boolean xs:boolean Description Trueifthehostisready Trueifthehostisavailable TrueifthehostisenabledforusewithCloud Director Trueifthehostisbusy Trueifthehostisenabledforhostspanning.If true,thehostcannotbeputinstandbyor maintenancemode. CPUtypeofthehost NumberoflogicalCPUs NumberofCPUpackages TotalCPUcapabilityofthishost Memoryreserved Totalmemory Hostoperatingsystemname Hostoperatingsystemversion vCentermessagesforthishost URLforhostpropertypageinvSphere vSpheremanagedobjectreferenceforthisobject
CpuType NumOfCpusLogical NumOfCpusPackages CpuTotal MemUsed MemTotal HostOsName HostOsVersion SystemMessages VimPropertyPageUrl VmMoRef
0 1 1 1 1 1 0 0 0 0 0
1 1 1 1 1 1 1 1 1 1 1
xs:string xs:int xs:int xs:long xs:double xs:double xs:string xs:string xs:string xs:string xs:string
Request Parameters
ThevSpherePlatformextensionsdefinedseveralelementsthatprovideparameterstorequeststhatcreate, delete,modify,orchangethestateofavSpherePlatformobject.
PrepareHostParams
ThePrepareHostParamselementformsthebodyofaprepareorunpreparerequestforanESXhost. Schema
Name Username Password Min 1 1 Max 1 1 Type xs:string xs:string Description Usernameofahostadministrator PasswordforspecifiedUsername
RegisterVimServerParams
TheRegisterVimServerParamselementformsthebodyofaregistervimserverrequest. Schema
Name VimServer ShieldManager Min 1 1 Max 1 1 Type VimServerType ShieldManagerType Description vCenterservertoregister vShieldManagerassociatedwiththevCenterservertoregister
200
VMware, Inc.
ImportVmAsVAppParams
TheImportVmAsVAppParamselementformsthebodyofanimportVmAsVApprequest. Schema
Name name sourceMove deploy powerOn Description InstantiationParams Min 1 0 0 0 0 0 Max 1 1 1 1 1 1 Type xs:string xs:boolean xs:boolean xs:boolean xs:string InstantiationParamsType Description SpecifiesthenameofthevAppcreatedbythis operation TrueiftheimportedVMshouldberemovedfrom thesourcevCenter Notsupportedinthisrelease Notsupportedinthisrelease Optionaldescription Containerforanyofthefollowing ovf:Section_Typeelements:
0 0 0 1 1
1 1 1 1 1
ImportVmAsVAppTemplateParams
TheImportVmAsVAppTemplateParamselementformsthebodyofanimportVmAsVAppTemplaterequest. Schema
Name name sourceMove Description VmMoRef Vdc Catalog Min 1 0 0 1 1 Max 1 1 1 1 1 Type xs:string xs:boolean xs:string xs:string ReferenceType ReferenceType Description SpecifiesthenameofthevAppcreatedbythis operation TrueiftheimportedVMshouldberemovedfromthe sourcevCenter Optionaldescription ManagedobjectreferenceoftheVMtoimport URLofthetargetvDC Referencetoacataloginwhichthetemplatewillbe included.Ifthiselementisomittedorempty,the templateisimportedintothetargetvDCbutnot referencesinanycatalog. Virtualmachinename Readonlyidentifiercreatedonimport Displaynameofthisvirtualmachine
0 0 0
1 1 1
VMware, Inc.
201
202
VMware, Inc.
TheOpenVirtualizationFormat(OVF)isanopen,portable,efficientandextensibleformatforpackagingand distributingvirtualsystems.OVFwasdevelopedbytheDistributedManagementTaskForce(DMTF),a notforprofitassociationofindustrymembersdedicatedtopromotingenterpriseandsystemsmanagement andinteroperability.FormoreinformationabouttheDMTFandOVF,visithttp://www.dmtf.org. ThevCloudAPIsupportsVersion1oftheOVFstandard.Inparticular,itsupportsuploadingand downloadingvApptemplatesasOVFpackages.Inaddition,vApp,Vm,andvAppTemplateelements incorporateanumberofovf:Section_Typeelementsintheirdefinitionsofvirtualmachines(seeSection onpage 163fordetailsonhowthesesectionsareused). NOTEThevCloudAPIsupportsuploadingOVF1.0andOVF1.1,anddownloadingOVF1.0.OVF1.1 packagesareconvertedtoOVF1.0fordownload. Thisappendixincludesthefollowingtopics:
About OVF
Becauseitisawidelyacceptedstandardformat,OVFprovidesconsiderableflexibilityinaccommodatingthe needsofadiversecollectionofvirtualizationtechnologies.Whilethisflexibilityentailsmorecomplexitythan avendorspecificformatmightrequire,italsoprovidesmanyadvantages.
VMware, Inc.
203
Virtual Machines
AnOVFEnvelopecollectsallofthemetadatathatdescribesasinglevirtualmachineintoaVirtualSystem element.AnEnvelopethatcontainsmorethanoneVirtualSystemcollectsthemintoa VirtualSystemCollectionelement.Thisarrangementsupportspackagingagroupofrelatedvirtual machinesasasingleobject,andincludesprovisionsforspecifyingglobalparameterssuchasvirtualmachine startuporder,networkconnections,andarangeofresourceconfigurations(suchasprocessingpowerand memory)towhichthevirtualmachinescanbedeployed. ThevCloudAPIalsosupportsthiskindofpackagingofmultiplevirtualmachines.Whenyouinstantiatea VAppTemplate,informationfromitsVirtualSystemandVirtualSystemCollectionelementsis propagatedtothecreatedVApp.VirtualSystemelementsinaVirtualSystemCollectionbecomeVm elementscontainedbytheChildrenelementofaVApp. Formoreinformationaboutinstantiation,seeInstantiateavAppTemplateonpage 61.Foradetailed exampleofanEnvelopeanditssections,seeReconfiguringvAppsandVirtualMachinesonpage 69.For moreinformationaboutthepurposeandcontentsoftheOVFSectionsincludedinavApporVm,seeVApp onpage 162.
204
VMware, Inc.
Networks
TheNetworkSectionelementofanOVFEnvelopelistsallthelogicalnetworksrequiredbythepackage.Each networkisdefinedinthissectionbyanameandcanhaveanoptionaldescription.Logicalnetworknamesare usedwhenspecifyingconnectiondetailsforavirtualNIC. TheOVFisextensible,andthevCloudAPIhasimplementedextensionsthatenableamorecomprehensive specificationofnetworkfeatures,suchasfirewallandNATrules,thanwhatiscurrentlysupportedbytheOVF standard.SeeNetworkConfigonpage 165. Example A2illustratesasubsetofEnvelopeelementsthatspecifyvAppnetworkingconfiguration.
VMware, Inc.
205
206
VMware, Inc.
MakeanHTTPrequest(typicallyGET,PUT,POST,orDELETE).Thetargetofthisrequestiseithera wellknownURL(suchastherootofavCloudserviceoranorganizationhostedonsuchaservice)ora linkobtainedfromtheresponsetoapreviousrequest.(Forexample,aGETrequesttoanorganization URLreturnslinkstocatalogandvDCobjectscontainedbytheorganization.) Examinetheresponse,whichalwaysincludesanHTTPresponsecodeandoftenincludesabody(anXML document,inthevCloudAPI).Theresponsebodymaycontainlinksorotherinformationaboutthestate ofanobject.(Forexample,aresponsethatincludesavAppbodycontainsthedetailsofthevAppscurrent virtualhardwareconfigurations,aswellaslinksthatyoucanusetoeditthatconfiguration).Ifthe responseisanHTTPresponsecode,itindicateswhethertherequestsucceededorfailed,andmaybe accompaniedbyaURLthatpointstoalocationfromwhichadditionalinformationcanberetrieved.
Thesetwooperationscanrepeat,inthisorder,foraslongasnecessary.
208
VMware, Inc.
Index
A
AccessLevel element example of use 57 schema reference 178 AccessSetting element example of use 56, 57 schema reference 178 AccessSettings element example of use 56 schema reference 178 AdminVdc element example of use 104 AllEULAsAccepted description 172 AllEULAsAccepted element example of use 63, 65 authentication about 18 example request 21 AvailableNetworks element example of use 103, 104, 129 schema reference 153
schema reference 176 ComposeVAppParams element example of use 65 schema reference 173 Configuration element schema reference 155 ControlAccessParams element example of use 56 schema reference 177
D
DeployVAppParams example of use 26, 81 DeployVAppParams element schema reference 175
E
Error codes 146 Error element schema reference 146 examples about 19 ExternalNetwork element example of use 99 schema reference 180
C
CaptureVAppParams element example of use 68 schema reference 175 Catalog element example of use 35 schema reference 160 CatalogItem element example of use 36 schema reference 160 CatalogItems element schema reference 160 Catalogs about 14 controlling access to 56 CloneMediaParams element example of use 51 schema reference 176 CloneVAppParams element example of use 52 schema reference 176 CloneVAppTemplateParams element example of use 51
F
File element schema reference 154 Firewall rules to create or modify 72 FirewallRule element example of use 72 FirewallService element example of use 72 schema reference 156
G
Group element example of use 113 schema reference 191 GuestCustomizationSection element cannot be passed in InstantiationParams 80
H
Host element example of use 124
209
VMware, Inc.
schema reference 199 HTTP headers Content-Type 142 HTTP status codes 18
I
InstantiateVAppTemplateParams element example of use 25, 63 schema reference 172 Instantiation Parameters about 62 InstantiationParams element example of use 25, 63 schema reference 172 IpRange element example of use 72 schema reference 156
example of use 21 OrgNetwork element schema definition 154 OVF to create vApp template from 42 to download vApp template as 47 to upload 171
P
Property element example of use 36, 161 schema reference 161
R
rel attribute about 15 ResourceEntity element about 38 example of use 37, 55 schema reference 154 responses contents of 18 Role element example of use 114 schema reference 191
L
Link element about 15 rel attribute 15 login example of 21 logout example of 30
S M
Media element example of use 50 schema reference 161 MediaInsertOrEjectParams element example of use 85 schema reference 177 ScreenTicket element example of use 30, 87 Source element example of use 63, 65, 67
T
Task element example of use 89 schema reference 168 Tasks about 14 TasksList element example of use 97 technical support resources 12
N
NAT rules to create or modify 72 NatRule element example of use 72 schema reference 158 network vApp 62 NetworkConfigSection element example of use 71
U
UndeployVAppParams element schema reference 175 UploadVAppTemplateParams element example of use 43 schema reference 171 User element example of use 110 schema reference 190
O
Org element example of use 22 schema reference 151 Org entity to retrieve 34 OrgList element
210
VMware, Inc.
Index
V
vApp to compose from templates and virtual machines 65 to create from template 24, 61 to deploy and power-on 26 to instantiate 24 VApp element example of use 65, 66, 67, 69 schema reference 162 vApp networks about 62 vApp template add to catalog 54 to create from OVF 42 to create from vApp 68 VAppScopedVmId element example of use 72 VAppTemplate element example of use 61 schema reference 161 to create 42 vDC about 14 Vdc element example of use 24, 37 schema reference 152 VimServer example of use 120 schema reference 194 Vm element example of use 65, 66, 73 schema reference 163 searching for 66 VmQuestionAnswer schema reference 177 VMWExtension example of use 119 schema reference 193 VMWExternalNetwork example of use 133 schema reference 199 VMWNetworkPool example of use 136 schema reference 198 VMWProviderVdc example of use 127 schema reference 197
VMware, Inc.
211
212
VMware, Inc.