Use vCenter APIs

Cloud Management Platform (CMP) already manages the resources in a vCenter, but when you need something it does not expose, both vCenter APIs are reachable from a resource handler without setting up your own connection or credentials.

vSphere Web Services API

The vSphere Web Services API is stable, changes infrequently, and keeps backward compatibility with earlier versions. It is based on SOAP and XML, which makes it complex to call directly.

CMP ships the pyvmomi Python bindings to mitigate the complexity. They are not especially Pythonic and take more effort than bindings such as Boto3, but they are supported by CMP.

See VMware’s vSphere Web Services API reference.

ServiceInstance: the root of the vCenter and ESXi API

ServiceInstance is the vCenter ManagedObject that serves as the singleton root of the API inventory on vSphere and ESXi servers.

1. Get the singleton from a connected vCenter server. CMP exposes it through the VsphereResourceHandler model.

   # Assuming the variable rh is a VsphereResourceHandler
   wrapper = rh.get_api_wrapper()
   si = wrapper._get_connection()
   

2. With a reference to the ServiceInstance for your resource handler, call the API on that vCenter directly. This example retrieves a virtual machine’s summary.

   RH_ID = 1          # The ID for a vSphere ResourceHandler
   SERVER_ID = 1000   # A Server ID for a server in the above ResourceHandler
   
   server = Server.objects.get(id=SERVER_ID)
   rh = VsphereResourceHandler.objects.get(id=RH_ID)
   wrapper = rh.get_api_wrapper()
   si = wrapper._get_connection()
   index = si.content.searchIndex
   
   vm = index.FindByUuid(
     uuid=server.resource_handler_svr_id,
     vmSearch=True)
   
   print(vm.summary if vm else "VM Not Found.")
   

The ServiceInstance gives you a ServiceContent object, which exposes the vCenter managed objects used to retrieve content in various ways. The example uses the SearchIndex singleton and its FindByUuid method, passing the UUID held on the CMP server record along with a flag indicating to search for a virtual machine.

Common pyvmomi gotchas:

• The capitalization is not conventional Python. Method names are CamelCase because the bindings are generated from the vSphere Web Services API.
• Calls and properties are dispatched dynamically, so an IDE cannot autocomplete them. The API reference is the way to find what is available.

vSphere Automation API

The vSphere Automation API, added in vSphere 6.5, is a REST API that is easier to work with than the Web Services API and more consistent with other vendors’ APIs.

See VMware’s vSphere Automation API reference.

Use the Automation API with a vCenter resource handler

CMP provides resourcehandlers.vmware.vapi_wrapper.VsphereRESTClient for calling this API with an existing vCenter resource handler. Build one from the handler’s own connection details.

client = VsphereRESTClient(
    host=rh.ip,
    port=rh.port,
    username=rh.serviceaccount,
    password=rh.servicepasswd,
    protocol="https",
    ssl_verification=rh.get_ssl_verification()
)

The client exposes some methods of its own, and all other operations are performed via HTTP POST or GET, depending on the API function. This example uses POST to list the objects a given vCenter tag is applied to.

# The following ID corresponds to an existing tag in our vCenter
TAG_ID = "urn:vmomi:InventoryServiceTag:0c43707b-39bd-4f69-8e16-4a2e7bff3755:GLOBAL"

client = VsphereRESTClient(
    host=rh.ip,
    port=rh.port,
    username=rh.serviceaccount,
    password=rh.servicepasswd,
    protocol='https',
    ssl_verification=rh.get_ssl_verification()
)

# Get objects in vCenter that are tagged with TAG_ID
response = client.post(
    uri=f"/rest/com/vmware/cis/tagging/tag-association"
        f"/id:{TAG_ID}?~action=list-attached-objects", data={})
client.close_session()

# Let's iterate thru the JSON returned to print tagged VMs
for moid in [value.get('id') for value in response.get('value')
             if value.get('type') == 'VirtualMachine']:
  print(moid)