vSphere Automation SDKs, PowerShell and you – Part 1

Yesterday a blog post, named Integration with VMware vSphere using the new Open Sourced Software Development Kits, was published. In my opinion an important milestone on VMware’s Open Source path ! The blog post announced the availability of the first two Open Sourced SDKs made available to the public on GitHub. One for REST and the other for Python.

When we hear REST API, we know it is relatively easy to consume these from a PowerShell script. So power up your labs and follow along on my first steps in my vSphere Audtomation SDK and PowerShell adventure.

Intro

The REST API were officially announced during VMworld EMEA 2016 in Barcelona.

Recently Kyle Ruddy published two blog posts on the VMware {code} blog that showed how to get started with both SDK.

Both should be in your reading list, since they are excellent introductions to the REST API usage, although not with our favourite tool 🙂

Note that what I show in this series is not the only way to consume the REST API. The Connect-CisServer, the Get-CisService and the Disconnect-CisServer cmdlets also give you access to the vSphere Automation SDK services. You can find great examples of working with those cmdlets in William Lam‘s series Exploring new VCSA VAMI API w/PowerCLI. Those should go into your reading list as well!

Environment

I do my exploration of the vSphere Automation SDK for REST in a vSphere 6.5 environment. My vCenter is a VCSA, and I’m using PowerShell 5.1.

Besides the PostMan tool, which is described in one of Kyle’s posts, I also find it handy to use Fiddler2 while coding and debugging. It acts as a proxy between my code and the VCSA.

When you’re working with the REST API you have to install the REST API repository on your system. They did a good job of producing this documentation.

The code for this series is available in my OpenSdk repository.

Some Basics

As I already demonstrated in my Ravello module, it is quite easy to consume REST API with PowerShell. With the Invoke-WebRequest cmdlet calling REST API becomes a breeze.

A few basics one needs to be aware of.

  • The key function in the code is the Invoke-RestCall function. This function does the preparation of the parameters, the actual Invoke-WebRequest call and the handling of any errors resulting from the call. I’m also investigating of the use of Invoke-RestMethod would bring any advantages.
  • Separate methods will be wrapped in separate functions. For now I tried to use function names that resemble their PowerCLI counterparts. You’ll find Connect-rViServer, Get-rVMHost…
  • Authentication in my code, as well as in the SDK Samples, is done as Basic Authentication. Creating the Authorization string can be done with PowerShell and some .Net methods.

  • As most REST API libraries, the vSphere Automation API also use a “Session” string for all calls after the authentication call. When using the Invoke-WebRequest cmdlet, there is no need to create a header with a session cookie. That is handled by the WebSession parameter. Note that Cookie header is in fact a Restricted Header, meaning you can just create it like any other regular header.
  • To store some basic information between different calls to the REST API, I use a Class object. That is easier to handle, and will open perspectives in future episodes of this series.

  • I use the Verbose option a lot while writing code. So you’ll see my standard “verbosity lines” at the start of each function.

Write-Verbose -Message “t$($PSCmdlet.ParameterSetName)" Write-Verbose -Message "tCalled from $($stack = Get-PSCallStack; $stack[1].Command) at $($stack[1].Location)”

Why?

One might wonder why I would be looking at wrapping these REST API in PowerShell code! More so, since these API can be consumed via native PowerCLI cmdlets (see my earlier note). I did in fact the same before starting this series, and I came up with these (random order) arguments.

  • Because we can! The fact that these REST API are open and public, make them an attractive alternative for all other available tools.
  • Open. The wrapper code and the REST API are Open, this in contrast to some of the binary products like PowerCLI. The wrapper code can be version controlled, and we can pull diffs between different versions
  • Appliance. We can avoid one extra dependency when installing an appliance.
  • Desired State Configuration (DSC). Same as the Appliance consideration, one less layer to take into account.
  • PowerShell. Although PostMan, Python, JavaScript… are most probably great tools, it pays to limit the number of tools one is using.
  • Uniformity. When PowerShell is the preferred tool of automation, it is an advantage to be able consume the REST API with the same tool. Note that if you have PowerCLI installed, you can use the CIS cmdlets (see my remark earlier)
  • Eco-system. To me it is more and more obvious that REST API are a preferred way to “talk” with many, if eventually not all, of VMware’s products.
  • Simplicity. The HTTP driven REST communication is simple to manage and control.

Sample Usage

In this first part there are only two functions available, a function to connect, and another to get the list of ESXi nodes in the environment. These two functions allowed me to tackle a number of the basic issues, so future functions should come faster 🙂

These two functions do, currently, not allow for a lot of variation. Open a session, get the list. That’s it.

In Fiddler2 the connection call is seen as follows. Note the User-Agent is PowerShell 5.1.

Notice how the encoded Authorization header is passed to the REST API.

The REST API returns the session ID. Instead of using a restricted header, this will be passed along through the WebSession parameter on the Invoke-WebRequest cmdlet..

In the subsequent calls to other REST API, the session id will passed.

And of course the result of our REST API call.

As we can notice, the result is returned as a JSON object. In one of the next posts in this series, we will discuss how to convert this to a PowerShell object.

Enjoy!

Leave a Reply

Your email address will not be published. Required fields are marked *

*
*

This site uses Akismet to reduce spam. Learn how your comment data is processed.