Recompose a vApp to Add, Remove, or Reconfigure Virtual Machines

The VMware Cloud Director API supports recomposition of a vApp to add, remove, and reconfigure its 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 ReconfigureItem elements, but is otherwise identical to ComposeVAppParams.

Unlike a composeVapp request, which operates on a VDC and creates a new vApp, a recomposeVapp request operates on (and modifies) an existing 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/vApp/vapp-33/action/recomposeVApp" />

To recompose a vApp, POST a recomposeVApp request to this link. The request body is a RecomposeVAppParams element, which can include all the information allowed in a ComposeVAppParams, as well as the following additional elements:

ReconfigureItem elements that reconfigure virtual machines in the vApp. By including ReconfigureItem elements, you can enable a recomposeVApp request to make the same kinds of virtual machine configuration changes you can make with a reconfigureVm request. See Update Multiple Sections of a Virtual Machine
DeleteItem elements remove virtual machines from the vApp

Prerequisites

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

Procedure

Find the recomposeVApp link in the target vApp.
Create a RecomposeVappParams element that specifies the details of the recomposition.
See Recompose a vApp.
POST the RecomposeVappParams element to the recomposeVapp link of the target vApp.

Example: Recompose a vApp

A RecomposeVAppParams request body prototype is similar to the ComposeVAppParams prototype shown in Compose a vApp. Instantiation parameters for the recomposed vApp appear as a root level InstantiationParams element. Instantiation parameters for added virtual machines appear as InstantiationParams in SourcedItem elements whose Source element references a virtual machine.

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="recompose"
      type="application/vnd.vmware.vcloud.recomposeVAppParams+xml"
      href="https://vcloud.example.com/api/vApp/vapp-33/action/recomposeVApp" />
   ...
   <Children>
      <Vm
         status="8"
         name="CRM-DB-ORCL"
         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>

Imagine that you want to replace the database server for this vApp with a new one hosted by a virtual machine that has the following properties:

<Vm
   status="8"
   name="CRM-DB-POSTGRES"
   href="https://vcloud.example.com/api/vApp/vm-90" ...>
   ...
</Vm>

To do that, create a request like this one, which removes the old database server (DeleteItem), adds the new one (SourcedItem, including InstantiationParams that connect it to the vApp network), and modifies the StartupSection to specify an appropriate start order for the recomposed vApp.

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-POSTGRES"/>
         <ovf:Item
            ovf:order="1"
            ovf:id="CRM-CRM"/>
      </ovf:StartupSection>
   </InstantiationParams>
   <SourcedItem>
      <Source href="https://vcloud.example.com/api/vApp/vm-90"/>
      <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>
   <DeleteItem href="https://vcloud.example.com/api/vApp/vm-8"/>
</RecomposeVAppParams>

If the virtual machine referenced in SourceItem element in this example was already included in the vApp but needed to be reconfigured to adapt to the new vApp network configuration, you could use a ReconfigureItem element in place of the SourcedItem element.

<?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>
      ...
   </InstantiationParams>
   <AllEULAsAccepted>true</AllEULAsAccepted>
   <DeleteItem href="https://vcloud.example.com/api/vApp/vm-8"/>
   <ReconfigureItem
      name="vm-90"
      href="https://vcloud.example.com/api/vApp/vm-90">
      <ovf:Section
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:type="NetworkConnectionSectionType">
         <ovf:Info>My Network Connection Section Info</ovf:Info>
         <PrimaryNetworkConnectionIndex>0</PrimaryNetworkConnectionIndex>
         <NetworkConnection network="CRMApplianceNetwork">
            <NetworkConnectionIndex>0</NetworkConnectionIndex>
            <IsConnected>true</IsConnected>
            <IpAddressAllocationMode>DHCP</IpAddressAllocationMode>
         </NetworkConnection>
      </ovf:Section>
   </ReconfigureItem>
</RecomposeVAppParams>

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.

Response:

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