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

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

An InstantiationParams element that can include any of the section types listed under Configuring a vApp. This is where you define the vApp network to which all the virtual machines in the composed vApp connect, and custom vApp lease settings and startup parameters for the virtual machines.

An optional Description of the composed vApp.

Zero or more SourcedItem elements, each of which defines a source of virtual machines to include in the composition. Each SourcedItem must contain a Source element that references a composition source, the href of a Vm, VApp, or VAppTemplate. If the Source element references a virtual machine, the SourcedItem can include any of the following elements:

An InstantiationParams element specific to that virtual machine. This element can include any of the section types listed under Configuring a Virtual Machine.

A NetworkAssignment element that specifies how the network connections in the virtual machine are mapped to vApp networks defined in the InstantiationParams element that applies to the composed vApp.

A VAppScopedLocalId element that provides a unique identifier for the virtual machine in the scope of the composed vApp.

If the Source element references a vApp or vApp template, all Vm elements from each composition source become peers in the Children collection of the composed vApp.

If any of the composition items is subject to a EULA, the ComposeVAppParams element must include an AllEULAsAccepted element that has a value of true, indicating that you accept the EULA. Otherwise, composition fails.

The composed vApp must be deployed and powered on before you can use it.

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

1

Find the composeVApp link in the target VDC.

The XML representation of the VDC contains a composeVapp link, which has the following form:

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

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

3

POST the ComposeVappParams element to the composeVapp link of the target VDC.

See the Request portion of Example: Compose a vApp.

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

Note

Virtual machines specified in Source elements must be powered off or this operation will fail. You can use a query like this one to return a list of references to powered-off virtual machines that you have access to.

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

See Using the Query Service.

Request:

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

The response is a sparsely populated VApp element in the target VDC. When the Task embedded in the response is complete, the vApp has been composed.

Response:

201 Created
Content-Type: application/vnd.vmware.vcloud.vApp+xml
...
<VApp
   name="Example Corp’s CRM Appliance" 
   type="application/vnd.vmware.vcloud.vApp+xml" 
   status="8" 
   href="https://vcloud.example.com/api/vApp/vapp-33" ...>
   <Link
      rel="up" type="application/vnd.vmware.vcloud.vdc+xml"
      href="https://vcloud.example.com/api/vdc/5"/>
   ...
   <Description>Composed CRM Appliance</Description>
   ...
   <Tasks>
      <Task operation="Composing Virtual Application Example Corp’s CRM Appliance (33)" ...>
         ...
      </Task>
   </Tasks>
</VApp>