Managed Object - VirtualApp

Returned by
CloneVApp_Task, CreateVApp
Extends
ResourcePool
See also
Datastore, Folder, HttpNfcLease, Network, ResourcePool, VAppCloneSpec, VAppConfigInfo, VAppConfigSpec,
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:

  • 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
    datastore* PManagedObjectReference[]
    to a Datastore[]

    A collection of references to the subset of datastore objects used by this vApp.
    network* PManagedObjectReference[]
    to a Network[]

    A collection of references to the subset of network objects that is used by this virtual machine.
    parentFolder* PManagedObjectReference
    to a Folder

    A reference to the parent folder in the VM and Template folder hierarchy. This can be null if the vApp is not associated with a VM & Template folder. A child vApp can never be associated with a vApp, but it is also not a requirement that a root vApp is linked into the VM and Template view.
    vAppConfig* PVAppConfigInfo

    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, unregisterVApp_Task, UpdateVAppConfig
    Methods inherited from ResourcePool
    CreateChildVM_Task, CreateResourcePool, CreateVApp, DestroyChildren, ImportVApp, MoveIntoResourcePool, 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:

    Additional privileges are required by the clone spec provided. See VAppCloneSpec for details.
    Required Privileges
    VApp.Clone

    Parameters

    NameTypeDescription
    _thisManagedObjectReference A reference to the VirtualApp used to make the method call.
    namexsd:string

    The name of the new vApp.
    targetManagedObjectReference
    to a ResourcePool

    The parent entity of the new vApp. Must be of type ResourcePool or VirtualApp.
    specVAppCloneSpec

    Specifies how to clone the vApp.

    Return Value

    Type Description
    ManagedObjectReference
    to a Task

    Faults

    Type Description
    FileFaultThrown if there was an error accessing one of the virtual machine files.
    InsufficientResourcesFaultThrown if this operation would violate a resource usage policy.
    InvalidDatastoreThrown if the operation cannot be performed on the target datastores.
    InvalidPowerStateThrown if the vApp is powered on.
    InvalidStateThrown 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.
    MigrationFaultThrown 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.
    NotSupportedThrown if the operation is not supported by the current agent.
    RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
    TaskInProgressThrown if the vApp is busy.
    VmConfigFaultThrown 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

    NameTypeDescription
    _thisManagedObjectReference 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
    FileFaultThrown if there was an error accessing one of the virtual machine files.
    InvalidPowerStateThrown if the vApp is powered on.
    InvalidStateThrown 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.
    RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
    TaskInProgressThrown if the vApp is busy.

    Show WSDL type definition



    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 is disabled through the VIM API. They will return TaskInProgress.

    Required Privileges
    VApp.PowerOff

    Parameters

    NameTypeDescription
    _thisManagedObjectReference A reference to the VirtualApp used to make the method call.
    forcexsd: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
    InvalidPowerStateThrown if the vApp is not running
    InvalidStateThrown 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.
    MissingPowerOffConfigurationThrown if no vApp powerOff configuration has been specified.
    RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
    TaskInProgressThrown 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.

    While a vApp is starting, all power operations performed on sub entities is disabled through the VIM API. They will return 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

    NameTypeDescription
    _thisManagedObjectReference A reference to the VirtualApp used to make the method call.

    Return Value

    Type Description
    ManagedObjectReference
    to a Task

    Faults

    Type Description
    FileFaultThrown if there is a problem accessing the virtual machine on the filesystem.
    InsufficientResourcesFaultThrown if this operation would violate a resource usage policy.
    InvalidPowerStateThrown if the vApp is already running
    InvalidStateThrown if it fails to power on a virtual machine due to no host availability, or unable to access the configuration file of a VM.
    MissingNetworkIpConfigThrown if no network configuration exists for the primary network for the vApp.
    NotEnoughLicensesThrown if there are not enough licenses to power on one or more virtual machines.
    NotSupportedThrown if the vApp is marked as a template.
    RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
    TaskInProgressThrown if the vApp is busy
    VAppConfigFaultThrown if a configuration issue on a vApp prevents the power-on. Typically, a more specific fault, MissingPowerOnConfiguration, is thrown.
    VmConfigFaultThrown 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.



    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

    NameTypeDescription
    _thisManagedObjectReference A reference to the VirtualApp used to make the method call.

    Return Value

    Type Description
    ManagedObjectReference
    to a Task

    Faults

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



    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

    NameTypeDescription
    _thisManagedObjectReference A reference to the VirtualApp used to make the method call.
    specVAppConfigSpec

    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
    ConcurrentAccessThrown if another operation conflicted with this operation.
    DuplicateName
    FileFault
    InsufficientResourcesFault
    InvalidArgumentThrown for wrong input.
    InvalidDatastore
    InvalidIndexArgumentThrown if a wrong key is used in one of the arrays. For example, for duplicated entries in entityConfig.
    InvalidName
    InvalidPowerStateThrown if the reconfiguration is not possible given the current powerState of the vApp.
    InvalidState
    RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
    TaskInProgressThrown if the vApp is busy.
    VmConfigFaultThrown for bad configuration, such as invalid property types.

    Show WSDL type definition