First steps with psphere

This document is meant to give a tutorial-like overview of the main psphere objects and the common tasks that psphere is used for.

The green arrows designate “more info” links leading to more detailed sections about the described task.

Vendor documentation

VMware provides very good documentation for the VMware vSphere API. It is suggested that you at least read the introductory documents to gain a conceptual understanding of the API.

Throughout this documentation there are links to the API reference documentation.

See useful references.

The Client object

The Client object is the entry point into psphere. Through it you can login to a vSphere server and obtain Python objects representing managed objects. You can then access information about and execute methods on those objects.

Read more about the Vim attributes and methods.

Hello World in psphere

Not quite, but logging into the server and printing the current time is close:

>>> from psphere.client import Client
>>> client = Client("your.esxserver.com", "Administrator", "strongpass")
>>> servertime = client.si.CurrentTime()
>>> print(servertime)
2010-09-04 18:35:12.062575
>>> client.logout()

General programming pattern

Create a new Client:

>>> from psphere.client import Client
>>> client = Client("your.esxserver.com", "Administrator", "strongpass")

...check out the rootFolder of the content attribute, it’s a Python object:

>>> client.si.content.rootFolder.__class__
<class 'psphere.managedobjects.Folder'>

...access properties of it:

>>> print(client.si.content.rootFolder.name)
Datacenters

...invoke a method:

>>> new_folder = client.si.content.rootFolder.CreateFolder(name="New")
>>> print(new_folder.name)
New
>>> task = new_folder.Destroy_Task()
>>> print(task.info.state)
success

...log out of the server:

>>> client.logout()

Finding a ManagedEntity

Managed Object’s which extend the ManagedEntity class are the most commonly used objects in the vSphere API. These include Managed Object’s such as HostSystem’s and VirtualMachine’s.

psphere makes it easy to find Managed Entity’s by providing a get() classmethod to find them:

>>> from psphere.client import Client
>>> from psphere.managedobjects import VirtualMachine
>>> client = Client("your.esxserver.com", "Administrator", "strongpass")
>>> vm = VirtualMachine.get(client, name="genesis")
>>> vm.__class__
<class 'psphere.managedobjects.VirtualMachine'>
>>> vm.name
bennevis
>>> vm.summary.guest.ipAddress
10.183.11.85
>>> vm.config.hardware.memoryMB
4096

There is also the all() method to get all entities of that type:

>>> vms = VirtualMachine.all(client)

Lazy loading of properties and pre-loading properties

At this point we have to delve into a more complicated aspect of vSphere and how psphere handles it. You do not need to worry about this, psphere will just work for you – albeit inefficiently in some cases.

The vSphere SDK architecture provides abstract “views” of server side objects, some of these objects can be quite substantial, both in size and server resources required to collect them.

If you retrieve substantial objects then your scripts will be slow and you will generate load on your vSphere server.

psphere deals with this by lazily loading objects on access. In most cases this is fine, but you can achieve substantial speed-ups – especially for lists of managed objects – by pre-loading objects you know that you are going to access.

For example, a HostSystem has a “vm” property which is a list of VirtualMachine objects on that host. If you know you are going to loop over all those VM’s and print their name, you can preload the name property using the preload method:

>>> hs = HostSystem.get(client, name="myhost")
>>> hs.preload("vm", properties=["name"])
>>> for vm in hs.vm:
>>>     print(vm.name)
>>> ...

Caching

Once lazily loaded or pre-loaded, attributes will be cached for a pre-defined time (5 minutes, which is not configurable but will be in the next release).

To update the cache for a specific property of an object, use the update() method with the properties parameter:

>>> hs.update(properties=["name"])

To update the cache for all cached properties of an object, use the update() method with no parameters:

>>> hs.update()

To clear the property cache for an object, use the flush_cache() method:

>>> hs.flush_cache()