Virtual Machine Methods

class netlab.api.VmApiMixin
vm_clone_task(*, parent_vm_id, parent_snapname, clone_role, clone_type, clone_name, clone_datastore=None, clone_storage_alloc=<CloneStorageAllocation.ONDEMAND: 'ONDEMAND'>, clone_vh_id=None, clone_vhg_id=None, clone_comments=None, copy_bios_uuid=False, **kwargs)

Method to call a task to clone a virtual machine.

Parameters
  • parent_vm_id (int) – Parent virtual machine identifier.

  • parent_snapname (str) – Parent snapshot name.

  • clone_role (netlab.enums.CloneRole) – Cloned virtual machine role.

  • clone_type (netlab.enums.CloneType) – Cloned virtual machine type.

  • clone_name (str) – Cloned virtual machine name.

  • clone_datastore (str) – Datastore cloned virtual machine will reside on.

  • clone_storage_alloc (netlab.enums.CloneStorageAllocation) – Cloned virtual machine storage allocation.

  • clone_vh_id (int) – The virtual host the cloned virtual machine will reside on.

  • clone_vhg_id (int) – The virtual host group identifier. NOT SUPPORTED!

  • clone_comments (str) – Comments for the cloned virtual machine.

vm_datacenter_find(*, vdc_name, **kwargs)

This method allows you to find a datacenter’s vdc_id by the datacenter name.

Parameters

vdc_name (str) – VM Datacenter name.

Returns

On success, returns vdc_id. If there is no VDC matching, returns None.

Return type

int

vm_datacenter_get(*, vdc_id, **kwargs)

This method allows you to retrieve a datacenter’s information by vdc_id.

Parameters

vdc_id (int) – VM Datacenter identifier.

Returns

On success, returns an object with the following properties:

Return type

dict

Properties

vdc_agent_hostname

Agent hostname/IP address.

vdc_agent_password

Agent password.

vdc_agent_username

Agent username.

vdc_date_added

Timestamp of when VDC was added to NETLAB+.

vdc_date_tested

Timestamp of when VDC was last tested.

vdc_last_test_status

Status of last VDC test.

vdc_id

VM Datacenter identifier.

vdc_name

VM Datacenter name.

vdt_type

VM Datacenter type.

vdt_name

VM Datacenter type name.

vm_datacenter_list(**kwargs)

This method allows you to retrieve all datacenters’ information.

Returns

A list of objects with the following properties:

Return type

list

Properties

vdc_agent_hostname

Agent hostname/IP address.

vdc_agent_password

Agent password.

vdc_agent_username

Agent username.

vdc_date_added

Timestamp of when VDC was added to NETLAB+.

vdc_date_tested

Timestamp of when VDC was last tested.

vdc_last_test_status

Status of last VDC test.

vdc_id

VM Datacenter identifier.

vdc_name

VM Datacenter name.

vdt_type

VM Datacenter type.

vdt_name

VM Datacenter type name.

vm_datacenter_test(*, vdc_id, **kwargs)

This method allows you to call a task to test communication to datacenter.

Parameters

vdc_id (int) – VM Datacenter identifier.

Returns

On success returns ‘PASSED’, otherwise returns ‘FAILED’.

Return type

‘PASSED’ or ‘FAILED’

vm_host_find(*, vh_name, **kwargs)

This method allows you to find a virtual host’s vh_id by the virtual host name.

Parameters

vh_name (str) – Virtual Host name.

Returns

On success, returns vh_id. If there is no matching Virtual Host, returns None.

Return type

int

vm_host_get(*, vh_id, **kwargs)

This method allows you to retrieve a virtual host information.

Parameters

vh_id (int) – Virtual host identifier.

Returns

On success, returns an object with the following properties:

Return type

dict

Properties

vdc_id

Agent hostname/IP address.

vdc_name

VM Datacenter name.

vdt_type

VM Datacenter type.

vdt_name

VM Datacenter type name.

vh_bios_date

Timestamp of BIOS creation date.

vh_bios_version

BIOS version installed.

vh_com_path

Virtual host communication path.

vh_cpu_cores

Total count of CPU cores on virtual host.

vh_cpu_count

Total count of physical CPUs on virtual host.

vh_cpu_mhz

Speed in MHz of CPU.

vh_cpu_model

CPU model identification.

vh_cpu_threads

Number of threads CPUs can handle.

vh_date_added

Timestamp of virtual host added to NETLAB+.

vh_date_modified

Timestamp of virtual host information has been modified.

vh_date_tested

Timestamp of virtual host test communication.

