Unsupported content This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

Compose vApp operation

The Compose vApp operation enables you to compose or create a vApp using the following entities:

  • A vApp template
  • An existing vApp
  • An existing VM

The following figure shows a sample <items> XML element for the Compose vApp operation:

Sample <items> XML element for the Compose vApp operation

<items>
 <item>
   <parameters>
     <vdc-id></vdc-id>
     <vapp-name></vapp-name>
     <deploy></deploy>
     <power-on></power-on>
     <description></description>
     <instantiation-params>
       <network-config-section>
         <info></info>
         <network-config>
           <network-name></network-name>
           <description></description>
           <configuration>
             <parent-network-id></parent-network-id>
             <fence-mode></fence-mode>
             <ip-scope>
               <is-inherited></is-inherited>
               <gateway></gateway>
               <netmask></netmask>
               <dns1></dns1>
               <dns2></dns2>
               <dns-suffix></dns-suffix>
               <ip-ranges>
                 <ip-range>
                   <start-address></start-address>
                   <end-address></end-address>
                 </ip-range>
               </ip-ranges>
             </ip-scope>
           </configuration>
         </network-config>
       </network-config-section>
       <startup-section>
         <info/>
         <vm-startup-details>
           <vm-name></vm-name>
           <order></order>
           <start-action></start-action>
           <start-delay></start-delay>
           <stop-action></stop-action>
           <stop-delay></stop-delay>
         </vm-startup-details>
       </startup-section>
       <lease-setting-section>
         <info/>
         <deployment-lease-in-seconds></deployment-lease-in-seconds>
         <storage-lease-in-seconds></storage-lease-in-seconds>
       </lease-setting-section>
     </instantiation-params>
     <compose-vapp-params>
       <compose-vapp-param>
         <vapp-id></vapp-id>
         <network-assignment>
           <inner-network></inner-network>
           <container-network></container-network>
         </network-assignment>
       </compose-vapp-param>
       <compose-vapp-param>
         <vapp-template-id></vapp-id>
         <network-assignment>
           <inner-network></inner-network>
           <container-network></container-network>
         </network-assignment>
       </compose-vapp-param>
       <compose-vapp-param>
         <vm-id></vm-id>
         <name></name>
         <network-connection-section>
           <info></info>
           <primary-network-connection-index></primary-network-connection-ind
           <network-connection>
             <network></network>
             <network-connection-index></network-connection-index>
             <is-connected></is-connected>
             <ip-address></ip-address>
             <mac-address></mac-address>
             <ip-address-allocation-mode></ip-address-allocation-mode>
           </network-connection>
         </network-connection-section>
         <network-assignment>
           <inner-network></inner-network>
           <container-network></container-network>
         </network-assignment>
       </compose-vapp-param>
     </compose-vapp-params>
     <all-eulas-accepted></all-eulas-accepted>
   </parameters>
 </item>
</items>

The following table describes the elements for this adapter request:

Adapter request elements for the Compose vApp operation

Element

Definition

Required

<operation-name>

Defines the type of operation: Compose_vApp

Yes

<vcloud-organization>

Specifies the name of the vCloud organization

Conditional:

  • Required if not specified in the configuration
  • If used, requires <user-name> and <password>
<user-name>

Specifies the user name required for basic HTTP authentication on vCloud

Conditional:

  • Required if not specified in the configuration
  • If used, requires <vcloud-organization> and <password>
<password>

Contains the password corresponding to the specified user name

Conditional:

  • Required if not specified in the configuration
  • If used, requires <vcloud-organization> and <user-name>
<parameters>

Contains the elements for the operation

Yes

<vdc-id>

Specifies the ID of the target virtual data center

Valid value: Any string

Yes

<vapp-name>

Specifies the name for the vApp that you want to compose

Valid value: Any string

Yes

<deploy>

Specifies whether the vApp must be deployed after being composed

Valid values: true, false (default)

