WilliamLam.com

How do you "log a reason" using PowerCLI when rebooting or shutting down ESXi host?

by // 2 Comments

I am sure many of you have seen this UI prompt asking you to specify a reason before issuing a reboot or shutdown of an ESXi host and I assume most of you spend a few seconds to type in a useful message and not just random characters, right? 😉


Have you ever tried performing the same reboot or shutdown operation using the vSphere API or PowerCLI (which leverages the API)? Have noticed, there is not a way to specify a message like you can in the UI?

Here is a table of the PowerCLI cmdlets and the respective vSphere API that is used to perform these two operations:

Operation Cmdlet vSphere API
Reboot  Restart-VMHost  RebootHost_Task
Shutdown  Stop-VMHost  ShutdownHost_Task

When looking at either the PowerCLI and/or vSphere API documentation, we can confirm that there are no fields to specify a message which can lead to an assumption that this is simply not possible or that the functionality might be provided by a private API. Fortunately, this is not the case and the functionality is in fact in the public vSphere API and has been for quite some time.

When you specify a message prior to rebooting or shutting down, this message is actually persisted and implemented as an Event within vCenter Server as shown in the screenshot below.

Instead of being able to specify a message that is only applicable to an ESXi host, I believe the original vSphere API designers thought that this functionality could also be useful and applied more broadly across any number of the vSphere Inventory objects, not just ESXi hosts. As such, this functionality which the vSphere UI uses is provided by the LogUserEvent() method which is part of the EventManager API. Customers or solutions can leverage this mechanism to log custom user defined events which is then persisted with the lifecycle fo the vSphere Inventory Object or as far back as your retention period for vCenter Server Events.

Going back to our original question, if you want to specify a message prior to rebooting or shutting down an ESXi host, the following snippet below demonstrates the use of the vSphere API via PowerCLI:

$eventManager = Get-View eventManager
$vmhost = Get-VMHost -Name 192.168.30.11
$message = "This message will be logged"

$eventManager.LogUserEvent($vmhost.ExtensionData.MoRef,$message)

New Instant Clone Architecture in vSphere 6.7 – Part 2

by // 5 Comments

In the previous article, I provided an overview of the new "Parentless" Instant Clone feature which was introduced in vSphere 6.7 and some of the architectural differences between prior versions of Instant Clone. In this post, I will show you how to use the new Instant Clone feature, which is currently only available with the vSphere API.

There are two important parts when using Instant Clone:

  1. A user defined script which runs within the GuestOS and is responsible for customizing the network identity of the Instant Clone. This script is not just limited to network configurations but can also be used to customize other OS and/or application settings.
  2. The deployment script which runs outside of the GuestOS and instantiates new Instant Clones using the vSphere API. This script is responsible for passing in data (network configuration, OS and/or application settings) to the GuestOS which can then be accessed directly by the user defined script running within each Instant Clone for actual customization.

To demonstrate the use of the Instant Clone API, I will be using PowerCLI and have also created an Instant Clone PowerCLI module called InstantClone.psm1. However, the API is not limited to just PowerCLI and can be consumed using any of the new vSphere 6.7 SDKs. For our example, we will be exercising the creating Instant Clones from a "Frozen" Source VM workflow since that is the most efficient method, especially as you scale to larger number of Instant Clones. For those that wish to experiment with the other workflow of creating Instant Clones from a "Running" Source VM, feel free to take a look at the previous post for the required steps.

For my setup, I will be using an Ubuntu Server 16.04 system as my Source VM and I will create 30 Instant Clones from this system. Each Instant Clone will immediately be available for use and will be fully customized and reachable from a network perspective (e.g. unique IP and MAC Address). Here is a screenshot of one of my deployments to give you an idea of how blazing fast Instant Clone is 🙂

Here is a short video that I just recorded that demos the Instant Clone APIs using PowerCLI (this demo is using an Ubuntu VM configured with 2GB memory where as the original screenshot was 1GB)

Demo of Instant Clone in vSphere 6.7 from lamw on Vimeo. [Read more...]

VM Creation Date now available in vSphere 6.7

by // 12 Comments

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!

The createDate property is located under VirtualMachine->Config and can be accessed using any one of the supported vSphere 6.7 Automation SDKs which also includes PowerCLI (you will need to install PowerCLI 10.1.0 which enables support for vSphere 6.7)

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:

    (Get-VMHost -Name 192.168.30.10).ExtensionData.Capability.VmCreateDateSupported

  • 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)