Managed Object - VirtualApp

Returned by: CloneVApp_Task, CreateVApp
Extends: ResourcePool
See also: Datastore, Folder, HttpNfcLease, ManagedEntity, Network, ResourcePool, VAppCloneSpec, VAppConfigInfo, VAppConfigSpec, VirtualAppLinkInfo
Since: vSphere API 4.0

Managed Object Description

Represents a multi-tiered software solution. A vApp is a collection of virtual machines (and potentially other vApp containers) that are operated and monitored as a unit. From a manage perspective, a multi-tiered vApp acts a lot like a virtual machine object. It has power operations, networks, datastores, and its resource usage can be configured.

From a technical perspective, a vApp container is a specialized resource pool that has been extended with the following capabilities:

Product information such as product name, vendor, properties, and licenses.

A power-on/power-off sequence specification

Support for import/export vApps as OVF packages

An OVF environment that allows for application-level customization

Destroying a vApp

When a vApp is destroyed, all of its virtual machines are destroyed, as well as any child vApps.

The VApp.Delete privilege must be held on the vApp as well as the parent folder of the vApp. Also, the VApp.Delete privilege must be held on any child vApps that would be destroyed by the operation.

Properties

Name	Type	Description
childLink*	VirtualAppLinkInfo[]	List of linked children *Since* vSphere API 4.1
datastore* P	ManagedObjectReference[] to a Datastore[]	A collection of references to the subset of datastore objects used by this vApp.
network* P	ManagedObjectReference[] to a Network[]	A collection of references to the subset of network objects that is used by this virtual machine.
parentFolder* P	ManagedObjectReference to a Folder	A reference to the parent folder in the VM and Template folder hierarchy. This is only set for a root vApp. A root vApp is a vApp that is not a child of another vApp.
parentVApp*	ManagedObjectReference to a ManagedEntity	Reference to the parent vApp. *Since* vSphere API 4.1
vAppConfig* P	VAppConfigInfo	Configuration of this package.
Properties inherited from ResourcePool
childConfiguration, config, owner, resourcePool, runtime, summary, vm
Properties inherited from ManagedEntity
alarmActionsEnabled, configIssue, configStatus, customValue, declaredAlarmState, disabledMethod, effectiveRole, name, overallStatus, parent, permission, recentTask, tag, triggeredAlarmState
Properties inherited from ExtensibleManagedObject
availableField, value

*May not be presentPRequired privilege - see tooltip for details

Methods

Methods defined in this Managed Object
CloneVApp_Task, ExportVApp, PowerOffVApp_Task, PowerOnVApp_Task, SuspendVApp_Task, unregisterVApp_Task, UpdateLinkedChildren, UpdateVAppConfig
Methods inherited from ResourcePool
CreateChildVM_Task, CreateResourcePool, CreateVApp, DestroyChildren, ImportVApp, MoveIntoResourcePool, QueryResourceConfigOption, RefreshRuntime, RegisterChildVM_Task, UpdateChildResourceConfiguration, UpdateConfig
Methods inherited from ManagedEntity
Destroy_Task, Reload, Rename_Task
Methods inherited from ExtensibleManagedObject
setCustomValue

CloneVApp_Task

Creates a clone of this vApp.

Any % (percent) character used in this name parameter must be escaped, unless it is used to start an escape sequence. Clients may also escape any other characters in this name parameter.

When invoking this method, the following privilege checks occur:

The privilege VApp.Clone is required on this vApp.
If the target is a resource pool, the privilege Resource.AssignVAppToPool is required on it.
If the target is a vApp, the privileges VApp.Clone and VApp.AssignVApp are required on it.

Additional privileges are required by the clone spec provided. See VAppCloneSpec for details.

Required Privileges: VApp.Clone

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualApp used to make the method call.
name	xsd:string	The name of the new vApp.
target	ManagedObjectReference to a ResourcePool	The parent entity of the new vApp. Must be of type ResourcePool or VirtualApp.
spec	VAppCloneSpec	Specifies how to clone the vApp.

Return Value

Type	Description
ManagedObjectReference to a Task

Faults

