Contents¶

What is vmjuggler¶

vmjuggler provides the simple high level API to VMWare’s SDK.

It built around pyvmomi library with aim to simplify interaction to VMWare VCenter and it’s managed objects for DevOps crowd and those who don’t want to plunge deeply to object’s relations. At the same time ability to perform actions on low level was preserved.

Installation¶

pip install vmjuggler

Manual installation¶

Install following python packages
- pyvmomi
- future-fstrings if used Python version < 3.5
Download latest vmjuuggler from https://github.com/shurkam/vmjuggler
Unpack and run python setup.py install

Getting started¶

from vmjuggler import VCenter

# Create instance of VCenter and connect to VCenter
vc = VCenter('10.0.0.1', 'user', 'super_secret_password')
vc.return_single(True)
vc.connect()

# Find VM and print out it's power state
vm = vc.get_vm(name='My_Linux_VM')
if vm:
    print(f'{vm.name} | {vm.state}')

# Close connection to VCenter
vc.disconnect()

Note

To use nice Python F-string feature with Python < 3.5 the future-fstrings package should be installed and the following line should be the first line in file after shebang.

# -*- coding: future_fstrings -*-

Examples¶

This sections contains examples of common VM operations.

Get list of VMs¶

from vmjuggler import VCenter

args = {'host': '10.0.0.1',  # VCenter IP or hostname
        'user': 'foo',       # VCenter username
        'pwd':  'foo_pwd'}   # Password

vc = VCenter(args['host'], args['user'], args['pwd'])
vc.connect()

vms = vc.get_vm(get_all=True)
for vm in vms:
    print(f'{vm.name} | {vm.state}')

vc.disconnect()

Power on VM¶

from vmjuggler import VCenter

args = {'host': '10.0.0.1',  # VCenter IP or hostname
        'user': 'foo',       # VCenter username
        'pwd':  'foo_pwd'}   # Password

vm_name = 'BuildBox01'       # VM name

vc = VCenter(args['host'], args['user'], args['pwd'])
vc.set_return_single(True)
vc.connect()

vm = vc.get_vm(name=vm_name)
if vm:
    vm.power_on()

vc.disconnect()

Power on all VMs¶

from vmjuggler import VCenter

args = {'host': '10.0.0.1',  # VCenter IP or hostname
        'user': 'foo',       # VCenter username
        'pwd':  'foo_pwd'}   # Password

vc = VCenter(args['host'], args['user'], args['pwd'])
vc.connect()

vms = vc.get_vm(get_all=True)
for vm in vms:
    vm.power_on()

vc.disconnect()

Revert VM to snapshot¶

from vmjuggler import VCenter

args = {'host': '10.0.0.1',    # VCenter IP or hostname
        'user': 'admin',       # VCenter username
        'pwd':  'admin_pwd'}   # Password

vm_name = 'TestBox01'          # VM name
snapshot_name = 'clean_state'  # Snapshot name

vc = VCenter(args['host'], args['user'], args['pwd'])
vc.set_return_single(True)
vc.connect()

vm = vc.get_vm(name=vm_name)
if vm:
    vm.revert(snapshot_name)

vc.disconnect()

Objects reference¶

Here it is provided structure of all vmjuggler objects

vmjuggler.VCenter¶

class vmjuggler.VCenter(address, username, password)¶

VCenter object

Parameters:	address (str) – VCenter address or IP. username (str) – User name. password (str) – User password.

connect(exit_on_fault=True)¶

Connect to VCenter.

Currently doesn’t use certificate, as it not used in the most installations or self-signed used.

Parameters:	exit_on_fault (bool) – Perform exit on connection fault if True, otherwise returns None.
Returns:	VMWare ServiceInstance object or None in case of connection fault.

create_vm()¶

Create new VM.

Returns:

disconnect()¶: Close connection with VCenter.

get_all(name=None, root=None, get_all=False, raw=False)¶

Get the object by name or list of all objects.

Parameters:	name (str) – Object name or list of names. root (str) – The folder to start looking from. get_all (bool) – The ‘name’ ignored and all objects of specified types are returned if set to True. raw (bool) – The raw objects will be returned if set otherwise ‘vmjuggler.BaseVCObject’ type.
Returns:	List of objects.

get_datastore(name=None, root=None, get_all=False, raw=False)¶

Get the Datastore by name or list of all Datastores.

