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:
Template contents that might influence composition of the request body include the following elements in the virtual machines that the template contains.
■
|
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 the OVF Descriptor of a vApp or vApp Template. |
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 Example: 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. |
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.
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 Example: Deploying a vApp to include additional elements in its InstantiationParams:
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 Example: Deploying a vApp.