vSphere API

Last year, I wrote about a new Virtual Machine API property called createDate which provides customers a method of retrieving the original creation date and time of a VM. This vSphere API was first introduced in VMware Cloud on AWS and with the release of vSphere 6.7, it is also now available for on-premises customers to consume.

I know this is a feature that many customers have been asking for (including myself) and I am super happy to finally see this information automatically captured and persisted as part of the VM configuration. Customers no longer have to query the vCenter Server Events API to retrieve this information and store it externally, since it can be rotated out and basically lost due to your vCenter Server Events retention configuration. As of right now, the VM creation date is only available using the vSphere API, it is currently not available in the vSphere H5 Client and hopefully I will be able to convince PM to add this useful piece information into the UI as well!

Here is an example of retrieving the createDate for a VM named esxi67-01:

(Get-VM -Name esxi67-01).ExtensionData.Config.createDate

Here are a few things to be aware of regarding the createDate behavior:

BOTH vCenter Server and ESXi hosts must be upgraded to 6.7 to make use of the new API

This API is available on both vCenter Server as well as ESXi hosts running 6.7

Only new VMs that were created after upgrading to 6.7 will include this property with the creation date

VMs that were created prior to upgrading 6.7 will not have their original creation date, but rather a default value of 1970-01-01T00:00:00Z. If ESXi hosts have not been upgraded but vCenter Server has, then the API property will be unset (null)

You can programmatically check whether an ESXi host supports the new createDate property by querying its capabilities using the vSphere API. Here is a PowerCLI example:

VMs created in a vSphere 6.7 environment can be Cross vCenter vMotion to other non-vSphere 6.7 environments and migrated back while retaining its original createDate value. This is done so by storing the value in the extraConfig property of a VM (this is best effort support and we recommend only migrating to vSphere 6.7 or newer environments)

Instant Clone or VMFork (as it is referred internally) has been around for a number of years now. It was initially available as part of vSphere 6.0 with the primary consumer being Horizon View and their just-in-time desktop solution. Although Instant Clone was part of the core vSphere platform, public APIs were not available for external consumption. Many customers were interested in the technology to enable other non-VDI use cases such as Dev/Test, Continuous Integration/Continuous Development (CI/CD) and even Container workloads. Part of the reason for not exposing the API was partially due to the original Instant Clone architecture which has certain limitations and constraints.

In addition, VMware was also interested in getting feedback from customers on how they would like to consume Instant Clone from an Automation standpoint, this was important because the current workflows were also some what complex. This started out with the release of a PowerCLI Instant Clone Extension Fling that provided an abstraction on top of the private APIs. Based on that and other feedback, VMware followed that up by releasing Instant Clone for pyvmomi (vSphere SDK for Python) Fling which gave customers more programmatic access to the private APIs. Both Flings were a huge success and we even had customers using the pyvmomi Instant Clone modules in Production to deploy several hundred Instant Clone VMs per day for their CI/CD workloads.

Taking the learnings from both Horizon View and the feedback from customers using the Flings, the Instant Clone Product/Engineering team has been hard at work behind the scenes on simplifying the Instant Clone architecture and removing limitations and constraints that had existed in earlier versions. As you can imagine, this was a non-trivial amount of work that would need to be released in phases, especially as VM lifecycle management touches almost every part of the vSphere stack. The team really focused on ease of consumption, especially from an Automation standpoint which is how most customers prefer to consume Instant Clone.

Below are just a few of the new vSphere 6.7 SOAP and REST APIs that have been added or enhanced which I think will be quite useful for customers to be aware of while they start to plan for their vSphere 6.7 upgrades. For a complete list of new vSphere 6.7 (SOAP based) APIs, check out the vSphere 6.7 API Reference Guide which will include a "What's New" section on all the new Managed Objects, Methods, Properties, etc. For a complete list of new vSphere 6.7 REST based APIs, check out vSphere Automation API 6.7 Reference which you can identify new operations and properties which will be marked with "Added in vSphere 6.7".

vSphere 6.7 WebServices (SOAP) API

AlarmManager->ClearTriggeredAlarms() - This method finally provides a way for customers to clear an alarm like you can using the vSphere UI. Historically, customers only had the ability to acknowledge an alarm using the API but not a way to reset alarms.

