With the vCloud API composeVApp operation, you can build a vApp from existing virtual machines to which you have access.

Every VDC includes a link to a composeVApp operation, which creates a new vApp in it. The ComposeVappParams request body is a superset of InstantiateVAppTemplateParams, and composeVApp can generally be used wherever you would use instantiateVAppTemplate. To compose a vApp, POST a composeVApp request to this link. The request body is a ComposeVAppParams element, which includes the following information:

■

An InstantiationParams element that can include any of the section types listed under Instantiation Parameters for vApps. 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 must contain a Source element that specifies the href of a Vm, VApp, or VAppTemplate to include in the composition. If the Source element references a virtual machine, the SourcedItem can include any of the following elements:

■

An InstantiationParams element specific to that virtual machine. This element can include any of the section types listed under Instantiation Parameters for Virtual Machines. Changes to most Item elements in a VirtualHardwareSection are ignored by the composeVApp operation.

■

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

■

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

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

■

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

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

Prerequisites

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

Procedure
1

Find the composeVApp link in the target VDC.

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

<Link
   rel="add"
   type="application/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. See Example: Compose a vApp

3

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

See the Request portion of Example: Compose a vApp.

Example: Compose a vApp

A ComposeVAppParams request body includes a root-level InstantiationParams element that provides instantiation parameters for the composed vApp. The request body can include an arbitrary number of SourcedItem elements, each of which can specify a vApp template or a virtual machine. SourcedItem elements where the Source is a vApp template cannot contain InstantiationParams. If you want to modify any of the virtual machines during composition or recomposition, specify InstantiationParams for them in the containing Source element. 

<!- ComposeVAppParams/RecomposeVAppParams request body prototype -->
<ComposeVAppParams>
   <InstantiationParams>
      <!-- vApp-level params -->
   </InstantiationParams>
   <SourcedItem>
      <Source href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111">
         <!-- InstantiationParams not allowed if Source references a vApp template -->
         <!-- vApp-level InstantiationParams apply to the composed vApp -->
   </SourcedItem>
   <SourcedItem>
      <Source href="any Vm">
         <InstantiationParams>
            <!-- Vm-level params -->
         </InstantiationParams>
      </Source>
   </SourcedItem>
</ComposeVAppParams>

This request composes a vApp from two virtual machines. The two SourcedItem elements each define a virtual machine (in their Source element) and supply InstantiationParams that modify its NetworkConnectionSection to connect to the vApp network created for this vApp in the root level InstantiationParams element.

Note

If a virtual machine referenced in a Source element is powered on or has an independent disk attached, this operation will fail. You can use a query like this one to return a list of references to powered-off virtual machines that you have access to. 

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/vApp/vm-45"/>
      <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>
   <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>

Related concepts
Related tasks