vh_id

Virtual host identifier.

vh_inside_ipv4_addr

Inside interface ipv4 address.

vh_inside_vswitch_0

Virtual host inside vSwitch.

vh_last_test_status

Status of last virtual host test communication.

vh_memory_mb

Total RAM in MB of virtual host.

vh_name

Virtual host hostname.

vh_online

Virtual host is online.

vh_os_build

Operating system build number.

vh_os_description

Operating system description.

vh_os_name

Operating system name.

vh_os_type

Operating system type.

vh_os_vendor

Operating system vender.

vh_os_version

Operating system version.

vh_outside_ipv4_addr

Outside interface ipv4 address.

vh_pra_enabled

Proactive resource awareness is enabled.

vh_pra_max_cpu

Max number of CPUs for PRA.

vh_pra_max_mem_mb

Max amount of RAM in MB for PRA.

vh_pra_max_vm

Max amount of virtual machines for PRA.

vh_sys_model

System model.

vh_sys_service_tag

System service tag.

vh_sys_vendor

System vendor.

vh_uuid

Virtual host unique global identifier.

vm_host_list(*, vdc_id=0, **kwargs)

This method allows you to retrieve a list of virtual hosts information.

Parameters

vdc_id (str) – VM Datacenter identifier. If not specified, will return from all datacenters.

Returns

Returns a list of objects with the following properties:

Return type

dict

Properties

vdc_id

Agent hostname/IP address.

vdc_name

VM Datacenter name.

vdt_type

VM Datacenter type.

vdt_name

VM Datacenter type name.

vh_bios_date

Timestamp of BIOS creation date.

vh_bios_version

BIOS version installed.

vh_com_path

Virtual host communication path.

vh_cpu_cores

Total count of CPU cores on virtual host.

vh_cpu_count

Total count of physical CPUs on virtual host.

vh_cpu_mhz

Speed in MHz of CPU.

vh_cpu_model

CPU model identification.

vh_cpu_threads

Number of threads CPUs can handle.

vh_date_added

Timestamp of virtual host added to NETLAB+.

vh_date_modified

Timestamp of virtual host information has been modified.

vh_date_tested

Timestamp of virtual host test communication.

vh_id

Virtual host identifier.

vh_inside_ipv4_addr

Inside interface ipv4 address.

vh_inside_vswitch_0

Virtual host inside vSwitch.

vh_last_test_status

Status of last virtual host test communication.

vh_memory_mb

Total RAM in MB of virtual host.

vh_name

Virtual host hostname.

vh_online

Virtual host is online.

vh_os_build

Operating system build number.

vh_os_description

Operating system description.

vh_os_name

Operating system name.

vh_os_type

Operating system type.

vh_os_vendor

Operating system vender.

vh_os_version

Operating system version.

vh_outside_ipv4_addr

Outside interface ipv4 address.

vh_pra_enabled

Proactive resource awareness is enabled.

vh_pra_max_cpu

Max number of CPUs for PRA.

vh_pra_max_mem_mb

Max amount of RAM in MB for PRA.

vh_pra_max_vm

Max amount of virtual machines for PRA.

vh_sys_model

System model.

vh_sys_service_tag

System service tag.

vh_sys_vendor

System vendor.

vh_uuid

Virtual host unique global identifier.

vm_inventory_add(*, vdc_id, vm_uuid, vm_name, vm_path=None, vm_alloc_mem_mb, vm_alloc_cpu_n, vhg_id=None, vh_id=None, vm_role=<VirtualMachineRole.NORMAL: 'NORMAL'>, vm_comments=None, vm_vendor_os_id=None, vm_vendor_os_name=None, vm_netlab_os_id=None, vm_parent_id=None, vm_parent_snapname=None, **kwargs)

``vm_inventory_add`` is deprecated, please use ``vm_inventory_import_task`` instead

Add virtual machines to NETLAB+ inventory.

Parameters
  • vdc_id (int) – VM Datacenter identifier.

  • vhg_id (int) – Virtual host group identifier.

  • vh_id (int) – Virtual host identifier.

  • vm_uuid (str) – Virtual machine unique identifier.

  • vm_name (str) – Virtual machine name.

  • vm_path (str) – Virtual machine path on datastore.

  • vm_role (netlab.enums.VirtualMachineRole) – Virtual machine role in NETLAB+ inventory.

  • vm_alloc_mem_mb (int) – Total amount of allocated RAM.

  • vm_alloc_cpu_n (int) – Total amount of allocated CPUs.

  • vm_comments (str) – Virtual machine comments from VMX.

  • vm_vendor_os_id (str) – Vendor operating system identifier.

  • vm_vendor_os_name (str) – Vendor operating system name.

  • vm_netlab_os_id (str) – NETLAB+ match to vm_vendor_os_id.

  • vm_parent_id (int) – Virtual machine parent identifier, if VM is a link clone.

  • vm_parent_snapname (str) – Virtual machine parent snapname, if VM is a link clone.

