The vCloud API supports recomposition of a vApp to add or remove virtual machines. To recompose a vApp, make a recomposeVApp request, supplying a RecomposeVAppParams element as the request body.

The RecomposeVAppParams element allows an arbitrary number of DeleteItem and CreateItem elements, but is otherwise identical to ComposeVAppParams. This means that in addition to adding or removing virtual machines, a recomposeVApp request can also change the name and description of the vApp, and can supply new InstantiationParams to change various sections of the composed vApp or any of the added virtual machines.

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

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 recomposeVApp link in the target vApp.

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

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

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

See Example: Recompose a vApp.

3

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

This example uses the recomposeVApp operation to modify this vApp, which contains three virtual machines. Only a few of the elements in the vApp appear here.

<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"/>
   ...
   <Children>
      <Vm
         status="8"
         name="CRM-DB"
         href="https://vcloud.example.com/api/vApp/vm-7" ...>
         ...
      </Vm>
      <Vm
         status="8"
         name="CRM-CRM"
         href="https://vcloud.example.com/api/vApp/vm-44" ...>
         ...
      </Vm>
      <Vm
         status="8"
         name="CRM-HTTP"
         href="https://vcloud.example.com/api/vApp/vm-45" ...>
         ...
      </Vm>
   </Children>
...
</VApp>

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

Request:

POST https://vcloud.example.com/api/vApp/vapp-33/action/recomposeVApp
Content-Type: application/vnd.vmware.vcloud.recomposeVAppParams+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<RecomposeVAppParams
   name="Example Corp’s CRM Appliance"
   xmlns="http://www.vmware.com/vcloud/v1.5"
   xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1">
   <Description>Composed CRM Appliance</Description>
   <InstantiationParams>
      <NetworkConfigSection>
         <ovf:Info>Configuration parameters for logical networks</ovf:Info>
         <NetworkConfig
            networkName="CRMApplianceNetwork">
            <Configuration>
               <ParentNetwork
                  href="https://vcloud.example.com/api/network/54" />
               <FenceMode>natRouted</FenceMode>
            </Configuration>
         </NetworkConfig>
      </NetworkConfigSection>
      <ovf:StartupSection
         xmlns:vcloud="http://www.vmware.com/vcloud/v1.5"
         vcloud:type="application/vnd.vmware.vcloud.startupSection+xml">
         <ovf:Info>VApp startup section</ovf:Info>
         <ovf:Item
            ovf:order="0"
            ovf:id="CRM-DB" />
         <ovf:Item
            ovf:order="1"
            ovf:id="CRM-CRM" />
      </ovf:StartupSection>
   </InstantiationParams>
   <AllEULAsAccepted>true</AllEULAsAccepted>
   <DeleteItem
      href="https://vcloud.example.com/api/vApp/vm-45" />
</RecomposeVAppParams>

Response:

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

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.