VMUG Norway session - REST APIs for the VMware Admin

This week I have been on a "VMUG Tour" visiting the Norwegian VMUG branches in Oslo, Bergen and Trondheim. I did the same last summer and had lots of fun so I was excited for this years tour as well.

The topic of my session was partly an extension of the stuff I did last year where I showed how to create a Performance monitoring solution for your vSphere platform and other parts of your infrastructure with open-soure tools like InfluxDB and Grafana.

This time I showed how to add your VCSA to the mix by utilizing the REST APIs in vCenter.

The other part of the topic for this session was how a VMware admin can get started with REST APIs in general and the vCenter ones in particular. We also discussed why it is important to have an understanding about how to use and find information about the REST APIs.

We covered some basics about REST, the principles, the request methods, response codes, body, headers and the anatomy of a REST call.

Swapi

In the session I used a website with an API to show some techniques and demoing how easy it is to use REST. The website I used was swapi.co which has lots of stuff from the Star Wars universe. You can pull information about characters, planets, spaceships and more and the API is completely open and free. That makes it perfect for experimenting with REST, especially if you are into Star Wars.

I showed that with just a REST client, which most people have available through i.e. Powershell or cUrl, you can run your first API call and pull stuff from the web!

For instance, to pull information about a character from the Star Wars universe you run a GET call to the people resource and optionally specify an Id

 1PS C:\> Invoke-RestMethod -Method Get -Uri "https://swapi.co/api/people/1"
 2
 3
 4name       : Luke Skywalker
 5height     : 172
 6mass       : 77
 7hair_color : blond
 8skin_color : fair
 9eye_color  : blue
10birth_year : 19BBY
11gender     : male
12homeworld  : https://swapi.co/api/planets/1/
13films      : {https://swapi.co/api/films/2/, https://swapi.co/api/films/6/, https://swapi.co/api/films/3/, https://swap
14             i.co/api/films/1/...}
15species    : {https://swapi.co/api/species/1/}
16vehicles   : {https://swapi.co/api/vehicles/14/, https://swapi.co/api/vehicles/30/}
17starships  : {https://swapi.co/api/starships/12/, https://swapi.co/api/starships/22/}
18created    : 2014-12-09T13:50:51.644000Z
19edited     : 2014-12-20T21:17:56.891000Z
20url        : https://swapi.co/api/people/1/
21

vSphere APIs

After playing around in the swapi API a bit we continued with looking at the vSphere APIs and how you can explore those. There's lots of resources around this and the documentation is available on code.vmware.com. Furthermore, with a reasonably updated vCenter, you have an APIExplorer available on your vCenter that runs commands directly to your own environment.

We also looked at and used the Postman examples VMware has created. Postman is an "API Development Environment" and works as a REST client that makes it easy to explore APIs and has the ability to set up stuff like environments that can be used when connecting to vCenter.

Both the APIExplorer and Postman masks some of the authentication process and takes care of the authentication and session header for you. This is nice, but to explain how the authentication process is done I demoed how you authenticate to the vCenter API with Powershell and how you use the session-id in subsequent API calls.

Following up on the topic of why you need to have an understanding about REST and the vSphere APIs we discussed how an Admin today will get questions from developers etc with requests on how they can create and manage their own VMs without having to click around in the vCenter UI (you probably won't have your devs in their in the fist place..). Of course you really should have proper access rights in place.

Integrating with APIs

Integration is also a big topic today and stuff from vCenter often needs to be integrated into other systems.

As a (silly) example on how we can integrate two apps with REST we created VMs in vCenter and used the name of random characters in the Star Wars universe as VM names. Kind of cool

 1
 2PS C:\> $uri = $BaseUri + "vcenter/vm/"
 3PS C:\> $random = Get-Random -Minimum 1 -Maximum 80
 4PS C:\> $swChar = Invoke-RestMethod -Method Get -Uri "https://swapi.co/api/people/$random/"
 5PS C:\> $vmname = $swChar.name
 6PS C:\>
 7PS C:\> $newVMBody = @{
 8>>     "spec"= @{
 9>>         "name" = $vmname
10>>         "guest_OS" = "RHEL_7_64"
11>>         "placement" = @{
12>>             "datastore"= "datastore-14"
13>>             "folder"= "group-v9"
14>>             "host" = "host-12"
15>>         }
16>>     }
17>> } | ConvertTo-Json -Depth 3
18PS C:\> Invoke-RestMethod -Method Post -Headers $sessionheader -Uri $uri -Body $newVMBody -ContentType "application/json"
19
20value
21-----
22vm-111
23
24

\

To really underline the need for having access rights in place we deleted a VM through the API. There's no "Are you really sure?" popup here, stuff is done as soon as the (correct) API call has been accepted by vCenter.

VCSA dashboard

As an example of why REST also can help the VMware admin we pulled health and service information from the VCSA. We created a Grafana dashboard with health status, cpu/memory utilization and disk stats.

\

I did a session on the same in the VMUG meeting in Oslo in December 2018 and I did a blog post that documents the process of building out the dashboard used in the session so feel free to check that out.

Summary

The VMUG Tour have been lots of fun and I seemed that the topic was interesting for the community members. There is a real power in todays modern API based world and as VMware Admins I think that we really need to have an understanding on how this stuff works. If not for using APIs in your own work then for having a basic level of understanding when discussing with developers and others on how to integrate with the vSphere platform.

The slide deck and the scripts used can be found on GitHub.