Returns

Returns a list of object with the following properties:

Return type

list[dict]

properties

vm_id

Virtual machine identifier.

vm_inventory_get(*, vm_id, **kwargs)

This method allows you to retrieve one or more virtual machines from NETLAB+ inventory.

Parameters

vm_id (int) – Virtual machine identifier.

Returns

Returns an object with the following properties:

Return type

dict

Properties

pc_id

Remote pc identifier.

pc_label

Remote pc label.

pc_os_id

NETLAB+ operating system identifier.

pc_os_name

NETLAB+ operating system name.

pc_pod_id

If attached to a pod, pod identifier.

pc_vm_id

Virtual machine identifier.

pod_name

Pod name.

vdc_id

Virtual datacenter identifier.

vdc_name

Virtual datacenter name.

vh_id

Virtual host identifier.

vh_name

Virtual host name.

vhg_id

Virtual host group identifier.

vhg_name

Virtual host group name.

vm_alloc_cpu_n

Total amount of allocated CPUs.

vm_alloc_mem_mb

Total amount of allocated RAM.

vm_child_count

Total count of children VMs.

vm_comments

Virtual machine comments from VMX.

vm_date_added

Timestamp of virtual machine added to NETLAB+ inventory.

vm_id

Virtual machine identifier.

vm_name

Virtual machine name.

vm_netlab_os_id

NETLAB+ match to vm_vendor_os_id.

vm_parent_id

Virtual machine parent identifier, if VM is a link clone.

vm_parent_name

Virtual machine parent name.

vm_parent_role

Parent virtual machine role.

vm_parent_snapname

Virtual machine parent snapname, if VM is a link clone.

vm_path

Virtual machine path on datastore.

vm_power_state

Virtual machine power state.

vm_role

Virtual machine role in NETLAB+ inventory.

vm_snapshot

This is what the VM reverts to when the pod is reset. You can take multiple snapshots with the same name, without having to update this field. Update this field with a call to pod_pc_update()

vm_uuid

Virtual machine unique identifier.

vm_vendor_os_id

Vendor operating system identifier.

vm_vendor_os_name

Vendor operating system name.

vm_inventory_import_task(*, vdc_id, vm_property_list, **kwargs)

Method to call a task to import virtual machine into NETLAB+ inventory.

Parameters
  • vdc_id (int) – Virtual datacenter identifier.

  • vm_property_list (list) – Virtual machine property list of the following properties:

properties

vm_uuid

Virtual machine unique identifier.

vhg_id

Virtual host group identifier.

vh_id

Virtual host identifier.

vm_name

Virtual machine name.

vm_role

Virtual machine role in NETLAB+ inventory. netlab.enums.VirtualMachineRole

vm_alloc_mem_mb

Total amount of allocated RAM.

vm_alloc_cpu_n

Total amount of allocated CPUs.

vm_comments

Virtual machine comments from VMX.

vm_vendor_os_id

Vendor operating system identifier.

vm_vendor_os_name

Vendor operating system name.

vm_netlab_os_id

NETLAB+ match to vm_vendor_os_id.

Returns

List of results

Return type

list[dict]

return properties

status

‘OK’ or error.

vm_id

Virtual machine identifier.

vm_inventory_list(*, vdc_id=None, roles=None, attached=None, **kwargs)

This method allows you to list the virtual machines from NETLAB+ inventory.

Parameters
  • vdc_id (int) – VM Datacenter identifier.

  • roles (list) – Filter by specified roles.

  • attached (int) – List virtual machines attached to a pod.

Returns

Returns an object with the following properties:

Return type

dict

Properties

pc_id

Remote pc identifier.

pc_label

Remote pc label.

pc_os_id

NETLAB+ operating system identifier.

pc_os_name

NETLAB+ operating system name.

pc_pod_id

If attached to a pod, pod identifier.

pc_vm_id

Virtual machine identifier.

pod_name

Pod name.

vdc_id

Virtual datacenter identifier.

vdc_name

Virtual datacenter name.

vh_id

Virtual host identifier.

vh_name

Virtual host name.

vhg_id

Virtual host group identifier.

vhg_name

