pyvcloud.vcd.vapp module

class pyvcloud.vcd.vapp.VApp(client, name=None, href=None, resource=None)

Bases: object

add_access_settings(access_settings_list=None)

Add access settings to the vApp.

Parameters:access_settings_list (list) –

list of dictionaries, where each dictionary represents a single access setting. The dictionary structure is as follows,

  • type: (str): type of the subject. One of ‘org’ or ‘user’.
  • name: (str): name of the user or org.
  • access_level: (str): access_level of the particular subject.
    Allowed values are ‘ReadOnly’, ‘Change’ or ‘FullControl’.
Returns:an object containing EntityType.CONTROL_ACCESS_PARAMS XML data representing the updated Access Control List of the vApp.
Return type:lxml.objectify.ObjectifiedElement
add_disk_to_vm(vm_name, disk_size)

Add a virtual disk to a virtual machine in the vApp.

It assumes that the vm has already at least one virtual hard disk and will attempt to create another one with similar characteristics.

Parameters:
  • vm_name (str) – name of the vm to be customized.
  • disk_size (int) – size of the disk to be added, in MBs.
Returns:

an object containing EntityType.TASK XML data which represents the asynchronous task that is creating the disk.

Return type:

lxml.objectify.ObjectifiedElement

Raises:

EntityNotFoundException: if the named vm cannot be located. occurred.

add_vms(specs, deploy=True, power_on=True, all_eulas_accepted=None)

Recompose the vApp and add vms.

Parameters:
  • specs (dict) – vm specifications, see to_sourced_item() method for specification details.
  • deploy (bool) – True, if the vApp should be deployed at instantiation.
  • power_on – (bool): True if the vApp should be powered-on at instantiation
  • all_eulas_accepted (bool) – True confirms acceptance of all EULAs in the vApp.
Returns:

an object containing EntityType.VAPP XML data representing the updated vApp.

Return type:

lxml.objectify.ObjectifiedElement

attach_disk_to_vm(disk_href, vm_name)

Attach an independent disk to the vm with the given name.

Parameters:
  • disk_href (str) – href of the disk to be attached.
  • vm_name (str) – name of the vm to which the disk will be attached.
Returns:

an object containing EntityType.TASK XML data which represents the asynchronous task of attaching the disk.

Return type:

lxml.objectify.ObjectifiedElement

Raises:

EntityNotFoundException: if the named vm or disk cannot be located.

change_owner(href)

Change the ownership of vApp to a given user.

Parameters:href (str) – href of the new owner.
connect_org_vdc_network(orgvdc_network_name, retain_ip=None, is_deployed=None, fence_mode='bridged')

Connect the vApp to an org vdc network.

Parameters:
  • orgvdc_network_name (str) – name of the org vdc network to be connected to.
  • retain_ip (bool) – True, if the network resources such as IP/MAC of router will be retained across deployments.
  • is_deployed (bool) – True, if this org vdc network has been deployed.
  • fence_mode (str) – mode of connectivity to the parent network. Acceptable values are ‘bridged’, ‘isolated’ or ‘natRouted’. Default value is ‘bridged’.
Returns:

an object containing EntityType.TASK XML data which represents the asynchronous task that is connecting the vApp to the network.

Return type:

lxml.objectify.ObjectifiedElement

Raises:

EntityNotFoundException: if named org vdc network does not exist.

Raises:

InvalidStateException: if the vApp is already connected to the org vdc network.

connect_vm(mode='DHCP', reset_mac_address=False)
delete_vms(names)

Recompose the vApp and delete vms.

Parameters:names (list) – names (str) of vms to delete from the vApp.
Returns:an object containing EntityType.VAPP XML data representing the updated vApp.
Return type:lxml.objectify.ObjectifiedElement
deploy(power_on=None, force_customization=None)

Deploys the vApp.

Deploying the vApp will allocate all resources assigned to the vApp. TODO: Add lease_deployment_seconds param after PR 2036925 is fixed. https://jira.eng.vmware.com/browse/VCDA-465

Parameters:
  • power_on (bool) – specifies whether to power on/off vApp/vm on deployment. True by default, unless otherwise specified.
  • lease_deployment_seconds (str) – deployment lease in seconds.
  • force_customization (bool) – True, instructs vCD to force customization on deployment. False, no action is performed.
Returns:

an object containing EntityType.TASK XML data which represents the asynchronous task that is deploying the vApp.

Return type:

lxml.objectify.ObjectifiedElement

Raises:

OperationNotSupportedException – if the vApp can’t be deployed.

detach_disk_from_vm(disk_href, vm_name)

Detach the independent disk from the vm with the given name.

Parameters:
  • disk_href (str) – href of the disk to be detached.
  • vm_name (str) – name of the vm to which the disk will be detached.
Returns:

an object containing EntityType.TASK XML data which represents the asynchronous task of dettaching the disk.

Return type:

lxml.objectify.ObjectifiedElement

Raises:

EntityNotFoundException: if the named vm or disk cannot be located.

disconnect_org_vdc_network(orgvdc_network_name)

Disconnect the vApp from an org vdc network.

Parameters:orgvdc_network_name (str) – (str): name of the orgvdc network to be disconnected.
Returns:an object containing EntityType.TASK XML data which represents the asynchronous task that is disconnecting the vApp from the network.
Return type:lxml.objectify.ObjectifiedElement
Raises:InvalidStateException: if the named org vdc network is not connected to the vApp.
get_access_settings()

Get the access settings of the vApp.

Returns:an object containing EntityType.CONTROL_ACCESS_PARAMS which represents the access control list of the vApp.
Return type:lxml.objectify.ObjectifiedElement
get_admin_password(vm_name)

Fetch the admin password of a named vm in the vApp.

Parameters:vm_name (str) – name of the vm whose admin password we want to retrieve.
Returns:admin password of the named vm.
Return type:str
Raises:EntityNotFoundException: if the named vm can’t be found.
get_all_networks()

Helper method that returns the list of networks defined in the vApp.

Returns:a smart xpath string that represents the list of vApp networks.
Return type:xpath string
get_all_vms()

Retrieve all the vms in the vApp.

Returns:a list of lxml.objectify.ObjectifiedElement objects, where each object contains EntityType.VM XML data and represents one vm.
Return type:empty list or generator object
get_metadata()

Fetch metadata of the vApp.

Returns:an object containing EntityType.METADATA XML data which represents the metadata associated with the vApp.
Return type:lxml.objectify.ObjectifiedElement
get_power_state(vapp_resource=None)

Returns the status of the vApp.

Parameters:vapp_resource (lxml.objectify.ObjectifiedElement) – object containing EntityType.VAPP XML data representing the vApp whose power state we want to retrieve.
Returns:The status of the vApp, the semantics of the value returned is captured in pyvcloud.vcd.client.VCLOUD_STATUS_MAP
Return type:int
get_primary_ip(vm_name)

Fetch the primary ip of a vm (in the vApp) identified by its name.

Parameters:vm_name (str) – name of the vm whose primary ip we want to retrieve.
Returns:ip address of the named vm.
Return type:str
Raises:Exception: if the named vm or its NIC information can’t be found.
get_resource()

Fetches the XML representation of the vApp from vCD.

Will serve cached response if possible.

Returns:object containing EntityType.VAPP XML data representing the vApp.
Return type:lxml.objectify.ObjectifiedElement
get_vapp_network_name(index=0)

Returns the name of the network defined in the vApp by index.

Parameters:index (int) – index of the vApp network to retrieve. 0 if omitted.
Returns:name of the requested network.
Return type:str
Raises:EntityNotFoundException: if the named network could not be found.
get_vm(vm_name)

Retrieve the vm with the given name in this vApp.

Parameters:vm_name (str) – name of the vm to be retrieved.
Returns:an object contains EntityType.VM XML data that represents the vm.
Return type:lxml.objectify.ObjectifiedElement
Raises:EntityNotFoundException: if the named vm could not be found.
get_vm_moid(vm_name)

Fetch the moref of a named vm in the vApp.

Parameters:vm_name (str) – name of the vm whose moref we want to retrieve.
Returns:moref of the named vm.
Return type:str
Raises:EntityNotFoundException: if the named vm can’t be found.
is_deployed(vapp_resource=None)

Checks if a vApp is deployed or not.

Parameters:vapp_resource (lxml.objectify.ObjectifiedElement) – object containing EntityType.VAPP XML data representing the vApp whose power state we want to check.
Returns:True if the vApp is deployed else False.
Return type:bool
is_powered_off(vapp_resource=None)

Checks if a vApp is powered off or not.

Parameters:vapp_resource (lxml.objectify.ObjectifiedElement) – object containing EntityType.VAPP XML data representing the vApp whose power state we want to check.
Returns:True if the vApp is powered off else False.
Return type:bool
is_powered_on(vapp_resource=None)

Checks if a vApp is powered on or not.

Parameters:vapp_resource (lxml.objectify.ObjectifiedElement) – object containing EntityType.VAPP XML data representing the vApp whose power state we want to check.
Returns:True if the vApp is powered on else False.
Return type:bool
is_suspended(vapp_resource=None)

Checks if a vApp is suspended or not.

Parameters:vapp_resource (lxml.objectify.ObjectifiedElement) – object containing EntityType.VAPP XML data representing the vApp whose power state we want to check.
Returns:True if the vApp is suspended else False.
Return type:bool
power_off()

Power off the vms in the vApp.

Returns:an object containing EntityType.TASK XML data which represents the asynchronous task that is powering off the vApp.
Return type:lxml.objectify.ObjectifiedElement
Raises:OperationNotSupportedException – if the vApp can’t be powered off.
power_on()

Power on the vms in the vApp.

