An instantiateVAppTemplate request creates a vApp from a vApp template.

To create a vApp from a vApp template, you must bind the template's abstract resource requirements, such as network connections, storage resources, memory, and CPU capacity, to appropriate resources in the target VDC. This binding operation is called instantiation.

For an example of a simple instantiation request, see Deploy the vApp. You can also specify additional parameters as part of instantiation.

Template contents that might influence composition of the request body include the following elements in the vApp itself:
  • A NetworkConfigSection that defines a vApp network to which virtual machines in this vApp can connect.
  • One or more EulaSection elements that specify licensing terms or other conditions that you must accept before creating the vApp. The InstantiateVAppTemplateParams element can include an AllEULAsAccepted element whose value indicates whether you accept all EULA terms included in the template. If a vApp template includes any ovf:EulaSection elements, AllEULAsAccepted must be set to a value of true. Otherwise, instantiation fails.
  • A LeaseSettingsSection. If this section is present and specifies settings that are appropriate for the vApp, you do not need to modify it. If it is absent or empty, the vApp is created with your organization’s default lease settings. If you specify new lease settings in a LeaseSettingsSection that you provide as part of instantiation, those settings replace any existing settings and override your organization's defaults.
Template contents that might influence composition of the request body include the following elements in the virtual machines that the template contains.
  • A NetworkConnectionSection that specifies network connection details for a virtual machine. Unless you want to create a vApp in which none of the virtual machines are connected to a network, your instantiation parameters must include at least one NetworkConfigSection that defines a vApp network, and that section must include a NetworkConfig element whose networkName attribute value matches the value of the network attribute of the NetworkConnection of each Vm in the template. If this attribute has the value none or is missing, the Vm can connect to any network. If the template contains Vm elements that specify different names for their network connections, you must create a vApp network for each.

Prerequisites

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

  • Review the current configuration of the vApp and its virtual machines. Configuration parameters in the VAppTemplate such as its NetworkConfigSection and LeaseSettingsSection affect all virtual machines in the vApp. Configuration parameters for individual virtual machines are defined in Vm elements in the VAppTemplate. A virtual machine's network connections are defined in its NetworkConnectionSection, and its hardware configuration is defined in its VirtualHardwareSection. To view the configuration of a virtual machine in a vApp template, you can retrieve the template and examine the VirtualHardwareSection of that Vm, or you can download the OVF descriptor of the vApp template, as shown in Download an OVF Descriptor or OVA File.

Procedure

  1. Retrieve the XML representation of the vApp template.
    Make a GET request to the URL provided in the href attribute of the Entity contained by the CatalogItem that references the template. You can also use the query service to return a list of references to vApp templates that you can access.
  2. Examine the template to determine the set of instantiation parameters that the request must include.
  3. Create an InstantiateVAppTemplateParams element.
    See Instantiate a vApp Template and Modify Virtual Machine Name, Description, and Storage Profile for guidelines.
  4. Make a POST request to the action/instantiateVAppTemplate URL of the VDC.
    Supply the InstantiateVAppTemplateParams element as the request body.

Results

The server takes the requested action and returns a VApp element. The element has a status attribute value of 0, meaning it is unresolved because the vApp is still being constructed. It also contains a Task element that tracks the progress of the request.

Example: Instantiate a vApp Template and Modify Virtual Machine Name, Description, and Storage Profile

An InstantiateVAppTemplateParams request body includes a root-level InstantiationParams element that provides instantiation parameters for the vApp. To modify properties of any virtual machine in the template during instantiation, include a SourcedItem element that references the virtual machine and provides InstantiationParams for it. Virtual machines referenced from SourcedItem elements in an InstantiateVAppTemplateParams must be members of the Children collection of the vApp template being instantiated. 
<!-- InstantiateVAppTemplateParams request body prototype -->
<InstantiateVAppTemplateParams>
   <InstantiationParams>
      <!-- vapp-level params -->
   </InstantiationParams>
   <Source href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111"/>
   <SourcedItem>
      <Source href="A Vm in template-111">
         <InstantiationParams>
            <!-- Vm-level params -->
         </InstantiationParams>
      </Source>
   </SourcedItem>
</InstantiateVAppTemplateParams>

This InstantiateVAppTemplateParams request extends the request shown in Deploying a vApp to include additional elements in its InstantiationParams:

  • A LeaseSettingsSection that specifies custom lease settings, overriding the settings that would otherwise be inherited from the organization.
  • An acknowledgement of EulaSection acceptance, supplied in the AllEULAsAccepted element. If the template does not include EulaSection elements, you can omit this acknowledgement.
  • A SourcedItem element whose Source element references a virtual machine in the template. In this example, the SourcedItem contains:
    • a VmGeneralParams element that specifies a new name and Description for a virtual machine in the template. If you omit this element, instantiation creates the virtual machine with the name and Description specified in the template.
    • a StorageProfile element that specifies a storage profile to be used for this virtual machine. If you omit this element, the virtual machine uses the default storage profile defined by the containing VDC.
Request: 
POST https://vcloud.example.com/api/vdc/5/action/instantiateVAppTemplate
Content-Type: application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<InstantiateVAppTemplateParams
   xmlns="http://www.vmware.com/vcloud/v1.5"
   name="Linux FTP server"
   deploy="true"
   powerOn="true"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1">
   <Description>Example FTP Server</Description>
   <InstantiationParams>
      <NetworkConfigSection>
         <ovf:Info>Configuration parameters for logical networks</ovf:Info>
         <NetworkConfig networkName="vAppNetwork">
            <Configuration>
               <ParentNetwork href="https://vcloud.example.com/api/network/54"/>
               <FenceMode>bridged</FenceMode>
            </Configuration>
         </NetworkConfig>
      </NetworkConfigSection>
      <LeaseSettingsSection
         type="application/vnd.vmware.vcloud.leaseSettingsSection+xml">
         <ovf:Info>Lease Settings</ovf:Info>
         <StorageLeaseInSeconds>172800</StorageLeaseInSeconds>
         <StorageLeaseExpiration>2014-04-25T08:08:16.438-07:00</StorageLeaseExpiration>
      </LeaseSettingsSection>
   </InstantiationParams>
   <Source href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111"/>
   <SourcedItem>
      <Source href="https://vcloud.example.com/api/vAppTemplate/vm-4"/>
      <VmGeneralParams>
         <Name>ftp1</Name>
         <Description>Primary FTP Server Instance</Description>
         <NeedsCustomization>true</NeedsCustomization>
      </VmGeneralParams>
      <StorageProfile href="https://vcloud.example.com/api/vdcStorageProfile/33">
      </StorageProfile>
   </SourcedItem>
   <AllEULAsAccepted>true</AllEULAsAccepted>
</InstantiateVAppTemplateParams>

The response is a sparsely populated VApp element, as shown in the response portion of Deploying a vApp.