Virtual host group name.

vm_alloc_cpu_n

Total amount of allocated CPUs.

vm_alloc_mem_mb

Total amount of allocated RAM.

vm_child_count

Total count of children VMs.

vm_comments

Virtual machine comments from VMX.

vm_date_added

Timestamp of virtual machine added to NETLAB+ inventory.

vm_id

Virtual machine identifier.

vm_name

Virtual machine name.

vm_netlab_os_id

NETLAB+ match to vm_vendor_os_id.

vm_parent_id

Virtual machine parent identifier, if VM is a link clone.

vm_parent_name

Virtual machine parent name.

vm_parent_role

Parent virtual machine role.

vm_parent_snapname

Virtual machine parent snapname, if VM is a link clone.

vm_path

Virtual machine path on datastore.

vm_power_state

Virtual machine power state.

vm_role

Virtual machine role in NETLAB+ inventory.

vm_snapshot

This is what the VM reverts to when the pod is reset. You can take multiple snapshots with the same name, without having to update this field. Update this field with a call to pod_pc_update()

vm_uuid

Virtual machine unique identifier.

vm_vendor_os_id

Vendor operating system identifier.

vm_vendor_os_name

Vendor operating system name.

vm_inventory_remove_datacenter_task(*vm_id, **kwargs)

Remove virtual machine from NETLAB+ inventory and datacenter. Does NOT remove VM from disk.

Parameters

vm_id (int) – Virtual machine identifier.

Returns

The removal completed successfully.

Return type

‘OK’

vm_inventory_remove_disk_task(*, vm_id, **kwargs)

Remove virtual machine from NETLAB+ inventory, datacenter, and disk.

WARNING: this method permanantly deletes the virtual machine files from disk. This operation cannot be undone.

Parameters

vm_id (int) – Virtual machine identifier.

Returns

The removal completed successfully.

Return type

‘OK’

vm_inventory_remove_local(*, vm_id, **kwargs)

Remove virtual machine from NETLAB+ inventory only. Does NOT remove VM from datacenter or disk.

Parameters

vm_id (int) – Virtual machine identifier.

Returns

The removal completed successfully.

Return type

‘OK’

vm_license_list(*, vdc_id=None, vh_id=None, vl_server=None, vl_key=None, vl_type=None, **kwargs)

This method returns a list of cached VMware vCenter and server licenses.

This license cache is populated by any of the following events: - every 12 hours per scheduled task - when datacenters are added or removed - when virtual machine host servers are added or removed - by calling API method VmApiMixin.vm_license_update_task()

The cache updates each time licenses are scanned. If a vCenter server for a datacenter is unreachable during the scan, the licenses managed by that vCenter will be missing from the cache until the vCenter can be reached on a subsequent scan.

Parameters
  • vdc_id (int) – return licenses for datacenter identified by vdc_id in NETLAB+

  • vh_id (int) – return license for vm host identified by vh_id in NETLAB+

  • vl_server (int) – return license with hostname or IP address matching vl_server in vCenter

  • vl_key (int) – return license with key matching vl_key in vCenter

  • vl_type (int) – License type. netlab.enums.VirtualMachineLicenseType

Returns

A list of dictionaries with the following properties.

Return type

list[dict]

Properties

vdc_id

NETLAB+ datacenter identifier associated with license.

vh_id

If not None, the NETLAB+ vm host identifier associated with license.

vl_type

License type. netlab.enums.VirtualMachineLicenseType

vl_server

Hostname or IP address of the server as registered in vCenter.

vl_product

Licensed product name.

vl_key

Licnese key.

vl_units

Number of units licensed (i.e. processors) depending on server type.

vl_expiration

The expiration date and time of the license (UTC) or None if no expiration.

vl_last_udpate

The date and time this license was last queried and cached.

vm_license_update_task(**kwargs)

This method scans each vCenter server in all NETLAB+ datacenters and returns the VMware license status of VMware vCenter and VMware host servers.

  • The license information is cached for quick retreival using subsequent calls to VmApiMixin.vm_license_list().

  • It is usually not necessary to call vm.liense.update.task directly. It is automatically run:
    • every 12 hours per scheduled task

    • when datacenters are added or removed

    • when virtual machine host servers are added or removed

  • The license cache is cleared updated each time vm.license.udpate.task is run.
    • If a vCenter server for a datacenter is unreachable during the scan, the licenses managed by that vCenter will be missing from the cache until the vCenter can be reached on a subsequent scan.

  • This task ignores licenses that are not associated with NETLAB+ servers.

Returns

