Supercharging your PowerCLI Scripts with Wait-Tools

How often do you use scripts?

Most virtualization admins find themselves having to script something at one point or another. The old saying, of course, being: “If you have to do something twice, script it.” It’s a true statement and one I think more IT pros are getting on board with. Scripting is great for those everyday maintenance tasks, and it works great for the stuff that falls outside of the standard maintenance scope as well, but in order to get REALLY good with scripting, you have to use all the tools available to you. With that in mind, I want to talk about a specific cmdlet that I think goes unnoticed. Let’s talk about Wait-Tools.

This articles is about Powershell. PowerShell is a free tool that uses scripts to automate tasks. Here are 101 Free VMware Tools (including PowerShell) that will help you become more efficient when using VMware.

The Use-Case for Wait Tools

The use cases are numerous, but one area (that also happens to be my favorite realm for scripting), is deployment orchestration. Deploying new workloads can be time-consuming but being able to handle scripted tasks not only at the hypervisor layer but also within the newly deployed workload can cut down your deployment time considerably. I used to work for a rather large service provider with a “private hosted cloud” offering that was built on vSphere, and as such, much of my time was spent doing deployments centered around that infrastructure.

It’s during this time that I discovered the Wait-Tools cmdlet. Most of our customers followed the cookie-cutter standard of 2 Domain controllers, a file server, and an RDS deployment. With all of these being Microsoft core services, I knew that I could automate the deployment with PowerShell. One thing I was struggling with during the deployment process was my script knowing when a particular VM was done booting for the first time, or done going through a reboot. Now sure, I could have used PowerShell remoting to check the status of a given process repeatedly until it was ready and then move on. However, what if the VM doesn’t have a configured network yet? The Get-Process method doesn’t work. This is where Wait Tools comes in.

Wait-Tools communicates with a VM through the hypervisor layer and as such doesn’t depend on networking being available. This makes it the perfect fit for deployment operations, though it’s not limited to this case.

Now outside of use-case, what does Wait-Tools actually do?

What Does Wait-Tools Do?

In short, Wait-Tools will watch a given VM until the VMware Tools Service is running and responding. The Script flow looks much like the below,

If you want the official explanation, the help file reads:

NAME

Wait-Tools

SYNOPSIS
This cmdlet waits for VMware Tools on the specified virtual machines to load.

SYNTAX
Wait-Tools [-VM] <VirtualMachine[]> [[-TimeoutSeconds] <Int32>] [-HostCredential <PSCredential>] [-HostUser
<String>] [-HostPassword <SecureString>] [-Server <VIServer[]>] [<CommonParameters>]
Wait-Tools [[-TimeoutSeconds] <Int32>] [-HostCredential <PSCredential>] [-HostUser <String>] [-HostPassword
<SecureString>] [-Guest] <VMGuest[]> [<CommonParameters>]

DESCRIPTION
This cmdlet waits for VMware Tools of the specified virtual machines to load. The cmdlet returns the virtual
machines or guests on which VMware Tools have loaded successfully within the specified time limits. You can cancel
the operation before completion using Ctrl+C.

The successful completion of Wait-Tools means that VMware Tools have loaded, but it does not guarantee for the
start of other services.

Updating the returned VMGuest objects requires additional communication with VMware Tools and some of their
properties (OSFullName, IPAddress, HostName, and other) might be still empty right after the completion of Wait-Tools.

 

As you can see there are some caveats, but everything here is easily worked around. I’ve found in using this tool, that by the time VMware tools are ready, most other services on the system are running as well. If you have a service you know is going to take a bit to get going, you’ll want to use another method in addition to Wait-Tools that checks the status of that service prior to advancing the script.

Additionally, if you have a script that gathers or uses some of the VMware tools related info (Like OSFullName, IPAddress…etc.) listed above, I’ve paired that with a simple PowerShell wait loop with 10 seconds in between each check. The script waits, and periodically checks to see if those values have been populated yet.

An Example of Wait-Tools in Action

I’ve pulled the below example from a script I published a while back that uses wait-tools extensively.

In this code snippet, I’m using Invoke-VMScript to reach inside of a VM, install the Active Directory Role, reboot the VM, and then provision a new Administrative user account once the machine is responding again. Many of the targets and Script actions are defined with variables, but you can still get a sense of what’s happening below. If you want to see exactly what’s contained in the below variables, take a look at the link listed above.

# Then we Actually install the AD Role and configure the new domain

Write-Verbose -Message "Getting Ready to Install Active Directory Services on $DomainControllerVMName" -Verbose

Invoke-VMScript -ScriptText $InstallADRole -VM $DomainControllerVMName -GuestCredential $DCLocalCredential

Write-Verbose -Message "Configuring New AD Forest on $DomainControllerVMName" -Verbose

Invoke-VMScript -ScriptText $ConfigureNewDomain -VM $DomainControllerVMName -GuestCredential $DCLocalCredential

# Script Block for configuration of AD automatically reboots the machine after provisioning

Write-Verbose -Message "Rebooting $DomainControllerVMName to Complete Forest Provisioning" -Verbose

# Below sleep command is in place as the reboot needed from the above command doesn't always happen before the wait-tools command is run

Start-Sleep -Seconds 60

Wait-Tools -VM $DomainControllerVMName -TimeoutSeconds 300

Write-Verbose -Message "Installation of Domain Services and Forest Provisioning on $DomainControllerVMName Complete" -Verbose

Write-Verbose -Message "Adding new administative user account to domain" -Verbose

Invoke-VMScript -ScriptText $NewAdminUser -VM $DomainControllerVMName -GuestCredential $DomainCredential

So, you can see above that I’ve paired Wait-Tools with the general PowerShell Start-Sleep cmdlet because AD’s deployment process doesn’t always reboot the OS immediately after the deployment process is over. Pairing Wait-Tools with other time management mechanisms provides a lot of flexibility.

Wrap-Up

As mentioned earlier in the article, I was deploying a lot of environments with a very simple 2 DC, 1 file server, 1 RDS server configuration. This script and Wait-Tools allowed me to script the entire process. I simply filled out the variables for the given customer and let it run. Think about the amount of time it takes to manually provision a domain and configure users. With the tools available, I took a very mundane process and automated it, so I had much more time to work on other things.

Hopefully, you’ve found this useful! If you’ve used Wait-Tools before and would like to share an interesting use case let us know in the comments below! Also, if you have questions let us know as well! Also, if you find these PowerCLI command reviews valuable, and would like to see more, let us know about that in the comments below too!

Thanks for reading!

[the_ad id=”4738″][thrive_leads id=’18673′]