VirtualMachine->ApplyEvcModeVM_Task() - This method can be used to enable the new Per-VM Enhanced vMotion Capability (EVC) feature that has been introduced in vSphere 6.7

VirtualMachine->InstantClone_Task() - This method simplifies the deployment of new version of Instant Clone that has been added into vSphere 6.7. For more details on how the new Instant Clone feature works, please take a look at this blog post here.

HostNvdimmSystem - This new Managed Object and its respective methods can can be used to manage the new NVDIMM (Persistent Memory) capability that has been added into vSphere 6.7

VirtualMachine->Config->createDate - This new property finally includes the creation date of a VM that has been created in vSphere 6.7 and will be persisted with the lifecycle of the VM itself. I will provide a more detailed blog post on how to consume this new property as well as the expected behaviors, especially around upgrades. I know many of you have been asking for this property and I am glad to see this finally available for all on-premises customers!

VirtualMachineGuestOsIdentifier - These are all the new GuestOS Ids that have been added into vSphere 6.7 to enable new GuestOS support, you can find the mapping of the OS type by taking a look at the vSphere API Reference Guide

asianux8_64Guest

centos8_64Guest

darwin17_64Guest

darwin18_64Guest

freebsd11Guest

freebsd11_64Guest

freebsd12Guest

freebsd12_64Guest

oracleLinux8_64Guest

other4xLinux64Guest

other4xLinuxGuest

rhel8_64Guest

sles15_64Guest

vSphere 6.7 REST API

/appliance/backup/schedules - This endpoint provides management and configuration of the new VCSA scheduled backup feature

/appliance/backup/system_name - This endpoint allows you to list all existing backups that have been taken for your VCSA

/appliance/local_accounts - This endpoint provides management of all local users

/appliance/local_accounts/policy - This endpoint provides global password policy management for all local users

/appliance/ntp - This endpoint provides NTP configuration for the VCSA

/vcenter/deployment - This endpoint enables the ability to automate both Install/Upgrade of the Stage2 installer for VCSA/PSC. Stage 1 deployment of the appliance is currently not part of the REST API but can be automated using existing methods such as OVFTool or PowerCLI as an example.

/vcenter/vm/guest/{identity,local_filesystem} - This endpoint provides guestOS details such as the configured OS along with some basic networking (e.g. Hostname and IP Address) which is retrieved as part of the VMware Tools service running inside of the GuestOS. In addition, you can also get visibility into the guest filesystem including capacity and freespace.

/vcenter/vm/storage/policy - This endpoint provides details about the current configured VM Storage Policy for individual VMDKs of a VM

There was an interesting discussion on our internal Socialcast platform last week on figuring out how an ESXi host is booted up whether it is from local device like a disk or USB device, Auto Deploy or even boot from SAN along with its respective boot device? Although I had answered the question, I was not confident that we actually had a reliable and programmatic method for identifying all the different ESXi boot methods, which of course piqued my interest.

With a bit of trial and error in the lab, I believe I have found a method in which we can identify the ESXi boot type (Local, Stateless, Stateless Caching, Stateful or Boot from SAN) along with some additional details pertaining to the boot device. To demonstrate this, I have created the following PowerCLI script ESXiBootDevice.ps1 which contains a function called Get-ESXiBootDevice.

The function can be called without any parameters, in which it will query all ESXi hosts for a given vCenter Server and/or standalone ESXi host. You can also specify a specific ESXi host by simply passing in the -VMHostname option.

Here is an example output for one of my lab environments which shows several ESXi hosts and their different boot methods from local disk to Auto Deploy which can include stateless, stateless caching and stateful deployments. Depending on the BootType, the boot device shown in the Device column will either be the MAC Address of the NIC used to network boot the ESXi host or the identifier of a disk device. I have also included some additional details such as vendor/model along with the media type (SAS, SSD or USB) which is available as part of ESXCLI.

This script also supports ESXi environments that boot from SAN (FC, FCoE or iSCSI) and you can easily identify that with the word "remote" for the BootType. I would like to give a huge thanks to David Stamen who helped me out with the boot from SAN testing.