A dictionary with the following properties.

Return type

dict

Properties

servers_tried

The number of vCenter servers that contact was attempted.

servers_reporting

The number of vCenter servers that responded with license information.

license_count

The number of licenses that were found and cached.

licenses

Information about each licence (see below).

earliest_expiration

The earliest license expiration at time of call. Can be None.

License Properties

vdc_id

NETLAB+ datacenter identifier associated with license.

vh_id

If not None, the NETLAB+ vm host identifier associated with license.

vl_type

License type. netlab.enums.VirtualMachineLicenseType

vl_server

Hostname or IP address of the server as registered in vCenter.

vl_product

Licensed product name.

vl_key

Licnese key.

vl_units

Number of units licensed (i.e. processors) depending on server type.

vl_expiration

The expiration date and time of the license (UTC) or None if no expiration.

vl_last_udpate

The date and time this license was last queried and cached.

vm_snapshot_add(*, vm_id=None, pc_id=None, snapshot_name, dump_memory=False, sync=False, description=None, **kwargs)

Method to call a task to add snapshot to virtual machine.

Parameters
  • vm_id (int) – Virtual datacenter identifier.

  • pc_id (int) – Remote pc identifier.

  • snapshot_name (str) – Name of snapshot to take.

  • dump_memory (bool) – Dump memory files.

  • sync (bool) – Sync files.

  • description (str) – Snapshot description.

Returns

The snapshot completed successfully.

Return type

‘OK’

vm_snapshot_edit(*, vm_id=None, pc_id=None, snapshot_id=None, new_snapshot_name=None, new_snapshot_description=None, **kwargs)

Method to call a task to edit a snapshot.

Parameters
  • vm_id (int) – Virtual datacenter identifier.

  • pc_id (int) – Remote pc identifier.

  • snapshot_id (int) – Snapshot identifier.

  • new_snapshot_name (int) – New name of snapshot to take.

  • new_snapshot_description (str) – New description of snapshot.

Returns

The edit completed successfully.

Return type

‘OK’

vm_snapshot_get_list(*, vm_id=None, pc_id=None, **kwargs)

Method to call a task to retrieve a list of snapshots.

Parameters
  • vm_id (int) – Virtual datacenter identifier.

  • pc_id (int) – Remote pc identifier.

Returns

Returns a dict with the following properties:

Return type

dict

Properties

current_snapshot

The current snapshot. See Snapshot properties for more info.

snapshot_list

A list of all snapshots. See Snapshot properties for more info.

Snapshot properties

power_state

The state of the snapshot. PowerState

name

The snapshot name.

description

The snapshot description.

parent_id

The id of the snapshot parent.

id

The snapshot id.

mo_ref

The unique identifier of the managed object in vSphere.

vm_snapshot_get_tree(*, vm_id=None, pc_id=None, **kwargs)

Method to call a task to retrieve snapshot tree.

Parameters
  • vm_id (int) – Virtual datacenter identifier.

  • pc_id (int) – Remote pc identifier.

Returns

Returns a dict with the following properties:

Return type

dict

Properties

current_snapshot

The current snapshot. See Snapshot properties for more info.

snapshot_list

A list of all snapshots. See Snapshot properties for more info.

Snapshot properties

power_state

The state of the snapshot. PowerState

name

The snapshot name.

description

The snapshot description.

id

The snapshot id.

mo_ref

The unique identifier of the managed object in vSphere.

vm_snapshot_remove(*, vm_id=None, pc_id=None, snapshot_name=None, snapshot_id=None, remove_children=None, remove_all_snapshots=None, **kwargs)

Method to call a task to remove snapshot from virtual machine.

Parameters
  • vm_id (int) – Virtual datacenter identifier.

  • pc_id (int) – Remote pc identifier.

  • snapshot_name (str) – Name of snapshot to take.

  • snapshot_id (int) – Snapshot identifier.

  • remove_children (bool) – Remove children snapshots.

  • remove_all_snapshots (bool) – Remove all snapshots of virtual machine.

Returns

The removal completed successfully.

Return type

‘OK’

vm_snapshot_revert(*, vm_id=None, pc_id=None, snapshot_name=None, snapshot_id=None, **kwargs)

Method to call a task to revert to snapshot from virtual machine.

Parameters
  • vm_id (int) – Virtual datacenter identifier.

  • pc_id (int) – Remote pc identifier.

  • snapshot_name (str) – Name of snapshot to take.

  • snapshot_id (int) – Snapshot identifier.

Returns

The revert completed successfully.

Return type

‘OK’