One of the most most exciting developments in vSphere 6.5 with respect to Automation is the introduction of several new REST APIs included in the vCenter Server Appliance (VCSA). In addition to covering some of the existing capabilities like vSphere Content Library and Tagging, customers will now have access to a new basic Virtual Machine management API that has been greatly simplified compared to the traditional vSphere SOAP API and access to the VCSA's Virtual Appliance Management Interface API, also known to most as the VAMI.
I am particular excited about the VAMI REST API as this is where customers will be able to manage the entire full lifecycle of their VCSA/PSC which will eventually include all Day 2 operations as well as Install, Upgrade, Migrate and Recovery capabilities. This initial release of the VAMI REST API covers most of the functionality found in the current VAMI UI by going to https://[VCSA]:5480 after your VCSA or PSC has been deployed.
Not having spent a whole lot of time with the new VAMI REST API, I figured a good way for me to learn more about the APIs was to consume it and what better way than using PowerCLI? With PowerCLI 6.5 R1 (Windows version) release, there is a new Connect-CisServer and Get-CisService cmdlet that provides you access to these new REST APIs including the VAMI APIs. As I explore the new VAMI APIs, I plan to create a new VAMI PowerCLI Module that contains functions exerising some of the new APIs that you see today in the VAMI UI.
Before getting started, I wanted to mention some of the resources and tips/ricks that I have been using to get started with the new REST APIs:
- VAMI REST API Online Reference Documentation
- "Live" vCenter Server API Explorer - See this blog post here for more details
Once connected, you can retrieve a list of API service endpoints by simply running the following:
You can also filter the results which includes the use of a wildcard character, which is quite nice. The example below will only show API service endpoints for everything under "com.vmware.appliance":
Get-CisService -Name "com.vmware.appliance.*"
For a given API endpoint, you can then retrieve the operations that are supported by piping the result to the Get-Method cmdlet (gm for short). Below is an example showing the methods for appliance/system/version which is just the get() method:
Get-CisService -Name "com.vmware.appliance.system.version" | gm
For each blog post, I will focus on a specific functional area within the VAMI UI and create a respective PowerCLI function that exercises the required VAMI APIs to retrieve the necessary info. In certain cases, there may be more information available from the API than there is in the UI, which is an additional benefit from using APIs. Each function will be added to an overall VAMI module called VAMI.psm1 and once the blog series is complete, I will submit the PowerCLI module over to the PowerCLI Sample Github project so that others can benefit.
VAMI UI Area of Focus
We will be retrieving some of the basic summary information as highlighted in the VAMI UI below.
VAMI APIs Used
- GET /appliance/system/version
- GET /appliance/system/uptime
The "Product" property will be the same regardless if you deployed a VCSA or PSC node. The next property is the deployment type which can be an Embedded VCSA, External PSC or External VCSA. Below are the three potential values for each of these deployment types.
- vCenter Server with an embedded Platform Services Controller
- VMware Platform Services Controller
- vCenter Server with an external Platform Services Controller
In addition, we can also collect the version and build of the VC/PSC application which can be useful for auditing purposes. Lastly, the VAMI API also includes some other useful information like the initial install time as well as the system uptime which can be useful for auditing as well as monitoring purposes. Hopefully this gives you a nice introduction to the VAMI APIs and stay tuned for Part 2.
- Exploring new VCSA VAMI API w/PowerCLI: Part 1
- Exploring new VCSA VAMI API w/PowerCLI: Part 2
- Exploring new VCSA VAMI API w/PowerCLI: Part 3
- Exploring new VCSA VAMI API w/PowerCLI: Part 4
- Exploring new VCSA VAMI API w/PowerCLI: Part 5
- Exploring new VCSA VAMI API w/PowerCLI: Part 6
- Exploring new VCSA VAMI API w/PowerCLI: Part 7
- Exploring new VCSA VAMI API w/PowerCLI: Part 8
- Exploring new VCSA VAMI API w/PowerCLI: Part 9
- Exploring new VCSA VAMI API w/PowerCLI: Part 10
Jamie Baker says
Hi William, just wondered what your thoughts on the vCenter REST API eventually replacing the SOAP API is?. Thanks Jamie.
Joseph Womack says
Is there a way to change the "Password Expiration Settings"? Specifically changing the "Root password expires" to "No"?
Almero Rademeyer says
This is a game changer . Thank you very much . Do you perhaps know if we can use this to monitor VCHA Failover related events ? Most current Enterprise utilities do not have the ability to trap notify when this occurs . I saw some SNMP options for VCHA , but was not able to figure out the MIB thing .
VAMI.psm1 module link is not available. Can you please make accessible? thx.
William Lam says
David Sellens says
This needs to be distributed via the VMware Fling site not GitHub. GitHub is banned by many organizations particularly the entire DOD.
William Lam says
Thanks for the comment but our Fling site isn't for hosting code samples. I'm sorry to hear that Github is banned as that's how I develop and share my code as well as samples both from the community/VMware. I don't know if this helps but the modules above have also been submitted to official VMware repo on Github
Barry Obie says
I couldn't get Get-VAMISummary or Get-VAMIHealth to work. I was getting an error: Unable to authenticate user. After digging around a bit, I found this article http://www.vryan.co.uk/index.php/2018/05/09/vcsa-automated-backup-failure/. It worked like a charm.
Scott Elliott says
Can you pull syslog info with these APIs? I am not seeing it in the document link you provided and thought maybe I am missing it?
John M says
How we do use the api calls for a non cloud systems?
using connect-viserver the Get-CisService does not work
trying to use connect-CisServer I can not login.
Connect-CIServer : 5/1/2019 10:51:18 AM Connect-CIServer No Cloud server was found on https://vcentername:443/api/
You are missing the 's' in Connect-Ci's'Server. Connect-CIServer is used to connect to the Cloud Server.