Parameters:	name (str) – Datastore name or list of names. root (str) – The folder to start looking from. get_all (bool) – The ‘name’ ignored and all objects of specified types are returned if set to True. raw (bool) – The raw objects will be returned if set otherwise ‘vmjuggler.Datastore’ type.
Returns:	List of objects.

get_dc(name=None, root=None, get_all=False, raw=False)¶

Get the Datacenter by name or list of all DCs.

Parameters:	name (str) – DC name or list of names. root (str) – The folder to start looking from. get_all (bool) – The ‘name’ ignored and all objects of specified types are returned if set to True. raw (bool) – The raw objects will be returned if set otherwise ‘vmjuggler.DataCenter’ type.
Returns:	List of objects.

get_folder(name=None, root=None, get_all=False, raw=False)¶

Get the Folder by name or list of all Folders.

Parameters:	name (str) – Folder name or list of names. root (str) – The folder to start looking from. get_all (bool) – The ‘name’ ignored and all objects of specified types are returned if set to True. raw (bool) – The raw objects will be returned if set otherwise ‘vmjuggler.Folder’ type.
Returns:	List of objects.

get_host(name=None, root=None, get_all=False, raw=False)¶

Get the Host by name or list of all Hosts.

Parameters:	name (str) – DC name or list of names. root (str) – The folder to start looking from. get_all (bool) – The ‘name’ ignored and all objects of specified types are returned if set to True. raw (bool) – The raw objects will be returned if set otherwise ‘vmjuggler.Host’ type.
Returns:	List of objects.

get_network(name=None, root=None, get_all=False, raw=False)¶

Get the Network by name or list of all Networks.

Parameters:	name (str) – Network name or list of names. root (str) – The folder to start looking from. get_all (bool) – The ‘name’ ignored and all objects of specified types are returned if set to True. raw (bool) – The raw objects will be returned if set otherwise ‘vmjuggler.Network’ type.
Returns:	List of objects.

get_vapp(name=None, root=None, get_all=False, raw=False)¶

Get the VApp by name or list of all VApps.

Parameters:	name (str) – VApp name or list of names. root (str) – The folder to start looking from. get_all (bool) – The ‘name’ ignored and all objects of specified types are returned if set to True. raw (bool) – The raw objects will be returned if set otherwise ‘vmjuggler.VApp’ type.
Returns:	List of objects.

get_vm(name=None, root=None, get_all=False, raw=False)¶

Get the VM by name or list of all VMs.

Parameters:	name (str) – VM name or list of names. root (str) – The folder to start looking from. get_all (bool) – The ‘name’ ignored and all objects of specified types are returned if set to True. raw (bool) – The raw objects will be returned if set otherwise ‘vmjuggler.VirtualMachine’ type.
Returns:	List of objects.

raw_global¶

Return raw_global parameter.

Returns:	Boolean or None.

return_single¶

Return return_single parameter.

Returns:

set_raw_global(value)¶

Set raw_global parameter.

The raw_globals defines type of objects to be returned by get_* methods.

True - always return raw VMWare Managed object.

False - always return extended vmjuggler.* object.

None - return type defined independently by ‘raw’ parameter of the get_* methods.

Parameters:	value (bool) – True/False/None.
Returns:	set value.

set_return_single(value)¶

Set return_single parameter

If set, output of get_* methods changes as follow:

If returning list of objects has the only one element it will be returned as single object, not as a list.

If returning list is empty, the None will be returned.

The feature is implemented by using decorator @Decor.single_object.

Parameters:	value (bool) –
Returns:	set value.

vmjuggler.VirtualMachine¶

class vmjuggler.VirtualMachine(vc_object)¶

VirtualMachine object

Wrapper for vim.VirtualMachine

Parameters:	vc_object (vim.VirtualMachine) – Raw VMWare ManagedObject

create_snap(name, description=None, memory=True, quiesce=False)¶

Create snapshot.

Parameters:	name (str) – Snapshot name. description (str) – Snapshot description. memory (bool) – If set, the memory will be included to snapshot. quiesce (bool) – If set, the quiesce snapshot will be created.
Returns:	True on success, otherwise False

get_snap(name=None, current=False, get_all=False, raw=False)¶

Return list of snapshot objects.

Parameters:	name (str) – Snapshot name. current (bool) – If set the ‘name’ is ignored and current snapshot returned. get_all (bool) – If set the ‘name’ and ‘current’ are ignored and all VM snapshots returned. raw (bool) – If set the raw VMWare snapshot object returned.
Returns:	List of vmjuggler.VMSnapshot objects.

list_snaps()¶

Prints out all VM snapshots.