No

<power-on>

Specifies whether the vApp must be powered on after being composed

Valid values: true, false (default)

No

<description>

Specifies the description for the vApp that you want to compose

No

<network-config-section>

Contains the following elements:

  • <info>
  • <network-config>

No

<info>

Specifies information about the <network-config-section> element

No

<network-config>

Defines the configuration of the vApp network

You can repeat the <network-config> element, which includes the following elements for multiple networks:

  • <network-name>
  • <description>
  • <configuration>

No

<network-name>

Specifies the name of the vApp's parent network

Valid value: Any string

Conditional; required if <network-config> is specified

<description>

Specifies the description of the network

No

<configuration>

Specifies the properties of the network, including the following elements:

  • <parent-network-id>
  • <fence-mode>
  • <ip-scope>
  • <is-inherited>
  • <gateway>
  • <netmask>
  • <dns1>
  • <dns2>
  • <dns-suffix>
  • <ip-ranges>
  • <ip-range>
  • <start-address>
  • <end-address>

Conditional; required if <network-config> is specified

<parent-network-id>

Specifies a reference to a network to which this network can be connected

No

<fence-mode>

Specifies how this network is connected to its parent network

Note

With version 1.5 of the vCloud Director, when you create a vApp network specifying the <fence-mode> as bridged, the vApp network's name specified in the <network-name> element must match the name of the parent network from which this vApp is cloned. This is because the Instantiate vApp Template operation automatically corrects a mismatch in the name by changing the value of the <network> element in the <network-connection> element.

Valid values: bridged, isolated, natRouted

Conditional; required if <network-config> is specified

<ip-scope>

Defines the address range, gateway, netmask, DNS, and other properties of the network

Conditional; required when creating a NAT-routed or isolated network

<is-inherited>

Specifies whether the values in the <ip-scope> element are inherited from the parent network

Valid values: true, false

Conditional; required when creating a NAT-routed or isolated network

<gateway>

Specifies the IP address of the network gateway

Conditional; required when creating a NAT-routed or isolated network

<netmask>

Specifies the network mask that you must apply to addresses on the new network

Valid value: IP address

Conditional; required when creating a NAT-routed or isolated network

<dns1>

Specifies the IP address of the primary DNS server for the new network

Conditional; required when creating a NAT-routed or isolated network

<dns2>

Specifies the IP address of the secondary DNS server for the new network

No

<dns-suffix>

Specifies the suffix that you must use when resolving host names that are not fully qualified

No

<ip-ranges>

Contains the <ip-range> element

No

<ip-range>

Defines the address range of the network

No

<start-address>

Specifies the start IP address for the specified IP range

Conditional; required if <ip-range> is specified

<end-address>

Specifies the end IP address for the specified IP range

No

<startup-section>

Contains the <info> and <vm-startup-details> elements

No

<info>

Specifies descriptive information about the <startup-section> element

No

<vm-startup-details>

Specifies startup information for the VM, including the following elements:

  • <vm-name>
  • <order>
  • <start-action>
  • <start-delay>
  • <stop-action>
  • <stop-delay>

No

<vm-name>

Specifies the name of the VM

No

<order>

Specifies the order in which the VMs in the composed vApp start and stop

Valid value: Any integer

No

<start-action>

Specifies the start-up action for the VM

Valid values: none, powerOn

No

<start-delay>

Specifies the delay in seconds after which the VM performs the action specified in the <start-action> element

No

<stop-action>

Specifies the manner in which the VM stops

Valid values: powerOff, guestShutdown

No

<stop-delay>

Specifies the delay in seconds after which the VM performs the action specified in the <stop-action> element

No

<lease-setting-section>

Contains the following elements:

  • <info>
  • <deployment-lease-in-seconds>
  • <storage-lease-in-seconds>

No

<info>

Specifies descriptive information about the <lease-setting-section> element

No

<deployment-lease-in-seconds>

