An instantiateVAppTemplate request creates a vApp from a vApp template. By default, this operation also deploys the vApp and powers it on.

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 sections:

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.

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.

Verify that you are logged in to the vCloud API as a system administrator or member of an organization in the cloud.

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.

2

Examine the template to determine the set of instantiation parameters that the request must include.

3

Create an InstantiateVAppTemplateParams element.

See Example: Instantiate a vApp Template for guidelines.

4

Make a POST request to the action/instantiateVAppTemplate URL of the vDC.

Supply the InstantiateVAppTemplateParams element as the request body.

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 it is still being constructed. It also contains a Task element that tracks the progress of the request.

This InstantiateVAppTemplateParams request extends the request shown in Example: 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.

For more information and a list of sections that you can include in InstantiationParams, see Configuring a vApp.

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>2010-04-11T08:08:16.438-07:00</StorageLeaseExpiration>
      </LeaseSettingsSection>
   </InstantiationParams>
   <Source
      href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" />
   <AllEULAsAccepted>true</AllEULAsAccepted>
</InstantiateVAppTemplateParams>

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