Using the vCenter 6.5 API to Deploy Virtual Machines with PowerCLI

First, let me say that using the new APIs in vSphere 6.5 is optional. Instead, one can simply use the standard PowerCLI cmdlets that we all know and love. Just like previously, you did not have to use Get-View if that was too crazy (I certainly didn't use it, unless it was a snippet from lucd :p)

However, these new techniques are pretty cool, and not as difficult as the old .NET techniques. As such, I think this can be a great way for people wanting to step up from using the canned PowerCLI cmdlets to accessing the latest APIs.

While you can go directly to the APIs to consume them, we will use an abstraction layer (Get-CisService) that VMware provides for us to easily work with the vSphere Automation SDK API. This Cis layer handles the interaction with the low level API and masks the complexity.

What's nice, is you can use your favorite PowerCLI cmdlets alongside the new APIs while you build your skill (and while the API matures).


To consume the vSphere Automation SDK using PowerCLI, we have the following requirements:

  • VMware vCenter Server 6.5
  • PowerCLI 6.0 R1 or later (PowerCLI 6.5.1 preferred)
  • Any supported ESX version connected to VC (I use ESX 6.0 U2 with VC 6.5)


Consume the com.vmware.vcenter.VM service on vCenter 6.5 using the Get-CisService cmdlet and deploy a virtual machine.

Note: This is similar to managing the VCSA appliance itself using the new com.vmware.appliance.* services (not covered here). If you are interested in that, check out the examples section at the end of this post. Also see the official vCenter Server Appliance Management API.

About Connections

In PowerCLI 6.5.1, there are nine different Connect-* cmdlets for various things. Here, we focus on the two we need to easily get started with the latest API:

Connect-VIServer This cmdlet establishes a connection to a vCenter Server system
Connect-CisServer This cmdlet establishes a connection to the vSphere Automation SDK server service on vCenter Server 6.5

Getting Started

Launch PowerCLI and connect to your vCenter Server with Connect-VIServer (like normal). This gives us the benefit of being able to do stuff like Get-VMHost, etc.

Connect-VIServer -Server <vcenter>

Next, we make another connection to the same vCenter, but instead of Connect-VIServer we use Connect-CisServer. There are no special URLs for any of this. Simply use your vCenter Server IP Address or DNS Name as usual.

Connect-CisServer -Server <vcenter>

Warning: You may notice a cmdlet with a very similar name (Connect-CIServer) but it's for vCloud Director which is unrelated!


Now that we are connected, we can begin enjoying the new VCSA 6.5 API by using the Get-CisService cmdlet. This acts as a proxy of sorts to the vSphere Automation SDK API service. As a result, the complexity of the underlying API (vCenter Management 6.5), is abstracted from us.

The Get-CisService cmdlet was first introduced in PowerCLI 6.0 R1 (along with the related Connect-CisServer,Disconnect-CisServer and Get-CisCommand). The cmdlet Description showed as being a proxy for vCloud Suite SDK API. This was true for releases until PowerCLI 6.5.1, where it was updated to reflect the name vSphere Automation SDK API instead.

All versions from PowerCLI 6.0 R1 and later work exactly the same against the latest API. I recommend using PowerCLI 6.5.1 since that has the latest help, which includes 2 examples.

help Get-CisService -Examples

For our purposes, we will look at Example 2 which shows us how to deploy a virtual machine by connecting to the VC 6.5 API. The following is the help example in its entirety, unmodified.

# Connect to the vSphere Automation SDK API
Connect-CisServer -Server $serverAddress -User $user -Password $pass

# Get the service for VM management
$vmService = Get-CisService com.vmware.vcenter.VM

# Create a VM creation specification
$createSpec = $vmService.Help.create.spec.CreateExample()

# Fill in the creation details
$ = "ExampleVM"
$createSpec.guest_OS = "WINDOWS_7_64"
$createSpec.placement.folder = (Get-Folder vm).ExtensionData.MoRef.Value
$ = (Get-VMHost)[0].ExtensionData.MoRef.Value
$createSpec.placement.datastore = (Get-Datastore)[0].ExtensionData.MoRef.Value
$createSpec.placement.cluster = $null
$createSpec.placement.resource_pool = $null

# Call the create method passing the specification
$vmService.create( $createSpec )

Try it out!

I recommend trying out the offical VMware example above. This creates a Windows7 virtual machine. However, it will not have a hard disk or network adapter, and will not be powered on. I really like how VMware left some of these things open for you to learn.

Note: You do not need a Windows ISO for this, though the API supports that if desired.

Supported Guests

The official VMware example uses WINDOWS_7_64 as the guest operating system. To choose something else, we can look inside the creation specification ($createSpec) that we built in the example earlier.

Using Select-String, we can search for the desired guest_OS identifier. In my case, I will search for Darwin to see what Apple operating systems are supported (subject to underlying hardware and software requirements of course).

$createSpec.guest_OS -split ',' | Select-String darwin


Note: The supported guests are the same as those used for the Get-VM cmdlet's GuestId parameter.

Connection Variables

This is relevant for folks doing session handling in their scripts. Unlike Connect-VIServer, which supports both $Global:DefaultVIServer and $Global:DefaultVIServers, the Connect-CisServer cmdlet only uses $Global:DefaultCisServers.

Specifically, there is no variable added to the global scope using the singular nomenclature of DefaultCisServer. It simply does not exist.

PS C:\> Get-Variable DefaultCisServers

Name                           Value
----                           -----
global:DefaultCisServers       {vcva02.lab.local}
PS C:\> Get-Variable DefaultCisServer

Get-Variable : Cannot find a variable with the name 'DefaultCisServer'.
At line:1 char:1
+ Get-Variable DefaultCisServer
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There is no spoon; Also, there is no $Global:DefaultCisServer.


Build on VMware's example and start adding the other items that you would normally include when using New-VM. Continue until your skill deploying a VM with VMware.VimAutomation.Cis.Core is as good as your VMware.VimAutomation.Core skills. Those of course, are the modules used when calling Get-CisService and New-VM respectively.


Here are some other examples that use PowerCLI to consume vCenter 6.5 services. All of these use Connect-CisServer and Get-CisService to access one or more API services. Remember the scope of this article was the VM service, but you can also access the appliance service the same way.

New-CisVMPractice.ps1 - This builds upon example #2 from help Get-CisService -Examples that we have been reviewing in this article. I added Credential support, and some other parameters. This consumes the com.vmware.vcenter.VM service from vCenter 6.5.

Backup-VCSA.psm1 - A PowerShell module by Brian Graf to back up your vCenter 6.5 appliance from PowerCLI. This consumes the com.vmware.appliance.recovery.backup service from vCenter 6.5 using Connect-CisServer and Get-CisService. Also see the accompanying blog post Backing up VMware VCSA with new API.

VAMI API - A PowerShell module by William Lam that shows how to consume a multitude of com.vmware.appliance.* services using Connect-CisServer and Get-CisService. There is an accompanying blog series (Exploring New VCSA VAMI API w/ PowerCLI as well.

vSphere Automation SDKs, PowerShell and You - Part 1 - Blog series by Luc Dekens showing how to interact directly with the REST API instead of using the CIS abstractions.

Tip: While the dust settles, you will see the new APIs referred to by many names. An easy way to find who is publishing scripts for this is simply to search for Get-CisService since that is the cmdlet used to proxy us into the API services from PowerCLI.


In this post, we reviewed the use of Connect-CisServer and Get-CisService to access the vSphere Automation SDK API from VMware PowerCLI. We learned that by having Connect-VIServer and Connect-CisServer sessions active concurrently, we can leverage familiar PowerCLI cmdlets until we get our skills up with the latest API.

VMware has an entire new landscape of open APIs and beautiful documentation to immerse yourself in. See VMware Code for more!