Specifies the duration of the deployment lease in seconds

No

<storage-lease-in-seconds>

Specifies the duration of the storage lease in seconds

No

<compose-vapp-param>

Contains the following elements:

  • <vapp-id>
  • <vapp-template-id>
  • <vm-id>

No

<vapp-id>

Specifies the ID of the vApp to use to compose the vApp

Valid value: Any string

Conditional:

  • Required if <compose-vapp-param> is specified
  • Required if <vapp-template-id> and <vm-id> are absent
<vapp-template-id>

Specifies the ID of the vApp template to use to compose the vApp

Valid value: Any string

Conditional:

  • Required if <compose-vapp-param> is specified
  • Required if <vapp-id> and <vm-id> are absent
<vm-id>

Specifies the ID of the VM to use to compose the vApp

Valid value: Any string

Conditional:

  • Required if <compose-vapp-param> is specified
  • Required if <vapp-template-id> and <vapp-id> are absent
<name>

Specifies a new name for the VM

This element is used only if the <vm-id> element is specified.

Valid value: Any string

No

<network-connection-section>

Contains the following elements:

  • <info>
  • <primary-network-connection-index>
  • <network-connection>
    This element is used only if the <vm-id> element is specified.

No

<info>

Specifies information about the <network-connection-section> element

No

<primary-network-connection-index>

Specifies the value of the <rasd:AddressOnParent> element, which specifies the index of the Network Interface card (NIC) supporting the primary network connection on the VM

The <rasd:AddressOnParent> element is returned when you retrieve information about a VM.

No

<network-connection>

Describes a single network connection

You can repeat the <network-connection> element for multiple networks, which includes the following elements:

  • <network>
  • <network-connection-index>
  • <is-connected>
  • <ip-address>
  • <external-ip-address>
  • <mac-address>
  • <ip-address-allocation-mode>

No

<network>

Specifies the name of the network to which this connection connects

Conditional; required if <network-connection> is specified

<network-connection-index>

Specifies the value of the <rasd:AddressOnParent> element, which specifies the index of the Network Interface card (NIC) supporting the connection

Conditional; required if <network-connection> is specified

<is-connected>

Specifies the connection state of the vApp

If the vApp is deployed, this element specifies the current state of its connection. If the vApp is undeployed, this element specifies whether this connection should be connected at deployment time.

Valid values: true, false

Conditional; required if <network-connection> is specified

<ip-address>

Specifies the IP address of the connection

No

<external-ip-address>

Contains the external address if the network to which the NIC is connected has network address translation (NAT) or port mapping

Valid value: IP address

No

<mac-address>

Specifies the MAC address of the connection

No

<ip-address-allocation-mode>

Specifies how an IP address is allocated to the connection

Valid values: NONE, MANUAL, POOL, DHCP

Conditional; required if <network-connection> is specified

<network-assignment>

Maps logical networks in the source to logical networks in the composed vApp

This element contains the <inner-network> and <container-network> elements.

No

<inner-network>

Specifies the name of the network in the source

Valid value: Any string

Conditional; required if <network-assignment> is specified

<container-network>

Specifies the name of the vApp network to which the value specified in the <inner-network> element is mapped

Valid value: Any string

Conditional; required if <network-assignment> is specified

<all-eulas-accepted>

Specifies whether to accept the terms and conditions in the template's EULA section

Valid values : true, false

No

The following figure shows the sample adapter request for the Compose vApp operation when the <fence-mode> element is set to isolated:

Sample adapter request for the Compose vApp operation (fence-mode = isolated)

