Instantiation binds the abstract requirements for resources such as memory, CPU, and networking expressed in a vApp, VM, or vApp template to concrete instances of appropriate resources in a target VDC.

vApp templates and the vApps and virtual machines created from them include detailed specifications of virtual hardware, network requirements, and other properties like computer names and descriptions, guest operating system configurations, storage leases, end user license agreement (EULA) text, and so on. Any time you create a vApp from a template or include a vApp or virtual machine in a composed vApp, you have the opportunity to modify those specifications so that the resulting configuration meets the needs of the workload. Instantiation operations use a POST request and create a vApp with a configuration you specify in the request body.

Not all configuration details of a vApp or virtual machine can be modified during instantiation. As an adjunct to instantiation, you can use various reconfiguration operations to update an existing vApp or virtual machine. See Reconfiguring vApps and Virtual Machines.

Instantiation Parameters

The InstantiationParams element is a generic parameter-passing mechanism that can apply to a vApp or virtual machine.

Table 1. Requests That Allow InstantiationParams
Request Request Body Description
instantiateVAppTemplate InstantiateVAppTemplateParams Creates a vApp from a vApp template. This simple form of instantiation is limited to creating a vApp that includes the set of virtual machines defined in the template.
composeVApp ComposeVAppParams Creates a vApp composed from any combination of vApp templates and virtual machines. Virtual machines referenced in the request body must be powered off and cannot have an independent disk attached. They can be sourced from any vApp or vApp template accessible to you. Any vApp referenced in the request body contributes all of its virtual machines to the composed vApp, but its vApp-level configuration details (such as vApp networks and lease settings) are ignored and replaced by the vApp-level instantiation parameters supplied in the request body.
recomposeVApp RecomposeVAppParams Edits a vApp to add, remove, or reconfigure virtual machines. Virtual machines referenced in the request body must be powered off and cannot have an independent disk attached. They can be sourced from any vApp or vApp template accessible to you. Any vApp added contributes all of its virtual machines to the composed vApp, but its vApp-level configuration details (such as vApp networks and lease settings) are ignored and replaced by the vApp-level instantiation parameters supplied in the request body.
cloneVApp CloneVAppParams Creates a copy of an existing vApp. You can include vApp-level instantiation parameters that apply to the copy. You can also include SourcedItem elements that apply instantiation parameters to virtual machines in the vApp.
instantiateOvf InstantiateOvfParams Creates a vApp or virtual machine from an OVF upload. This simple form of instantiation is limited to creating the vApp or virtual machine defined in the uploaded OVF package.

The set of elements and attributes that are allowed within an InstantiationParams element depends on whether the InstantiationParams apply to a vApp template or virtual machine.

Instantiation Parameters for vApps

An instantiateVAppTemplate, composeVApp, or recomposeVApp request can modify certain properties of a vApp by including an InstantiationParams element at the vApp level. The placement of vApp-level InstantiationParams depends on the type of request you are making:
  • In an instantiateVAppTemplate request, vApp-level instantiation parameters are included at the root level of the InstantiateVAppTemplateParams request body, preceding the Source element that references the template you are instantiating. See Instantiation Parameters for vApps
  • In a composeVApp request, vApp-level instantiation parameters are included in the SourcedItem whose Source element references the vApp template being instantiated or included in the composition.
  • In a recomposeVApp request, which specifies a vApp in the request URL, the vApp-level instantiation parameters are included at the root level of the RecomposeVAppParams request body.
  • In an instantiateOvf request, vApp-level instantiation parameters are included at the root level of the InstantiateOvfParams request body.
InstantiationParams for a vApp can include any of the following elements:
LeaseSettingsSection
Defines the terms of storage and deployment leases for the vApp. If this section is omitted, the vApp inherits the default lease settings of the containing organization.
NetworkConfigSection
Defines the properties of the vApp network and specifies how it is connected to one or more organization VDC networks. Unless you intend to create a vApp that has no connection to any network, you must include this section in your InstantiationParams.
StartupSection
Defines the order in which the virtual machines in the vApp start up and shut down. If this section is omitted, the startup and shutdown order of virtual machines in the vApp is indeterminate.

Instantiation Parameters for Virtual Machines

An instantiateVAppTemplate, composeVApp, or recomposeVApp request can modify certain properties of individual virtual machines by including InstantiationParams in the SourcedItem whose Source element references the virtual machine.

InstantiationParams for a virtual machine can include any of the following elements:

VirtualHardwareSection
Contains a description of the virtual hardware supported by a virtual machine. Each hardware resource is defined in an Item element. Instantiation parameters for a virtual machine can include individual items of the following types:
  • CPU (RASD resource type 3)
  • Memory (RASD resource type 4)
  • Hard disk (RASD resource type 17)
Important: Changes to most Item elements in a VirtualHardwareSection are ignored by the composeVApp operation.
GuestCustomizationSection
Contains guest customization parameters for the virtual machine.
OperatingSystemSection
Specifies the guest operating system installed on the virtual machine.
ProductSection
Contains information about software installed on the virtual machine.
NetworkConnectionSection
Specifies how the virtual NIC devices on the virtual machine are connected to the vApp network.
VmCapabilities
Allows you to specify virtual machine capabilities such as hot-add of memory or CPU.