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.
Requests That Allow
InstantiationParams
|
|
|
|
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.
|
|
OperatingSystemSection
|
Specifies the guest
operating system installed on the virtual machine.
|
|
NetworkConnectionSection
|
Specifies how the
virtual NIC devices on the virtual machine are connected to the vApp network.
|
|
GuestCustomizationSection
|
Contains guest
customization parameters for the virtual machine.
|
|
VmCapabilities
|
Allows you to specify
virtual machine capabilities such as hot-add of memory or CPU.
|