<vmware-vcloud-request>
 <operation-name>Compose_vApp</operation-name>
 <vcloud-organization>TestOrg</vcloud-organization>
 <user-name>TestUser</user-name>
 <password>Password</password>
 <parameters>
   <vdc-id>1481190991</vdc-id>
   <vapp-name>TestTmpl108</vapp-name>
   <deploy>true</deploy>
   <power-on>true</power-on>
   <description>This is compose Vapp functionality</description>
   <instantiation-params>
     <network-config-section>
       <network-config>
         <network-name>qwe</network-name>
         <configuration>
           <fence-mode>isolated</fence-mode>
           <ip-scope>
             <is-inherited>false</is-inherited>
             <netmask>255.255.0.0</netmask>
             <gateway>10.128.128.1</gateway>
             <dns1>10.10.1.1</dns1>
           </ip-scope>
         </configuration>
         <ip-ranges>
           <ip-range>
             <start-address>10.128.128.2</start-address>
             <end-address>10.128.128.10</end-address>
           </ip-range>
         </ip-ranges>
       </network-config>
     </network-config-section>
   </instantiation-params>
   <compose-vapp-params>
     <compose-vapp-param>
       <vm-id>vm-849472990</vm-id>
       <name>testuser</name>
       <network-connection-section>
         <network-connection>
           <network>qwe</network>
           <network-connection-index>1</network-connection-index>
           <is-connected>true</is-connected>
           <ip-address>10.128.128.4</ip-address>
           <mac-address>01:01:01:01:01:01</mac-address>
           <ip-address-allocation-mode>MANUAL</ip-address-allocation-mode>
         </network-connection>
       </network-connection-section>
     </compose-vapp-param>
   </compose-vapp-params>
   <all-eulas-accepted>true</all-eulas-accepted>
 </parameters>
</vmware-vcloud-request>

The following figure shows the response for the sample request when the <fence-mode> element is set to isolated:

Sample adapter response for the Compose vApp operation (fence-mode = isolated)

<vmware-vcloud-response>
   <metadata>
       <status>success</status>
   </metadata>
   <status-line>
       <code>201</code>
       <reason>Created</reason>
   </status-line>
   <message-body>
       <VApp
           deployed = "false"
           status = "0"
           name = "TestTmpl108"
           type = "application/vnd.vmware.vcloud.vApp+xml"
           href = "https://10.128.248.112/api/v1.0/vApp/vapp-1234561431">
           <Link
               rel = "up"
               type = "application/vnd.vmware.vcloud.vdc+xml"
               href = "https://10.128.248.112/api/v1.0/vdc/1481190991"/>
           <Description>This is compose Vapp functionality</Description>
           <Tasks>
               <Task
                   status = "running"
                   startTime = "2011-03-01T15:09:40.364+05:30"
                   operation = "Composing Virtual Application
TestTmpl118(1234561431)"
                   expiryTime = "2011-05-30T15:09:40.364+05:30"
                   endTime = "9999-12-31T23:59:59.999+05:30"
                   type = "application/vnd.vmware.vcloud.task+xml"
                   href = "https://10.128.248.112/api/v1.0/task/vcqtlf2
eh41xs5xxho">
                   <Owner
                       type = "application/vnd.vmware.vcloud.vApp+xml"
                       name = "TestTmpl108"
                       href = "https://10.128.248.112/api/v1.0/vApp/vapp-1234
561431"/>
               </Task>
           </Tasks>
       </VApp>
   </message-body>
</vmware-vcloud-response>

The following figure shows the sample adapter request for the Compose vApp operation with <vm-startup-details> and <lease-setting-section> elements:

Sample adapter request for the Compose vApp operation with <vm-startup-details> and <lease-setting-section>