I was recently reminded of an excellent VMworld 2017 session that given by Ravi Soundararajan, a Principal Engineer at VMware working in our vCenter Server Performance Team. In his session, vCenter Server Performance Deep Dive, Ravi provides some great insights into things to consider that may have an impact on vCenter Server performance. In addition, he also covered a few additional topics, one of which that comes up every so often which around auditing vSphere API usages for a given user. Below are links to both the recording as well as the deck.

If you were not able to watch Ravi's session live, I highly recommend giving the session a watch and downloading the deck as it contains a ton of useful nuggets!

After re-watching Ravi's session on auditing vSphere API usage, I thought it would be cool to automate the manual process he had outlined. With that, I created a PowerShell script called vSphereAPIUsage.ps1 which contains a single function called Get-vSphereAPIUsage. This script requires access to the vpxd.log which a user will need to download from vCenter Server by either running a VC Support bundle or manually retrieving it from the vCenter Server. In addition, you will need to also provide the user session ID that you wish to query. In Ravi's session, he pointed users to the vpxd-profiler.log but I had found that this can also be found within the vpxd.log which saves users from having to look at another file.

Once you have downloaded the vpxd.log locally on your system, go ahead and open it up with your favorite text editor. I highly recommend Microsoft Visual Studio Code, if you do not have one handy or prefer something beyonds notepad or vi. You will need to search for the particular user you wish to perform the query and the string to search for should look like the following (replace with your SSO or AD domain and username)

[Auth]: User VSPHERE.LOCAL\Administrator

I would also recommend searching from the bottom up as you may want the last login from this particular user. Once you have identified the line, you then need to go up three lines until you see "vim.SessionManager.loginByToken" entry and to the right of that (highlighted in green) is the session ID that you need to make a note of. You can also use the opID value to ensure the session ID is in fact related to this login as you may have other log entries in between.

After making a note of the session ID, you can simply call the Get-vSphereAPIUsage and provide it the full path to the downloaded vpxd.log and the session ID that you had retrieved above. Here is an example using the session ID from the screenshot above:

The results of the script is a tally of all the different vSphere APIs that have been invoked by this particular session/user and its frequency from lowest to highest. In the example above, I had created a new Datacenter entity, created a couple of Clusters, created several VMs, powered on/off and created/deleted snapshot. These operations were all invoked using the vSphere H5 Client, so there will be other vSphere APIs that are in-directly used by the UI such as inventory lookup that may show up. Hopefully this script will come in handy for those that are interested in this information and beats going through the vpxd.log line by line 🙂

Lastly, Ravi also mentioned that you can use the vSphere Flex/H5 Client to get useful information for a given vCenter Server Session such as the client IP Address as well as the number of API invocations. These details can also be retrieved by using the vSphere API itself, have a look at this article here which provides more details.

Since publishing my Automating Cross vCenter vMotion between the same and different SSO Domain article back in early 2016, I have had a large number of customers reach out to me and share their success stories of allowing them to perform datacenter migrations to consolidating vCenter Servers all due to this awesome capability that was introduced in vSphere 6.0. In fact, many of the VM migration numbers were in the 4,000 to 8,000+ range which completely blew me away. It was great to hear from customers on how the xMoveVM.ps1 script had enabled them to do things that was simply not possible before, especially without impacting their workloads.

I still get pinged on a regular basis from customers about using my script and one thing that surprises many customers when I mention to them that this functionality has already been ported over to the native Move-VM cmdlet that was introduced with the PowerCLI 6.5 release. This had always been my original intention to provide an example using our vSphere API and enabling our customers in the short term and working with Alan Renouf and the PowerCLI team to get this folded back into the official PowerCLI cmdlets. This means, you no longer have to use my script for basic Cross vCenter vMotions whether that is between the same or different SSO Domain, which is quite nice as the number of user inputs is significantly reduced by using Move-VM cmdlet.

Primary Sidebar

Search this website

Author

William Lam is a Staff Solutions Architect working in the VMware Cloud on AWS team within the Cloud Platform Business Unit (CPBU) at VMware. He focuses on Automation, Integration and Operation of the VMware Software Defined Datacenter (SDDC).