Type	Description
FileFault	Thrown if there was an error accessing one of the virtual machine files.
InsufficientResourcesFault	Thrown if this operation would violate a resource usage policy.
InvalidDatastore	Thrown if the operation cannot be performed on the target datastores.
InvalidPowerState	Thrown if the vApp is powered on.
InvalidState	Thrown if the operation cannot be performed because of the vApp's current state. For example, if the virtual machine configuration information is not available, or if the vApp is running.
MigrationFault	Thrown if it is not possible to migrate one of the virtual machines to the destination. This is typically due to hosts being incompatible, such as mismatch in network polices or access to networks and datastores. Typically, a more specific subclass is thrown.
NotSupported	Thrown if the operation is not supported by the current agent.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the vApp is busy.
VmConfigFault	Thrown if one of the virtual machines are not compatible with a destination host. Typically, a specific subclass of this exception is thrown, such as IDEDiskNotSupported.

ExportVApp

Obtains an export lease on this vApp. The export lease contains a list of URLs for the disks of the virtual machines in this vApp, as well as a ticket that gives access to these URLs.

See HttpNfcLease for information on how to use the lease.

Required Privileges: VApp.Export

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualApp used to make the method call.

Return Value

Type	Description
ManagedObjectReference to a HttpNfcLease	The export lease on this vApp. The export task continues running until the lease is completed or aborted.

Faults

Type	Description
FileFault	Thrown if there was an error accessing one of the virtual machine files.
InvalidPowerState	Thrown if the vApp is powered on.
InvalidState	Thrown if the operation cannot be performed because of the vApp's current state. For example, if the virtual machine configuration information is not available, or if the vApp is running.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the vApp is busy.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ExportVApp" type="vim25:ExportVAppRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ExportVAppResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

PowerOffVApp_Task

Stops this vApp.

The virtual machines (or child vApps) will be stopped in the order specified in the vApp configuration, if force is false. If force is set to true, all virtual machines are powered-off (in no specific order and possibly in parallel) regardless of the vApp auto-start configuration.

While a vApp is stopping, all power operations performed on sub entities are disabled through the VIM API. They will throw TaskInProgress.

Required Privileges: VApp.PowerOff

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualApp used to make the method call.
force	xsd:boolean	If force is false, the shutdown order in the vApp is executed. If force is true, all virtual machines are powered-off (regardless of shutdown order).

Return Value

Type	Description
ManagedObjectReference to a Task

Faults

Type	Description
InvalidPowerState	Thrown if the vApp is not running
InvalidState	Thrown if the operation cannot be performed because of the vApp's current state. For example, if the vApp is in the process of being started.
MissingPowerOffConfiguration	Thrown if no vApp powerOff configuration has been specified.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the vApp is busy.
VAppConfigFault

PowerOnVApp_Task

Starts this vApp.

The virtual machines (or sub vApps) will be started in the order specified in the vApp configuration. If the vApp is suspended (@see vim.VirtualApp.Summary.suspended), all suspended virtual machines will be powered-on based on the defined start-up order.

While a vApp is starting, all power operations performed on sub entities are disabled through the VIM API. They will throw TaskInProgress.

In case of a failure to power-on a virtual machine, the exception from the virtual machine power on is returned, and the power-on sequence will be terminated. In case of a failure, virtual machines that are already started will remain powered-on.

Required Privileges: VApp.PowerOn

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualApp used to make the method call.

Return Value

Type	Description
ManagedObjectReference to a Task

Faults

Type	Description
FileFault	Thrown if there is a problem accessing the virtual machine on the filesystem.
InsufficientResourcesFault	Thrown if this operation would violate a resource usage policy.
InvalidPowerState	Thrown if the vApp is already running
InvalidState	Thrown if it fails to power on a virtual machine due to no host availability, or unable to access the configuration file of a VM.
MissingNetworkIpConfig	Thrown if no network configuration exists for the primary network for the vApp.
NotEnoughLicenses	Thrown if there are not enough licenses to power on one or more virtual machines.
NotSupported	Thrown if the vApp is marked as a template.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the vApp is busy
VAppConfigFault	Thrown if a configuration issue on a vApp prevents the power-on. Typically, a more specific fault, MissingPowerOnConfiguration, is thrown.
VmConfigFault	Thrown if a configuration issue on the vApp or a virtual machine in the vApp prevents the power-on to complete. Typically, a more specific fault, such as InvalidPropertyType is thrown.