<vmware-vcloud-request>
 <operation-name>Compose_vApp</operation-name>
 <vcloud-organization>TestOrg</vcloud-organization>
 <user-name>TestUser</user-name>
 <password>Password</password>
 <parameters>
   <vdc-id>1481190991</vdc-id>
   <vapp-name>TestTmpl108</vapp-name>
   <deploy>true</deploy>
   <power-on>true</power-on>
   <description>This is compose Vapp functionality</description>
   <instantiation-params>
     <network-config-section>
       <network-config>
         <network-name>abcd</network-name>
         <configuration>
           <fence-mode>bridged</fence-mode>
           <parent-network-id>539454687</parent-network-id>
         </configuration>
       </network-config>
     </network-config-section>
     <startup-section>
       <info/>
       <vm-startup-details>
         <vm-name>testlaysha134567</vm-name>
         <order>0</order>
         <start-action>powerOn</start-action>
         <start-delay>60</start-delay>
         <stop-action>powerOff</stop-action>
         <stop-delay>60</stop-delay>
       </vm-startup-details>
       <vm-startup-details>
         <vm-name>testlaysha1345678</vm-name>
         <order>1</order>
         <start-action>powerOn</start-action>
         <start-delay>60</start-delay>
         <stop-action>powerOff</stop-action>
         <stop-delay>60</stop-delay>
       </vm-startup-details>
     </startup-section>
       <lease-setting-section>
         <info/>
         <deployment-lease-in-seconds>60000</deployment-lease-in-seconds>
         <storage-lease-in-seconds>60000</storage-lease-in-seconds>
       </lease-setting-section>
     </instantiation-params>
     <compose-vapp-params>
       <compose-vapp-param>
         <vm-id>vm-1662797449</vm-id>
         <name>testuser</name>
         <network-connection-section>
           <network-connection>
             <network>abcd</network>
             <network-connection-index>1</network-connection-index>
             <is-connected>true</is-connected>
             <ip-address-allocation-mode>DHCP</ip-address-allocation-mode>
           </network-connection>
         </network-connection-section>
       </compose-vapp-param>
       <compose-vapp-param>
         <vm-id>vm-1662797449</vm-id>
         <name>testuser</name>
         <network-connection-section>
           <network-connection>
             <network>abcd</network>
             <network-connection-index>1</network-connection-index>
             <is-connected>true</is-connected>
             <ip-address-allocation-mode>DHCP</ip-address-allocation-mode>
           </network-connection>
       </network-connection-section>
     </compose-vapp-param>
   </compose-vapp-params>
   <all-eulas-accepted>true</all-eulas-accepted>
 </parameters>
</vmware-vcloud-request>

The following figure shows the response for the sample request with <vm-startup-details> and <lease-setting-section> elements:

Sample adapter response for the Compose vApp operation with <vm-startup-details> and <lease-setting-section>

<vmware-vcloud-response>
   <metadata>
       <status>success</status>
   </metadata>
   <status-line>
       <code>201</code>
       <reason>Created</reason>
   </status-line>
   <message-body>
       <VApp
           deployed = "false"
           status = "0"
           name = "TestTmpl111"
           type = "application/vnd.vmware.vcloud.vApp+xml"
           href = "https://10.128.248.112/api/v1.0/vApp/vapp-1234561431">
           <Link
               rel = "up"
               type = "application/vnd.vmware.vcloud.vdc+xml"
               href = "https://10.128.248.112/api/v1.0/vdc/1481190991"/>
           <Description>This is compose Vapp functionality</Description>
           <Tasks>
               <Task
                   status = "running"
                   startTime = "2011-03-01T15:09:40.364+05:30"
                   operation = "Composing Virtual Application
TestTmpl118(1234561431)"
                   expiryTime = "2011-05-30T15:09:40.364+05:30"
                   endTime = "9999-12-31T23:59:59.999+05:30"
                   type = "application/vnd.vmware.vcloud.task+xml"
                   href = "https://10.128.248.112/api/v1.0/task/vcqtlf2eh41x
s5xxho">
                   <Owner
                       type = "application/vnd.vmware.vcloud.vApp+xml"
                       name = "TestTmpl111"
                       href = "https://10.128.248.112/api/v1.0/vApp/vapp-1234
561431"/>
               </Task>
           </Tasks>
       </VApp>
   </message-body>
</vmware-vcloud-response>

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*