Returns:an object containing EntityType.TASK XML data which represents the asynchronous task that is powering on the vApp.
Return type:lxml.objectify.ObjectifiedElement
Raises:OperationNotSupportedException – if the vApp can’t be powered on.
power_reset()

Power resets the vms in the vApp.

Returns:an object containing EntityType.TASK XML data which represents the asynchronous task resetting the vApp.
Return type:lxml.objectify.ObjectifiedElement
Raises:OperationNotSupportedException – if the vApp can’t be power reset.
reboot()

Reboots the vms in the vApp.

Returns:an object containing EntityType.TASK XML data which represents the asynchronous task rebooting the vApp.
Return type:lxml.objectify.ObjectifiedElement
Raises:OperationNotSupportedException – if the vApp can’t be rebooted.
reload()

Reloads the resource representation of the vApp.

This method should be called in between two method invocations on the VApp object, if the former call changes the representation of the vApp in vCD.

remove_access_settings(access_settings_list=None, remove_all=False)

Remove access settings from the vApp.

Parameters:
  • access_settings_list (list) –

    list of dictionaries, where each dictionary represents a single access setting. The dictionary structure is as follows,

    • type: (str): type of the subject. One of ‘org’ or ‘user’.
    • name: (str): name of the user or org.
  • remove_all (bool) – True, if the entire Access Control List of the vApp should be removed, else False.
Returns:

an object containing EntityType.CONTROL_ACCESS_PARAMS XML data representing the updated access control setting of the vdc.

Return type:

lxml.objectify.ObjectifiedElement`

set_lease(deployment_lease=0, storage_lease=0)

Update lease settings of the vApp.

Parameters:
  • deployment_lease (int) – length of deployment lease in seconds.
  • storage_lease (int) – length of storage lease in seconds.
Returns:

an object containing EntityType.LEASE_SETTINGS XML data which represents the updated lease settings of the vApp.

Return type:

lxml.objectify.ObjectifiedElement

set_metadata(domain, visibility, key, value, metadata_type='MetadataStringValue')

Set metadata of the vApp.

Parameters:
  • domain (str) –
  • visibility (str) –
  • key (str) –
  • value (str) –
  • metadata_type (str) –
Returns:

an object containing EntityType.METADATA XML data which represents the updated metadata associated with the vApp.

Return type:

lxml.objectify.ObjectifiedElement

share_with_org_members(everyone_access_level='ReadOnly')

Share the vApp to all members of the organization.

Parameters:everyone_access_level – (str) : access level when sharing the vApp with everyone. Allowed values are ‘ReadOnly’, ‘Change’, or ‘FullControl’. Default value is ‘ReadOnly’.
Returns:an object containing EntityType.CONTROL_ACCESS_PARAMS XML data representing the updated access control setting of the vdc.
Return type:lxml.objectify.ObjectifiedElement
shutdown()

Shutdown the vApp.

Returns:an object containing EntityType.TASK XML data which represents the asynchronous task shutting down the vApp.
Return type:lxml.objectify.ObjectifiedElement
Raises:OperationNotSupportedException – if the vApp can’t be shutdown.
to_sourced_item(spec)

Creates a vm SourcedItem from a vm specification.

Parameters:spec (dict) –

a dictionary containing

  • vapp: (resource): (required) source vApp or vAppTemplate
    resource.
  • source_vm_name: (str): (required) source vm name.
  • target_vm_name: (str): (optional) target vm name.
  • hostname: (str): (optional) target guest hostname.
  • password: (str): (optional) the administrator password of the vm.
  • password_auto: (bool): (optional) auto generate administrator
    password.
  • password_reset: (bool): (optional) True, if the administrator
    password for this vm must be reset after first use.
  • cust_script: (str): (optional) script to run on guest
    customization.
  • network: (str): (optional) name of the vApp network to connect.
    If omitted, the vm won’t be connected to any network.
  • storage_profile: (str): (optional) the name of the storage
    profile to be used for this vm.
Returns:an object containing SourcedItem XML element.
Return type:lxml.objectify.ObjectifiedElement
undeploy(action='default')

Undeploys the vApp.

Parameters:action (str) –

specifies the action to be applied to all vms in the vApp. Accepted values are

  • powerOff: power off the virtual machines.
  • suspend: suspend the virtual machines.
  • shutdown: shut down the virtual machines.
  • force: attempt to power off the virtual machines. Failures in
    undeploying the virtual machine or associated networks are ignored. All references to the vApp and its vms are removed from the database.
  • default: use the actions, order, and delay specified in the
    StartupSection.
Returns:an object containing EntityType.TASK XML data which represents the asynchronous task that is undeploying the vApp.
Return type:lxml.objectify.ObjectifiedElement
Raises:OperationNotSupportedException – if the vApp can’t be undeployed.
unshare_from_org_members()

Unshare the vApp from all members of current organization.

Returns:an object containing EntityType.CONTROL_ACCESS_PARAMS XML data representing the updated access control setting of the vdc.
Return type:lxml.objectify.ObjectifiedElement