Python Access to vSphere APIs

For the Python developer, this chapter shows how to install the Python SDKs and run example programs against vSphere APIs.

VMware vSphere offers two important programming interfaces: (1) Web Services API in the vSphere Management SDK, which is SOAP based and the integration point for

pyvmomi

. (2) vSphere Automation API, which is primarily REST based but has additional bindings for Python and Java. SOAP interfaces were first used decades ago to implement the vSphere Client UI. The Automation API is newer with additional features and some duplication. Code samples in this chapter use them together.

Prerequisite: Python 3.8 or higher. Recent Linux distributions and MacOS include higher Python versions. The command name is probably

python3

but can be aliased.

Installing the Python SDKs for vSphere

Python access to vSphere APIs is most convenient with the

pyvmomi

library. To install

pyvmomi

If not already installed, get the Python installer

pip

. On Ubuntu systems, the package is named

python-pip

. On MacOS there are several alternatives; one is to download and run

get-pip.py

. In any case, add

pip

's location to your PATH.

Update

pip

and setup tools, then install (or upgrade)

pyvmomi

with the

pip

command.

pip install --upgrade pip
pip install --upgrade setuptools
pip install --upgrade pyvmomi

Install the vSphere Automation SDK for Python from its Github archive. The expression

git+https

means to use secure HTTP for downloading the Github install.

pip install --upgrade git+https://github.com/vmware/vsphere-automation-sdk-python.git

You could also download the vSphere Automation SDK for Python (as a ZIP file) from its https://developer.broadcom.com/sdks landing page. Install instructions, including for a secure air-gapped environment, are available in the Quick Start Guide section of README.md on the http://github.com/vmware/vsphere-automation-sdk-python web page.

Now you are ready to run the code samples below. Copy and paste the code into a file and run the

python

python3

command on the file. You can run one at a time, or all three copy-and-pastes together at once.

Basic Authentication Using pyvmomi

The

pyvmomi

SDK simplifies code for connecting to the VIM endpoint by using a

SmartConnect

function that accepts basic user credentials, opens a session with the server, and returns the

ServiceInstance

object.

ServiceInstance

contains references to specific managed objects needed to use VIM API features.

The

vsphere_client

object contains interface stubs for all Automation API endpoints. This code excerpt shows a function that connects to both the VIM endpoint and the Automation API endpoint and returns both the

vsphere_client

object and the

ServiceInstance

object.

hostname = 'vc1.example.com'
username = 'administrator@vsphere.local'
password = 'TooSecret2C!'

from pyVim.connect import SmartConnect
from vmware.vapi.vsphere.client import create_vsphere_client, VsphereClient
import requests, urllib3
import sys
from pyVmomi import vim

def connect(host: str, user: str, pwd: str, insecure: bool) -> tuple[VsphereClient, vim.ServiceInstance]:
    session = requests.session()
    if insecure:
        session.verify = False
        urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
    print('Creating an Automation API session.')
    vsphere_client = create_vsphere_client(host, user, pwd, session=session)
    print('Creating a VIM/SOAP session.')
    si = SmartConnect(host=host, 
                      user=user,
                      pwd=pwd,
                      disableSslCertValidation=insecure)
    return vsphere_client, si

(vsphere_client, service_instance) = connect(hostname,
                                             username,
                                             password,
                                             insecure=True)

At this point, your session is established and the session ID is stored in a cookie that will be passed along with future requests.

Creating a Hello Folder with the VIM API Using pyvmomi

The

ServiceContent

object contains a reference to the root folder of the managed object hierarchy. You can invoke the

CreateFolder()

method on the

rootFolder

object to create a subfolder named

Hello Folder

...
print('Using VIM to create Hello Folder.')
try:
  hello_folder = service_instance.content.rootFolder.CreateFolder('Hello Folder')
except vim.fault.DuplicateName as oops:
  print(oops)
  print('Please delete folder from Inventory and try again.\n')
  sys.exit(1)
print('Hello Folder MOref: ', hello_folder, type(hello_folder), '\n')

# Convert object IDs from VIM to VAPI.
def vim_moref_to_moid(moref):
  return moref._GetMoId()
...

Tagging the Folder with Automation API for Python

To tag a folder, start by creating a tag category, then create a tag in that category, and finally attach the tag to the folder.

...
# Interface factory object:
stub_config = vsphere_client._stub_config

print('Automation API creating a tag category.')
from com.vmware.vapi.std_client import DynamicID
from com.vmware.cis.tagging_client import Category, CategoryModel, Tag, TagAssociation
import com.vmware.vapi.std.errors_client
category_id = None
tag_id = None
category_stub = Category(stub_config)
tc_create_spec = category_stub.CreateSpec(name='hello_category',
   description = 'example of tagging category from pyvmomi',
   cardinality = CategoryModel.Cardinality.MULTIPLE,
   associable_types = set(['Folder']))
try:
  category_id = category_stub.create(tc_create_spec)
except com.vmware.vapi.std.errors_client.AlreadyExists as oops:
  print(oops)
  print('Please delete category from Tags & Custom Attributes and try again.\n')
  sys.exit(1)
print('New category created: ', category_id)

print('VAPI creating a tag in new category.')
tag_stub = Tag(stub_config)
tag_create_spec = tag_stub.CreateSpec(name='hello_tag',
description= 'example of a tag',
category_id=category_id)
try:
  tag_id = tag_stub.create(tag_create_spec)
except errors_client.NotFound as oops:
  print('Exception: \n', oops, '\n')
  sys.exit(1)
print('New tag created: ', tag_id)

print('VAPI creating association of tag with Hello Folder.')
dynamic_id = DynamicID(type='Folder',
 id=vim_moref_to_moid(hello_folder))
tag_association_stub = TagAssociation(stub_config)
tag_association_stub.attach(tag_id=tag_id,
 object_id=dynamic_id) 
print('Tag attached to folder.')

The following image shows the Hello Folder and Category as it looks in the vSphere Client UI.