Returns:	n/a

name¶: Object’s name. Populated once instance created.

power_off()¶

Power Off VM.

Returns:	True on success, otherwise False.

power_on()¶

Power On VM.

Returns:	True on success, otherwise False.

raw_obj¶: Raw object. Populated once instance created.

reboot()¶

Reboot VM.

Returns:	True on success, otherwise False.

remove_snap(name=None, current=False, remove_all=False, remove_children=False, consolidate=False)¶

Remove snapshot or all snapshots.

Parameters:

name (str) – Snapshot name.
current (bool) – If set, the current snapshot will be deleted, “name” parameter is ignored.
remove_all (bool) – If set, all snapshots will be removed, “name” and “current” parameters are ignored.
remove_children (bool) – If set, children snapshots will be removed along with parent.
consolidate (bool) – If set, the consolidation will be performed.

Returns:

True on success, False if any of snapshots failed to be removed.

reset()¶

Reset VM power.

Returns:	True on success, otherwise False.

revert(snapshot_name=None, current=False)¶

Revert to snapshot.

Parameters:	snapshot_name (str) – Snapshot name. current (bool) – Revert to current snapshot if set. The ‘name’ is ignored.
Returns:	True on success, otherwise False.

shutdown()¶

Shutdown OS on VM.

Returns:	True on success, otherwise False.

state¶

VM power state.

Returns:	str: “poweredOff”, “poweredOn” or “suspended”

suspend()¶

Suspend VM.

Returns:	True on success, otherwise False.

terminate()¶

Immediately terminate VM.

Returns:	True on success, otherwise False.

vmjuggler.Datacenter¶

class vmjuggler.Datacenter(vc_object)¶

Datacenter object

Wrapper for vim.Datacenter

Parameters:	vc_object (vim.Datacenjter) – Raw VMWare ManagedObject

name¶: Object’s name. Populated once instance created.

raw_obj¶: Raw object. Populated once instance created.

vmjuggler.Folder¶

class vmjuggler.Folder(vc_object)¶

Folder object

Wrapper for vim.Folder

Parameters:	vc_object (vim.Folder) – Raw VMWare ManagedObject

name¶: Object’s name. Populated once instance created.

raw_obj¶: Raw object. Populated once instance created.

vmjuggler.VApp¶

class vmjuggler.VApp(vc_object)¶

VApp object

Wrapper for vim.VApp

Parameters:	vc_object (vim.VApp) – Raw VMWare ManagedObject

name¶: Object’s name. Populated once instance created.

raw_obj¶: Raw object. Populated once instance created.

vmjuggler.Network¶

class vmjuggler.Network(vc_object)¶

Network object

Wrapper for vim.Network

Parameters:	vc_object (vim.Network) – Raw VMWare ManagedObject

name¶: Object’s name. Populated once instance created.

raw_obj¶: Raw object. Populated once instance created.

vmjuggler.Datastore¶

class vmjuggler.Datastore(vc_object)¶

Datastore object

Wrapper for vim.Datastore

Parameters:	vc_object (vim.Datastore) – Raw VMWare ManagedObject

name¶: Object’s name. Populated once instance created.

raw_obj¶: Raw object. Populated once instance created.

vmjuggler.Host¶

class vmjuggler.Host(vc_object)¶

Host object

Wrapper for vim.Host

Parameters:	vc_object (vim.Host) – Raw VMWare ManagedObject

name¶: Object’s name. Populated once instance created.

raw_obj¶: Raw object. Populated once instance created.

vmjuggler.VMSnapshot¶

class vmjuggler.VMSnapshot(vc_object)¶

VM Snapshot object.

Parameters:	vc_object – SnapshotList object.

info()¶

Print out snapshot info.

Returns:	n/a

name¶: Object’s name. Populated once instance created.

raw_obj¶: Raw object. Populated once instance created.

remove(remove_children=False, consolidate=False)¶

Remove snapshot.

Parameters:	remove_children (bool) – If set, the children snapshots will be removed too. consolidate (bool) – If set, disk images will be consolidated after snapshot removed.
Returns:	True on success, otherwise False

rename(name=None, description=None)¶

Rename snapshot or change description.

Parameters:	name (str) – New snapshot name. description (str) – New Description.
Returns:	True on success, otherwise False

revert(suppress_power_on=False)¶

Revert snapshot.

Parameters:	suppress_power_on (bool) – If set, VM will not be powered on in case snapshot was created in VM powered on state.
Returns:	True on success, otherwise False