In December 2013, VMware made an christmas gift to the community by releasing pyVmomi. pyVmomi is a SDK that allows you to manage VMware ESXi and vCenter using Python and the VMware vSphere API. Nearly 18 months are past since then and pyVmomi has developed over time.
I’ve started to play around with Python, and I’ve written about the reasons in one of my last blog posts (Hey infrastructure guy, you should learn Python!).
How to get pyVmomi?
You can install the official release of pyVmomi using pip (pip installs packages, a recursive acronym).
pip3 install --upgrade pyvmomi
The latest version is available on GitHub. To get the latest version, use
python setup.py develop
python setup.py install
That you can fetch the latest version from GitHub is pretty cool and shows a big benefit: The community can contribute to pyVmomi and it’s more frequently updated. A huge benefit in regard of code quality and features.
What Python releases are support?
The latest information about supported Python releases can be found on the GitHub page of the project.
- pyVmomi 188.8.131.526.4 and later support 2.7, 3.3 and 3.4
- pyVmomi 6.0.0 and later support 2.7, 3.3 and 3.4
- pyVmomi 5.5.0-2014.1 and 5.5.0-2014.1.1 support Python 2.6, 2.7, 3.3 and 3.4
- pyVmomi 5.5.0 and below support Python 2.6 and 2.7
Interesting fact: pyVmomi version numbers correlate with vSphere releases. pyVmomi 6.0.0 was released with the GA of VMware vSphere 6. pyVmomi supports the corresponding vSphere release and the previous four vSphere releases.
I’m using Python 3 for my examples. I wouldn’t recommend to start with Python 2 these days.
pyVmomi allows you to manage VMware ESXi and vCenter using Python and the VMware vSphere API. Because of this, the VMware vSphere API Reference Documentation will be your best friend.
First of all, you need a connection to the API. To connect to the vSphere API, we have to import and use the module pyVim, more precise, the pyVim.connect module and the SmartConnect function. pyVim.connect is used for the connection handling (creation, deletion…) to the Virtualization Management Object Management Infrastructure (VMOMI). pyVim is part of pyVmomi and it’s installed automatically.
from pyVim.connect import SmartConnect c = SmartConnect(host="192.168.20.1", user="root", pwd='Passw0rd')
SmartConnect accepts various parameters, but for the beginning it’s sufficient to use three of them: host, user and pwd. You can use “help(SmartConnect)” to get information about the SmartConnect function. “c” is the object (pyVmomi.VmomiSupport.vim.ServiceInstance) which we will use later.
A connection itself is useless. But how can we explore the API? Python doesn’t support typing, so it can be difficult to “explore” an API. That’s why the VMware vSphere API Reference Documentation and the Managed Object Browser (MOB) will be your best friends. The MOB is a web-based interface and represents the vSphere API. It allows you to navigate through the API. Any changes you make through the MOB, by invoking methods, take effect and change the config or will give you an output.
|Important note: If you are using VMware vSphere 6 (ESXi 6.0 and vCenter 6.0), you have to enable the MOB. The MOB is disabled by default. Check VMware KB2108405 (The Managed Object Browser is disabled by default in vSphere 6.0) for more details.|
Open a browser and open https://ip-or-fqdn/mob. You can use the IP address or the FQDN of an ESXi host or a vCenter Server (Appliance). I use a standalone ESXi 5.5 host in this example.
Our first code
Let’s try something easy. I’ve framed a method in the screenshot above. We will use this method now.
from pyVim.connect import SmartConnect c = SmartConnect(host="192.168.20.1", user="root", pwd='Passw0rd') print(c.CurrentTime())
This code will connect to the vSphere API, invoke the method “CurrentTime()” and prints the result. What happens if we execute our first lines of Python code? We will get an error…
self._sslobj.do_handshake() ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:645)
Python checks SSL certificates in strict mode. Because of this, untrusted certificates will cause trouble. This applies to Python 3, as well as to Python >= 2.7.9 (PEP 0466). Most people use untrusted certificates. To deal with this, we have to create a context for our HTTP connection. This context can be used by the SmartConnect function. To create a context, we have to import the ssl module of Python.
from pyVim.connect import SmartConnect import ssl s = ssl.SSLContext(ssl.PROTOCOL_TLSv1) s.verify_mode = ssl.CERT_NONE c = SmartConnect(host="192.168.20.1", user="root", pwd='Passw0rd', sslContext=s) print(c.CurrentTime())
“s” is the new object (ssl.SSLContext) we will use and the parameter “sslContext=s” will told SmartConnect to use this object.
Save this code into a file (I called it pyvmomitest.py in my example). Navigate to the folder, open a Python REPL and import the file you’ve saved (module) a moment ago.
C:\Users\p.terlisten\Documents\Development\Python\Playground>python Python 3.5.1 (v3.5.1:37a07cee5969, Dec 6 2015, 01:38:48) [MSC v.1900 32 bit (Intel)] on win32 Type "help", "copyright", "credits" or "license" for more information. >>> import pyvmomitest 2016-05-20 12:29:23.837049+00:00 >>>
Hurray! We used the vSphere API to get the current date and time (CET).
But what if we have deployed valid certificates? And what about housekeeping? We have connected, but we haven’t disconnected from the API? We can use a try-except block to handle this. And because we are nice, we import also the function “Disconnect” from pyVim.connect to disconnect from the vSphere API at the end.
from pyVim.connect import SmartConnect, Disconnect import ssl s = ssl.SSLContext(ssl.PROTOCOL_TLSv1) s.verify_mode = ssl.CERT_NONE try: c = SmartConnect(host="192.168.20.1", user="root", pwd='Passw0rd') print('Valid certificate') except: c = SmartConnect(host="192.168.20.1", user="root", pwd='Passw0rd', sslContext=s) print('Invalid or untrusted certificate') print(c.CurrentTime()) Disconnect(c)
With this code, we should get the following output.
C:\Users\p.terlisten\Documents\Development\Python\Playground>python Python 3.5.1 (v3.5.1:37a07cee5969, Dec 6 2015, 01:38:48) [MSC v.1900 32 bit (Intel)] on win32 Type "help", "copyright", "credits" or "license" for more information. >>> import pyvmomitest Invalid or untrusted certificate 2016-05-20 12:36:28.707876+00:00 >>>
Okay, the vSphere API wasn’t designed to retrieve the current date and time. Let’s look at something more useful. This script will give us the names of all VMs in the datacenter.
from pyVim.connect import SmartConnect, Disconnect import ssl s = ssl.SSLContext(ssl.PROTOCOL_TLSv1) s.verify_mode = ssl.CERT_NONE try: c = SmartConnect(host="192.168.20.1", user="root", pwd='Passw0rd') print('Valid certificate') except: c = SmartConnect(host="192.168.20.1", user="root", pwd='Passw0rd', sslContext=s) print('Invalid or untrusted certificate') datacenter = c.content.rootFolder.childEntity vms = datacenter.vmFolder.childEntity for i in vms: print(i.name) Disconnect(c)
Let’s take this statement and look at everything after the “c”. We will use the MOB to navigate through the API. This will help you to understand, how the Python code and the structure of the vSphere API correlate.
datacenter = c.content.rootFolder.childEntity
Open the MOB. You will easily find the property “content”.
Click on “content” and search for the property “rootFolder”.
Click on the value “ha-folder-root.” The property “childEntity” is an ManagedObjectReference (MOR) and references to all datacenters (the counting starts at 0) known to the ESXi or vCenter. The value “childEntity” will give us the first datacenter.
If we have the datacenter, the way to get the names of the VMs is the same. You can use the MOB, to verify this.
vms = datacenter.vmFolder.childEntity
Click on the value “ha-datacenter”. At the bottom of the list, you will find the property “vmFolder”.
Click on the value “ha-folder-vm”.
The MOR “childEntity” references to two VMs. Click on one of the IDs.
The property “name” includes the name of the VM. Because of this, we can use a simple
for i in vms: print(i.name)
to get the name for each VM.
This was only a short introduction into pyVmomi. You should be now able to install pyVmomi, make a connection to the vSphere API and retrieve some basic stuff.
Every day I discover something new. It’s important to understand how the vSphere API works. Play with pyVmomi and with the vSphere API. It looks harder as it is.
btw: There is a Hands-on-Lab available “HOL-SDC-1622 VMware Development Tools and SDKs“. Check it out!
- Why you should change your KRBTGT password prior disabling RC4 - July 28, 2022
- Use app-only authentication with the Microsoft Graph PowerShell SDK - July 22, 2022
- Getting started with the Microsoft Graph PowerShell SDK - July 21, 2022
This is very useful and nicely explained. Thanks a lot.
This is very useful and nicely explained. Thanks a lot.
HOL lab link does not work
Hello Patrick, this is a very helpful post to get up to speed with Python and the vSphere SDK. Thanks a lot and keep up the good work.
Thanks for the feedback Paul! :)
This is a very helpful article for new learners like me, thank you :)
Really Good Explanation ..
Can you please help me how to proceed further with the same.
I need more inputs with pyVmomi , wana learn it badly .
Very useful for me, as a beginner
Hi, How can I get host of particular VM??
Thanks, this has helped me get started.
Clearly explained Even a fresher (new learner can understand)
Hello Patrick, I have a question about pyvmomi.
How do you see the composition of variables inside the “childEntity” ?
pyvmomi’s github page doesn’t seem to say anything about this.