SuspendVApp_Task

Suspends this vApp.

Suspends all powered-on virtual machines in a vApp, including virtual machines in child vApps. The virtual machines are suspended in the same order as used for a power-off operation (reverse power-on sequence).

While a vApp is being suspended, all power operations performed on sub entities are disabled through the VIM API. They will throw TaskInProgress.

Required Privileges: VApp.Suspend
Since: vSphere API 4.1

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualApp used to make the method call.

Return Value

Type	Description
ManagedObjectReference to a Task

Faults

Type	Description
InvalidPowerState	Thrown if the vApp is not running
InvalidState	Thrown if the operation cannot be performed because of the vApp's current state. For example, if the vApp is in the process of being started.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the vApp is busy.
VAppConfigFault

unregisterVApp_Task

Removes this vApp from the inventory without removing any of the virtual machine's files on disk. All high-level information stored with the management server (ESX Server or VirtualCenter) is removed, including information such as vApp configuration, statistics, permissions, and alarms.

Required Privileges: VApp.Unregister

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualApp used to make the method call.

Return Value

Type	Description
ManagedObjectReference to a Task

Faults

Type	Description
ConcurrentAccess
InvalidPowerState	Thrown if the vApp is running.
InvalidState
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

UpdateLinkedChildren

Reconfigure the set of linked children.

A VirtualMachine and vApp can be added as a linked child as long as it is not a direct child of another vApp. In case it is a linked child, the existing link is removed and replaced with the new link specified in this call.

An InvalidArgument fault is thrown if a link target is a direct child of another vApp, or if the addition of the link will result in a vApp with a cycle. For example, a vApp cannot be linked to itself.

The removeSet must refer to managed entities that are currently linked children. Otherwise, an InvalidArgument exception is thrown.

For each entity being linked, the operation is subject to the following privilege checks:

If the object being linked is a vApp, VApp.Move must be held on the vApp being linked and its former parent vApp (if any). The privilege VApp.AssignVApp must be held on this vApp.
If the object being linked is a VirtualMachine, VApp.AssignVM is required on both the target vApp, the VirtualMachine, and its former parent vApp (if any).

Privilege checks for each entity in the removeSet are similar to the entities in the addChangeSet, except that there is no target vApp.

This operation is only transactional with respect to each individual link change. The changes are processed sequentially and committed one at a time. The addChangeSet is processed first, followed by the removeSet. If a failure is detected, then the method terminates with an exception.

Required Privileges: Dynamic - See discussion above
Since: vSphere API 4.1

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualApp used to make the method call.
addChangeSet*	VirtualAppLinkInfo[]	a set of LinkInfo objects that either add a new link or modify an exisiting link.
removeSet*	ManagedObjectReference[] to a ManagedEntity[]	a set of entities that should no longer link to this vApp.

*Need not be set

Return Value

Type	Description
None

Faults

Type	Description
ConcurrentAccess	Thrown if a concurrent modification happens while adding the link.
InvalidArgument	See above description.
NotSupported	Thrown if the target of the link is not in the same datacenter.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateLinkedChildren" type="vim25:UpdateLinkedChildrenRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateLinkedChildrenResponse">
            <complexType/>
         </element>

UpdateVAppConfig

Updates the vApp configuration.

Updates in different areas require different privileges. See VAppConfigSpec for a full description.

Required Privileges: Dynamic - See discussion above

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the VirtualApp used to make the method call.
spec	VAppConfigSpec	contains the updates to the current configuration. Any set element, is changed. All values in the spec that is left unset, will not be modified.

Return Value

Type	Description
None

Faults

Type	Description
ConcurrentAccess	Thrown if another operation conflicted with this operation.
DuplicateName
FileFault
InsufficientResourcesFault
InvalidArgument	Thrown for wrong input.
InvalidDatastore
InvalidIndexArgument	Thrown if a wrong key is used in one of the arrays. For example, for duplicated entries in entityConfig.
InvalidName
InvalidPowerState	Thrown if the reconfiguration is not possible given the current powerState of the vApp.
InvalidState
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the vApp is busy.
VmConfigFault	Thrown for bad configuration, such as invalid property types.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateVAppConfig" type="vim25:UpdateVAppConfigRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateVAppConfigResponse">
            <complexType/>
         </element>