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.

To deploy the vApp, you construct an InstantiateVAppTemplateParams element that specifies a vApp template to use and a network to connect to, then POST the element to the action/instantiateVAppTemplate URL of the VDC.

Prerequisites

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

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 find the Vm elements of the virtual machines that it contains.

Look for a NetworkConnection element in the Vm. You need some of the information in that element to create a vApp network that the virtual machine can connect to.

3

Create an InstantiateVAppTemplateParams element.

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

See the response portion of Example: Deploying a vApp.

Example: Deploying a vApp

This simple instantiateVAppTemplate request assumes that the vApp template includes one Vm and has no special requirements other than connecting that Vm to a network. For a look at a more complex instantiation request, see Example: Instantiate a vApp Template and Modify Virtual Machine Name, Description, and Storage Profile. The InstantiateVAppTemplateParams includes the following information:

■

A name for the vApp, supplied in the name attribute of the InstantiateVAppTemplateParams element. This request also provides a description, which is optional but a good practice.

■

A reference to a template, obtained from the href attribute of the Entity contained by the CatalogItem that you retrieved in Retrieve a Catalog Item and suppled in the Source element of the InstantiateVAppTemplateParams.

■

Configuration parameters for a vApp network, supplied in the NetworkConfigSection element. This specification includes the following parameters:

■

A name for the network, supplied in the name attribute of the NetworkConfigSection element. The name you specify for the vApp network must match the value of the network attribute of the NetworkConnection of the Vm. This example assumes that this NetworkConnection element includes the following values, which specify that the Vm connects to a network named vAppNetwork: 

<NetworkConnectionSection
   ...
    <NetworkConnection
      network="vAppNetwork">
      ... 
   </NetworkConnection>
</NetworkConnectionSection>
■

A reference to the organization VDC network to which the vApp network connects, specified in the ParentNetwork element. The URL used in this reference is one shown in the AvailableNetworks element in Example: Deployment Information in a VDC.

■

A fence mode, specified in the FenceMode element. A value of bridged indicates that the vApp network is connected directly to the organization VDC network.

For more information about creating networks with the vCloud API, see About vCloud Director Networks.

The target of the request is the instantiateVAppTemplate URL of this VDC. See Example: Deployment Information in a VDC. Because the operation creates a new vApp object, the HTTP request type is POST.

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>
   </InstantiationParams>
   <Source
      href="https://vcloud.example.com/api/vAppTemplate/vappTemplate-111" />
</InstantiateVAppTemplateParams>

The response to the instantiation request is a sparsely populated vApp element that includes the following information:

■

The status of the vApp. The status value 0 indicates that the vApp is unresolved, because instantiation is not complete.

■

The name of the vApp, as supplied in the request.

■

The vApp URL, shown in the href attribute of the VApp element. You can use this reference to retrieve information about the vApp.

■

A task created to track the instantiation. The Task element has an operation attribute that describes what is happening, and contains an Owner element that is a reference the vApp being created. The vApp is the owner of the task.

Response: 

201 Created
Content-Type: application/vnd.vmware.vcloud.vApp+xml
...
<VApp
   xmlns="http://www.vmware.com/vcloud/v1.5"
   xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"
   deployed="false"
   status="0"
   name="Linux FTP server"
   type="application/vnd.vmware.vcloud.vApp+xml"
   href="https://vcloud.example.com/api/vApp/vapp-7">
   <Link
      rel="up"
      type="application/vnd.vmware.vcloud.vdc+xml"
      href="https://vcloud.example.com/api/vdc/5"/>
   <Description>Example FTP Server vApp</Description>
   <Tasks>
      <Task
         status="running"
         operation="Creating Virtual Application Linux FTP server(7)"
         ... >
         <Owner
            type="application/vnd.vmware.vcloud.vApp+xml"
            name="LinuxFtpServer"
            href="https://vcloud.example.com/vApp/vapp-7" />
      </Task>
   </Tasks>
</VApp>

Previous topic: Retrieve Deployment Information From the VDC
Next topic: Get Information About a vApp