Home > Blogs > VMware PowerCLI Blog

Getting Started with the HCX Module

2 Replies

PowerCLI 11.2.0 introduced a brand-new module that allows us to easily automate VMware HCX! The VMware.VimAutomation.HCX module adds 20 new cmdlets to already existing count of well over 600 cmdlets contained in the entire set of PowerCLI modules. This is important because HCX is one of the newest technologies VMware has released and it has some impressive power.

To give a quick overview, think of VMware HCX as a swiss army knife – a single tool with multiple options to move your workloads in and out of the cloud. Schedule migrations with HCX vMotion, take advantage of replication assisted vMotion for bulk migrations and even VMs with larger footprints, or simply protect your data with the available disaster recovery options. HCX is a powerful tool to easily manage the location of your workloads.

For more information on HCX itself, see the following blog article from my colleague Emad Younis: Learning Hybrid Cloud Extension (HCX)

My lab environment is shared between a couple of my peers and I didn’t happen to deploy HCX to this environment. So, let’s walk through a couple examples of using the HCX module to perform some environment discovery and follow that up with performing an HCX vMotion.

Getting Started

The first time I use a module, I examine the cmdlets that are available. We can do that with the following code:

We can see in the response that each of the cmdlets have a prefix, for the noun portion, of HCX. There’s the standard Connect-HCXServer and Disconnect-HCXServer cmdlets for authentication, along with the low-level Get-HCXService cmdlet so we can access the API directly. The other cmdlets are high-level, which have abstracted the available API calls and provided us with easy to understand names and parameters.

First, we need to authenticate to our HCX environment. We will connect directly to the on-premises HCX Manager using the Connect-HCXServer cmdlet.

Example: Connect-HCXServer Output

Now that we’re connected, we can take a look at some of the appliances which have been deployed. We can use the Get-HCXAppliance cmdlet to do that.

Example: Get-HCXAppliance Output

We can see that we have 3 appliances deployed and the type for each of them. This falls in line with what you would see under the “HCX Components” tab of the Infrastructure Interconnect page in the HCX Management UI.

Another piece of information on that particular page is the status of the Interconnect. We can receive that with the Get-HCXInterconnectStatus cmdlet.

Example: Get-HCXInterconnectStatus

We also want to know some site-based information. We can make use of the Get-HCXSite cmdlet to do this. However, we will be making use of two parameters to get the full picture. These two parameters are Source and Destination. If no parameter is used, we’ll receive the source site information by default.

Example: Get-HCXSite Output

There are also a handful of cmdlets to help us discover the what vSphere objects are available to the HCX environment. These include Get-HCXVM, Get-HCXDatastore, Get-HCXNetwork, and Get-HCXContainer. The first three should be fairly obvious, but the fourth cmdlet is a little more ambiguous. Get-HCXContainer returns back a list of multiple object types including clusters, datastores, folders, hosts, and resource pools.

Example: Get-HCXContainer Output

One item to take note of, by default each of these cmdlets only return objects for the source site. If you want to receive objects from some other site, you will need to specify that with the Site parameter.

At this point, I think we’re fairly familiar with our environment so let’s take a look at performing an HCX migration!

HCX Migration

The HCX Migration service offers numerous ways to migrate our VMs between the available sites. There are five cmdlets to help us automate migrations.

We can start off by using Get-HCXMigration to see a status on any existing migrations. In this case, there has been one previous migration and we can use the “Format-List” parameter to see the all the properties for the HCXMigration object.

Example: Get-HCXMigration Output

Next, let’s perform an HCX Migration. We’ll need to populate a handful of parameters to create the migration with New-HCXMigration. This is quite similar to performing a standard vMotion between vCenters with Move-VM. One big caveat though, the New-HCXMigration cmdlet is looking for HCX objects and not the standard objects we receive from vCenter. Therefore, we’ll be using the HCX associated cmdlets to create variables for each of those parameters.

Here’s some example code based on my environment:

Then, we can run our New-HCXMigration cmdlet. In my environment, I stored the output from the cmdlet into a variable since we will need to reference it later.

Example code:

Our migration is created, but it hasn’t actually started yet. There’s one more step to perform before we start the migration, and that’s testing the migration!

Example code:

Assuming a successful validation, we can now move onward to performing the migration with the Start-HCXMigration cmdlet.

Putting the above altogether, it should look similar to the following:

Example: New Migration Workflow

Summary

A new module has been made available as part of PowerCLI 11.2.0 to automate VMware HCX. This module includes 20 cmdlets which can be used to discover HCX environments and automate the lifecycle of network extensions, migrations, and disaster recovery replication. PowerCLI makes it easier than ever to migrate and protect your workloads!

Let us know in the comments what HCX actions you’re using PowerCLI for!

Configuring VMs For Opaque Networks

2 Replies

PowerCLI has a new object to interact with, thanks to NSX-T! The Opaque Network managed object gives us the ability to interact with NSX-T provisioned logical switches as though they are port groups. Technically, it has been available for a couple releases of vSphere but the functionality was really improved here recently.

Last year we released KB 65149 that included code to create a new function, named Set-NetworkAdapterOpaqueNetwork. This function could be used to assign an opaque network to a VM’s network adapter. I’m happy to relay that, as of PowerCLI 11.2.0, we no longer have to rely on that function. We can now use the Set-NetworkAdapater to assign an opaque network just as we would any other normal port group with the NetworkName parameter. We also have the ability to deploy OVAs and/or OVFs with an opaque network configured in the OVFConfiguration parameter.

Before we dive into some coding examples, we should begin by showing how to list out the available opaque networks. This is because opaque networks aren’t included as part of the response for either Get-VirtualPortGroup or Get-VDPortGroup. Each of those cmdlets return their own object types. Therefore, we need to rely on the Get-View cmdlet to interact directly with the vSphere Web Services API.

Retrieving Opaque Networks

We can list all of our vCenter’s opaque networks with the following command:

Since we’re interacting directly with the API, we’re going to receive back all of the top-level information about each opaque network. We can condense the output and make it a little easier to read with the following code:

Sample: Condensed output from listing opaque networks

Configuring Opaque Networks

We now have a list of opaque networks which are available for us to use. The next step is to start configuring our VMs to use them. As of PowerCLI 11.2.0, we can use the already existing Set-NetworkAdapter cmdlet combined with the NetworkName parameter to make the change.

We can update a VM’s port group association to be an opaque network with the following code:

Example: Set-NetworkAdapter Usage

Summary

NSX-T adds a new object for PowerCLI to interact with in the form of an opaque network. These are a representation, at the vSphere level, of a logical switch which has been provisioned from NSX-T. PowerCLI 11.2.0 includes updates to existing cmdlets that allow us to assign opaque networks to our VMs as port groups. The first, which was demonstrated in this post, is to modify a VM’s network adapter with the Set-NetworkAdapter cmdlet paired with the NetworkName parameter. The second, while deploying OVAs and/or OVFs through Import-VApp when using the OvfConfiguration parameter.

Update today to the latest version of PowerCLI to ensure you have access to the latest features and functionalities.

Documentation Walkthrough

1 Reply

Documentation is an important part of the automation and development process. When I first started using PowerCLI, I found the docs to be overwhelming and confusing. As my PowerCLI knowledge grew, I started to use them more and more. Instead of frustratingly browsing the multiple levels of properties that make up vCenter objects in a terminal, I found I could easily pick them out in the docs. As part of this blog post, we’re going to walk through the available documentation, which documentation should be used at what points, and then walk-through two use cases of using the documentation to perform a task.

PowerCLI Objects

PowerCLI allows us to access two different types of objects, .Net and vSphere. It’s important to know about these two object types and how to interact with them to understand what documentation should be used at what points.

To summarize the two objects quickly, the .Net objects are what PowerCLI high-level cmdlets interact with. Example: Get-VM returns back a UniversalVirtualMachineImpl .Net object. The vSphere objects are what the low-level cmdlets interact with, which is a direct connection to the vSphere Web Services API. These vSphere objects are accessible through Get-View and when referencing a .Net object’s ExtensionData property. Example: (Get-VM).ExtensionData returns back a VirtualMachine vSphere object.

If there’s a question about what object type we’re interacting with, we can verify the object type by using either the object level method of ‘GetType’ or with the ‘Get-Member’ cmdlet. Here’s how we can use the GetType method against the three examples I’ve already mentioned:
Example: Retrieving an Object's Type

These two object types also have their own sets of documentation. The .Net objects are available in the “Types” section of the PowerCLI Cmdlet Reference. The vSphere objects are available in the vSphere Web Services API Reference. The vSphere API has two main object types we’ll want to become familiar with, Managed Objects and Data Objects. Think of Managed Objects as the top-level inventory items, such as Datacenters, Clusters, Hosts, and VMs. It’s also worth noting that Managed Objects can also be services, such as the EventManager and ScheduledTaskManager, but we won’t be using them as part of this blog post. We can then think of Data Objects as the child objects that make up the top-level Managed Objects.

If you want to learn some more about these two objects and how they pertain to PowerCLI, PowerCLI mastermind Luc Dekens and I walked through these in a VMworld session last year: A Deep(er) Dive with PowerCLI 10 (VIN1992BE)

Documentation Lingo

At first glance, the documentation for both PowerCLI and the vSphere APIs can be a little overwhelming. There’s a lot of information available to consume. Let’s cover the main sections that are consistently available for both object types. These sections are: Property of, Parameter to, Returned by, Extends and/or Extended by, and Properties. “Property of” means that this particular object will be returned as a property for the listed objects. “Parameter to” means this object can be used as input for a particular cmdlet and/or method. “Returned by” means that a particular object will be the response by a cmdlet and/or method. Then we have “Extends” and/or “Extended by”, which is interesting because these can actually add properties to the given object which may not be listed in the documentation since it can change based on the object being referenced. Lastly, there are the “Properties” which are the items and objects that make up each object. Every time you get an object based response in PowerCLI, you’ll find those properties.

Next, we’re going to put all of this information to use in order to solve an issue where we’re looking for more information about a VM’s disk space and its associated filesystem.

Disk Space Utilization – .Net Object

For the first object type, we’ll be working with the .Net objects. We’ll want to start by referencing the PowerCLI documentation, known as the cmdlet reference. Instead of diving right in on the cmdlet list, we’re going to instead take a look at the Types. Since, at the root of the request, we’re looking for information about a VM, we’ll start with the VirtualMachine object. There, we can see all of the available properties including some that are relevant to our task such as: HardDisks, UsedSpaceGB, and ProvisionedGB. We can also take note of a deprecation notice for the HardDisks property which, as part of the Type column, refers us to the HardDisk object. Moving to the HardDisk object page, we can see some additional properties we might want to reference by the names of CapacityGB and CapacityKB. We’re not quite ready to move to coding just yet, we haven’t found any filesystem information. There’s one other section, that’s part of the VirtualMachine object, we should explore. This is the VMGuest object. Here we can see properties that have been pulled from VMware Tools, including one very interesting property for the our task: Disks. This property is related to the DiskInfo object. On the DiskInfo object page, we can see properties such as Path, Capacity, FreeSpace, CapacityGB, and FreeSpaceGB.

Quick recap, based on the request for hard disk and filesystem of a VM, we’re going to be interested in the following properties:

Object Property
VirtualMachine UsedSpaceGB
VirtualMachine ProvisionedSpaceGB
HardDisk CapacityGB
DiskInfo Path
DiskInfo CapacityGB
DiskInfo FreeSpaceGB

We now know what information we’re looking to retrieve, so we can start figuring out what code we can use to retrieve this information. The two main areas we’ll be concerned with are the “Property of” and “Returned by” sections. For the first two properties, we can use the Get-VM cmdlet to return those. Due to the deprecation of the HardDisk property, we have to use the Get-HardDisk cmdlet to return CapacityGB. Then, for our last three properties, we can use the output from the original Get-VM cmdlet. We know this because the DiskInfo object is a property of VMGuest, which just happens to be a property of VirtualMachine.

We can break it down to be the following properties:

Cmdlet Property Path
Get-VM UsedSpaceGB
Get-VM ProvisionedSpaceGB
Get-HardDisk CapacityGB
Get-VM Guest – Disks – Path
Get-VM Guest – Disks – CapacityGB
Get-VM Guest – Disks – FreeSpaceGB

Here’s what it looks like in PowerCLI code:

Here’s what it looks like in our PowerShell session:
Example: Disk Information from .Net Object

Disk Space Utilization – vSphere Object

For the second object type, we’ll be working with the vSphere objects. vSphere objects are vSphere Web Services API based, which means that we’ll be using a different set of documents to pull the same data. This document is known as the vSphere Web Services API Reference.

Taking a look at our request from the vSphere API level, we will again want to start at the VirtualMachine Managed Object. We can immediately notice a larger amount of data available to consume, since accessing the API gives us access to all of the available information. We’ll first want to start in the storage property, which leads us to the VirtualMachineStorageInfo data object. We can see there’s a property of perDatastoreUsage which is related to the VirtualMachineUsageOnDatastore object. This object has two properties we’re interested in, committed and uncommitted. The committed property will represent the used space amount, while the sum of committed and uncommitted will represent the provisioned space amount. Note, both of those properties are referenced in bytes so there will need to be some conversion done later.

Next, we’re looking for information about the hard disk itself. This is a multi-step process. Referencing the VirtualMachine object, we can see the layoutEx property contains information about the files that comprise a VM. The layoutEx property aligns with the VirtualMachineFileLayoutEx object, which has the property of disk. This disk property aligns with the VirtualMachineFileLayoutExDiskLayout object which gives us a key property. By reading the description of the key property, we can see that this key matches up to a VirtualDevice object which also has a key property. In reading through the available properties, we’re missing the property we’re looking for, which is a capacity-based property. This is where the ‘DynamicData’ comes into play. At the bottom of the properties, it specifies that some additional properties could be inherited by “DynamicData”. This is where the “Extended by” section comes into play. For our request, we can see that the VirtualDevice object is extended by the VirtualDisk object. When we look at the VirtualDisk object, we see the property that we’re looking for: capacityInBytes! At this point, we have our property but we don’t know how to retrieve it. Using the “Property of” section, we can backtrack to the VirtualMachine object. VirtualDisk is extended by the VirtualDevice object. The VirtualDevice object is a property of the VirtualHardware object. The VirtualHardware object is a property of the VirtualMachineConfigInfo object. Which takes us back to the VirtualMachine object, since the VirtualMachineConfigInfo is a property of the VirtualMachine object.

Last, we’re looking for filesystem-based information. Similarly to the .Net object, the VirtualMachine object has a guest property which is a GuestInfo object. The GuestInfo object has a property of disk, which is a GuestDiskInfo object. The GuestDiskInfo object has the capacity, diskPath, and freeSpace properties we’re looking for.

Attempting a quick recap, based on the request for hard disk and filesystem of a VM, we’re going to be interested in the following properties of the vSphere objects:

Object Property
VirtualMachineUsageOnDatastore committed
VirtualMachineUsageOnDatastore uncommitted
VirtualMachineFileLayoutExDiskLayout key
VirtualDisk capacityInBytes
GuestDiskInfo diskPath
GuestDiskInfo capacity
GuestDiskInfo freeSpace

Since we’re only going to be working with the root VirtualMachine object, we can move right over to the code. We can access the vSphere object in two ways, either through the usage of the Get-View cmdlet or through an object’s Extension Data. Once we have established that object in a variable, the experience is the same.

The two ways to retrieve the vSphere object for a particular VM can actually be extended into three ways, depending on what you are most comfortable with:

We can break it down to be the following cmdlets and properties:

Cmdlet Property Path
Get-VM | Get-View storage – perDatastoreUsage – committed
Get-VM | Get-View storage – perDatastoreUsage – uncommitted
Get-VM | Get-View layoutEx – disk – key
Get-VM | Get-View config – hardware – device – capacityInBytes
Get-VM | Get-View guest – disk – diskPath
Get-VM | Get-View guest – disk – capacity
Get-VM | Get-View guest – disk – freeSpace

Here’s what it looks like in PowerCLI code:

Here’s what it looks like in our PowerShell session:
Example: Disk Information from vSphere Object

Summary

Documentation is often an overlooked part of the PowerCLI development process. PowerCLI allows us to work with both it’s own set of objects as well as the entire set of vSphere API objects! This blog post discussed the differences between those objects, where to find the documentation to interact with those objects, how to read the documentation, and wrapped up with an example of fulfilling a request using both types of objects.

Let us know in the comments what type of scenario you would like walked through for the next documentation based blog post!

Moving a Datastore Cluster to a New Folder

1 Reply

We often get lots of interesting requests about figuring out how to automate something. The latest request was about how to move a datastore cluster between folders. This is the type of automation action which probably doesn’t need to be used all that often and is more aesthetic in nature than anything else. However, the interesting part is that, this request came from someone that found out they couldn’t perform the action in the UI. So, PowerCLI to the rescue!

Move-DatastoreCluster

PowerCLI doesn’t have a high-level cmdlet for this action, so we’ll be creating our own. To perform this action, we’ll be using a method that’s available in the vSphere API known as “MoveIntoFolder.” We can see some additional information about this method in the VMware Code API Explorer: MoveIntoFolder Method

I have created and shared a script on the PowerCLI Community repository and the VMware Code Sample Exchange which takes that “MoveToFolder” and wraps it in an advanced function we can call with: Move-DatastoreCluster

Example Usage

The script will need to be, what’s known as, dot sourced so that the advanced function is available in our current PowerShell session. From that point we will use the ‘DatastoreCluster’ parameter to pass a Datastore Cluster and the ‘Destination’ parameter to pass a folder.

Putting this altogether looks a bit like the following:
Move-DatastoreCluster Example Code

Summary

PowerCLI is a great tool to use when automating VMware environments. In the case of Datastore Clusters, we can actually use PowerCLI to perform tasks which aren’t available in the vSphere Client! The Move-DatastoreCluster script has been shared and presents an advanced function, of the same name, which allows us to move Datastore Clusters between the available folders.

If this is a function you’d like to see added to PowerCLI, head out to the public feature request site and upvote the following idea: Enhancement for moving inventory items Datastore Cluster

Obtaining Specific PowerCLI Versions from the PowerShell Gallery

1 Reply

The recommendation is to always be on the latest and greatest version of PowerCLI. However, whether it be for testing and validation or to possibly workaround an issue, there are instances where you may need to use an older version.

The PowerShell Gallery has the potential to make this process incredibly easy when using the RequiredVersion parameter for both Install-Module and Save-Module. These cmdlets download and/or install the indicated module at the specified version. The issue, especially with PowerCLI, comes in how the dependent modules are handled. This is because, in most cases, the module dependencies are specified to be obtained at a particular level or newer.

Example PowerCLI Dependency Listing:
PowerCLI Module Dependencies

This means if you want to download PowerCLI 6.5.4 with either the Install-Module or Save-Module cmdlets, the end result will not actually give you the requested version of PowerCLI. You would only receive the top-level VMware.PowerCLI module at version 6.5.4. All of the module dependencies which make up the PowerCLI 6.5.4 release will be at the latest and greatest version.

So, how can we properly download prior versions of PowerCLI?

Introducing Save-PowerCLI

Dimitar Milov, a PowerCLI engineer, came up with a function to address the issue and shared it in the comments on the PowerShell Gallery page for the VMware.PowerCLI module. From that point, I added a couple new features and shared it in both the PowerCLI Community repository and the VMware Code Sample Exchange.

Save-PowerCLI In Action

Demo: Save-PowerCLI Usage

Save-PowerCLI Code

Known Issues

There are a couple issues I’ve noticed when testing this against various versions of PowerShell.

  • Older versions of PowerShellGet (Example: 1.0.0.1) will fail because it can’t handle the formatting of one specific PowerCLI version.
    • Workaround: Update PowerShellGet. Example: Install-Module -Name PowerShellGet -Force
  • Newly released PowerCLI modules can be found downloaded, even if they did not exist at the time of the specific version release.

Summary

We always recommend how everyone should be on the latest and greatest version of PowerCLI. However, we also recognize that isn’t always possible. Whether it be for testing and validation, working around known issues, and so forth, there are reasons and needs to be able to obtain prior versions of PowerCLI from the PowerShell Gallery. The Save-PowerCLI function can streamline the download process of retrieving those specific versions of PowerCLI.

Let us know what you think of this function in the comments!

New Release: PowerCLI Preview for VMware Cloud on AWS

1 Reply

It’s a big week for PowerCLI! We’re closing out 2018 with several new releases. The new PowerShell DSC Resources for VMware came out last week. PowerCLI 11.1.0 was released earlier today. Now, we also have a brand-new Fling to help bridge the gap between the low-level cmdlets already available and the high-level cmdlets that are so easy to use. The PowerCLI Preview for VMware Cloud on AWS adds 14 new high-level cmdlets which are used in combination with the existing VMware.VimAutomation.VMC module.

What do I mean by ‘high-level’ cmdlets? There are generally two forms of cmdlets available through PowerCLI, high-level and low-level. High-level cmdlets abstract the underlying API calls and provide an easy to use and understand cmdlet, like Get-SDDC. Based on that, you can assume the output will be SDDCs within your VMware Cloud on AWS environment. However, every API call does not have a corresponding high-level cmdlet and that’s where the low-level cmdlets come into play. Low-level cmdlets interact directly with the API and therefore have complete coverage of the available API calls. An example of a low-level cmdlet would be Get-View, or in the case of the VMC module it would be Get-VmcService. More information about the low-level cmdlet usage of the VMC module is available in the following blog post: Getting Started with the VMware Cloud on AWS Module

Why is this being released as a fling? Much like the NSX-T preview module released earlier this year, we’re trying a new approach to creating cmdlets based on the APIs. Essentially, we take the VMC API swagger specification and programmatically create the entire module. It’s early in this new development process and we know there is the potential for issues and things that may or may-not make sense.

Another reason for it being a fling, we need your feedback! What cmdlets are you using the most? What should the output look like? What cmdlets aren’t working the way you think they should? What cmdlets are missing? As well as any other feedback you can come up with! The preference is to leave the feedback on the Fling’s comments page. However, if you post it as a comment here, I’ll make sure the right people receive it.

With that said, let’s get started using this new module!

Getting Started

Before we dive right in, the following section is going to be using a Windows environment. However, both the existing VMC module as well as the new VMC Preview module are multi-platform and can be used with PowerShell Core!

First, we’ll need to head out to the VMware Flings site, browse for the fling and download the zip file. Direct link: PowerCLI Preview for VMware Cloud on AWS

Next, extract the module and place it into one of your $PSModule directories. Better yet, do it with PowerShell:

We can then verify the module was placed in the proper location and is available for us to use:

VMCPreview Module Install Process

Note: If you don’t see those two modules, you probably need to install the latest version of PowerCLI. Walkthroughs on how to do that are available:

Now that we can see the module, I would suggest browsing through the new cmdlets available. We can do that with the following command:

Listing the available commands

One last step before starting to use the new cmdlets, we need to authenticate to the VMware Cloud on AWS service. This requires the Connect-VMC cmdlet, which is available as part of the VMware.VimAutomation.VMC module, and our Refresh Token from the Account section of the VMware Cloud on AWS Cloud Console. We can then authenticate with the following command:

We are now authenticated and ready to start pulling information from the environment. Following along with the prior blog post, let’s start by pulling information about our organization. We can do that with the Get-Organization cmdlet.

Get-Organization Usage

We can clean up the output through the use of the Select-Object cmdlet with the following command:

Get-Organization Details

Another item we looked at in the last blog post, and the next logical step, SDDCs. The Get-Sddc cmdlet can be used, however it does require the addition of an Organization ID. I’ll store the Org ID from the prior step in a variable named orgId and then just jump to the cleaned-up view by using the following command to list the SDDC/s in the Org:

SDDC Example Output

Last thing I want to cover, these cmdlets make use of objects just like standard PowerCLI cmdlets do. Specific to the SDDC, we can access additional information such as what AWS Region and Availability Zone/s are in use, NSX information like the Manager URL (which will be important in a later blog post), and what the vCenter URL is. All of that information happens to be available in the ResourceConfig property of an SDDC. We can retrieve that information with the following command:

Additional SDDC Object Information

Summary

There’s a great new fling available called the PowerCLI Preview for VMware Cloud on AWS. This fling adds an additional 14 high-level cmdlets for VMware Cloud on AWS, like Get-Organization and Get-Sddc, which means that automating VMware Cloud on AWS has never been easier!

As with all of our Flings, please leave feedback on the Comments section! We want to know what you think. What cmdlets are you using the most? What should the output look like? What cmdlets aren’t working the way you think they should? What cmdlets are missing? As well as any other feedback you can come up with!

New Release: PowerCLI 11.1.0

2 Replies

As 2018 comes to a close, we have one more release for you in the form of PowerCLI 11.1.0! If you’re keeping track, that brings us to 6 official PowerCLI releases in the 2018 calendar year. To quickly summarize 2018: PowerCLI has gone multi-platform, added 2 new modules, added 25 new cmdlets, and supported new VMware product versions faster than ever! There were also quite a few other updates that involve PowerCLI, such as the Fling modules containing high-level cmdlets for NSX-T and VMware Cloud on AWS, the Code Capture addition to the HTML5 Web Client Fling, and the brand-new PowerShell DSC Resources for VMware!

PowerCLI 11.1.0 comes with the following updates:

  • Added support to the SRM module for MacOS and Linux
  • Added support for SRM 8.1
  • Updated 2 Storage module cmdlets
  • Updated DeployAutomation and ImageBuilder module dependencies

Let’s take a look at some of the updates.

Site Recovery Manager Module Updates

The VMware.VimAutomation.SRM module is the newest module to be converted to for multi-platform support. That means this module can now be used with PowerShell Core on MacOS and Linux! This module has also received updates to support Site Recovery Manager 8.1. More information on this new version of SRM can be found at the following: VMware Site Recovery Manager 8.1 Release Notes

PowerCLI and SRM Compatability

Storage Module Updates

The VMware.VimAutomation.Storage module received a couple updates to fix some issues. The Get-VsanDisk cmdlet has been updated to now also list the vSAN disk where the Witness Component resides. An update has additionally been made to the Start-SpbmReplicationTestFailover cmdlet so that it no longer requires the VvolId parameter.

Summary

PowerCLI 11.1.0 has been released and completes the 6th release of the year! This new release includes support for Site Recovery Manager 8.1, as well as converting the SRM module over for multi-platform support. Two storage cmdlets have been updated to fix some reported issues. Lastly, some dependencies for the DeployAutomation and ImageBuilder modules have been updated.

For more information on changes made in VMware PowerCLI 11.1.0, including improvements, security enhancements, and deprecated features, see the VMware PowerCLI Change Log. For more information on specific product features, see the VMware PowerCLI 11.1.0 User’s Guide. For more information on specific cmdlets, see the VMware PowerCLI 11.1.0 Cmdlet Reference.

Remember, updating your PowerCLI modules is now as easy as: Update-Module VMware.PowerCLI

Example: Update-Module -Name VMware.PowerCLI

Let us know in the comments what you’re most excited about!

New Community Module for Tag Management

Leave a reply

vSphere tags, in my opinion, are one the unsung heroes when it comes to VMware environment management. They’re extremely versatile. They can be used as labels. They can be used to group similar objects and/or multiple object types together. They can be used to apply policies. There are third party products also using them. I’ve seen lots of companies use them in lots of creative ways. However, automating their usage can be slow in some environments and not available at all in larger environments.

There’s a new module in the PowerCLI Community Repository to help against some of those issues. This new module, named VMware.Community.CISTag, makes use of the vSphere REST API to manage tags in a more performant manner.

The VMware.Community.CISTag module includes the following advanced functions:

Function Name Synopsis
Get-CISTag Gathers tag information from the CIS REST API endpoint
Get-CISTagCategory Gathers tag category information from the CIS REST API endpoint
Get-CISTagAssignment Displays a list of the tag assignments from the CIS REST API endpoint
New-CISTag Creates a new tag from the CIS REST API endpoint
New-CISTagCategory Creates a new tag category from the CIS REST API endpoint
New-CISTagAssignment Creates new tag assignments from the CIS REST API endpoint
Remove-CISTag Removes a tag from the CIS REST API endpoint
Remove-CISTagCategory Removes tag category information from the CIS REST API endpoint
Remove-CISTagAssignment Removes tag assignments from the CIS REST API endpoint

There are also some requirements that are needed in order for this module to work:

  • vCenter 6.0 or newer
  • PowerCLI 6.5.3 or newer
  • Active vCenter CIS service connection, using Connect-CISServer
  • Preferred: Active vCenter connection, using Connect-VIServer

Let’s take a quick look at how to get started using this module.

Accessing the Module

There are a couple ways to get access to this great module, all of which go through the PowerCLI Community Repository. One of the easiest ways is to load up the repository’s page, click on the green ‘Clone or download’ button, then clicking on ‘Download ZIP’. This downloads the entire contents of the repository to your local system.

Download PowerCLI Community Repository to Local System

Once the download is complete, unzip the files and browse to the ‘Modules’ directory. We are now going to copy the VMware.Community.CISTag folder and paste it in one of the directories that are listed in the PSModulePath variable. Doing this allows the module to be available for automatic importing by your PowerShell session!

By default, the PSModulePath variable contains the following directories:

  • $home\Documents\WindowsPowerShell\Modules
  • $pshome\Modules

In my environment, I have placed the module in the first of the above options. This is also where my PowerCLI modules are available.

Module Overview

The functions are written in a very similar format to the existing PowerCLI Tag cmdlets. If you’ve ever used the existing tag cmdlets, these operate in a very similar fashion and offer a very similar response. However, there are some changes that you should be aware of. The PowerCLI Tag cmdlets generally work with objects, whereas these functions work with names or IDs. This means you should test these new functions thoroughly before updating any existing scripts and/or workflows. Making use of Get-Help will greatly aide in the transition.

Overall, I noticed some good performance increases as well.

Example: Comparing an environment with 400 tags assigned, saw an improvement of roughly 25%
Performance test of listing tag assignments

There are some other features that have been added which can be used to achieve even more performance. The first, by using an object’s ID whenever possible. Most of the functions also feature TagId and ObjectId which can be referenced instead of the name parameters. This helps by cutting down on the amount of additional calls which are being made to translate a name into an ID value.

The second way to see even more performance improvement is through the usage of bulk actions. This applies specifically to the TagAssignment functions. The underlying API method allows multiple tags to be assigned or removed from a single object or a single tag can be assigned or removed from multiple objects. Therefore the New-CISTagAssignment and Remove-CISTagAssignment functions accept strings or arrays for Tag or Entity properties. There’s also the ability to further speed up the process by using object IDs too.

Example: Comparing the difference between the bulk assignment of a single tag against multiple VMs. Top example is name based, the bottom example is ID based.
Bulk action performance results

The last big note on improvements for this module, I have yet to run into any timeout issues, maximum results errors, and so forth.

Example: Comparing an environment with 1400 tags assigned, where the Get-TagAssignment cmdlet fails while the Get-CISTagAssignment succeeds
Example comparison with 1400 tags assigned

Summary

The CISTag module is a great new resource for anyone automating tag usage within their vSphere environment. By switching to the tagging methods available in the REST API, we’ve seen performance improvements, the ability to overcome timeout errors, and more!

Head out to the PowerCLI Community Repository, download it, and let us know in the comments how you’re putting it to use in your environment!

Getting Started with Desired State Configuration Resources for VMware

11 Replies

Today, we are happy to announce a brand-new and open-sourced way to manage your vSphere environment. The Desired State Configuration (DSC) Resources for VMware allows partners, automation engineers, DevOps teams, and system administrators a new way to apply standard configuration management processes through PowerShell DSC and PowerCLI!

Let’s take a walk through how we can get started using these DSC resources and apply our first configuration!

Desired State Configuration Resources for VMware Overview

PowerShell DSC has been out for a while, since Windows Server 2012 R2 as a matter of fact. To summarize in a single sentence: PowerShell DSC can manage and monitor a system’s configuration based on what’s known as configuration files, which happen to be written as PowerShell code. This is all made possible thanks to the Local Configuration Manager (LCM). LCM is the “engine” running locally on each of the target nodes that takes the configuration file, interprets it, and applies all the configured parts. These parts include a system’s configuration, in what manner the configuration is refreshed, and how often it is refreshed, just to name a few.

The above is important because the DSC Resources for VMware operate a little differently than a standard DSC configuration. The DSC Resources for VMware make use of a proxy LCM host. This is because the LCM cannot run on the VCSA (both vCenter and PSC based appliances) nor can it run on ESXi hosts. An important note about this proxy LCM host, it has to be Windows PowerShell based. Furthermore, only PowerShell 5.1 and PowerCLI 10.1.1 or newer will be supported.

Desired State Configuration Resources for VMware

This first release of the DSC Resources for VMware will be able to manage a couple different areas for both vCenter and ESXi hosts. They are as follows:

  • vCenterStatistics
    • Level
    • PeriodLength
  • vCenterSettings
    • EventMaxAge
    • TaskMaxAge
    • Logging Level
  • VMHostNtpSettings
    • NTP Server
    • NTPD Service Policy
  • VMHostDnsSettings
    • HostName
    • DomainName
    • Address
  • VMHostSatpClaimRule
    • RuleName
    • Transport
    • Description
  • VMHostTpsSettings
    • ShareScanTime
    • ShareForceSalting

Installation Overview

We now know what it is and what it can do, how about the installation? On the designated proxy LCM system, we will want to download the module from GitHub and make it available in one of our designated PSModulePath directories. The zip file is available through the following link: Desired State Configuration Resources for VMware

Here’s some code that can streamline the download and initialization process:

After we have installed the module we should be able to list the newly acquired module and import it into our active PowerShell Session:

Example: Importing the VMware.vSphereDSC Module

We can also verify the DSC resources we have available:

Example: Output of available DSC Resources

Next, we need to make sure the proxy LCM system can understand the DSC configuration files. This is done through the Windows Remote Management service. We can setup the WinRM service or verify that the WinRM service is setup with the following code:

In my environment, this system already had WinRM setup so I received the following message:
Example: Windows Remote Management Configuration

We should now be all set to start setting up DSC resources in our environment!

Managing an ESXi Host’s NTP

The DSC Resources for VMware repository has some pre-created configuration files which can be sourced to create the MOF file. The MOF file, which stands for Managed Object Format, is the output from a configuration file which has been compiled by the LCM. These configuration files are located in the repo at the following location: \Source\VMware.vSphereDSC\Configurations In my environment, I’ve created my own fork of the repository and cloned it to my local system where I’ll be referencing the files.

In our example, we’re going to setup DSC to manage an ESXi host’s NTP configuration. We can see some parameters and some settings by opening the VMHostNtpSettings_Config.ps1 file that’s located in the ESXiConfigs directory.

Input Type Input Name Input Description
Parameter Name Resource Name
Server Server Host Name
User ESXi host username
Password ESXi host password
Setting NtpServer NTP server/s the host will use
NtpServicePolicy Status for the NTPD service

For my lab environment, I’m going to update the NtpServer values and accept the service policy setting of ‘automatic’. I’m also going to apply this configuration at the ESXi host level, so my host name and server name will match.

We can do this with the following commands:

As part of the output, we should see the following MOF file having been created:
Example: Configuring and creating MOF file

We can then test the MOF file against our host with the following command:

Added to the output, I have also included another PowerShell session which is polling the host for the current NTP server/s and service policy:
Example: Pre-DSC Configuration

In the above example, notice the ‘InDesiredState’ property with a value of False.

Now, we’re ready to start applying our configuration. We do this with the following command:

After a few moments, we’re ready to check the current DSC configuration with the following command:

Again, I’ve added a second PowerShell session to show the current status of the host:
Example: Post DSC Configuration Status

For reference, this is the code I’m running to show the current status of the host’s NTP configuration:

In some later blog posts, we’ll take a look at some of the other areas of this module including applying configurations to multiple hosts, applying vCenter settings, applying values to multiple hosts in a vCenter, and some ways to apply better security practices to both the credentials and the MOF.

Summary

PowerCLI is back with a brand-new feature, Desired State Configuration Resources for VMware! These resources allow PowerCLI to make use of PowerShell DSC to define the configuration of a desired node. The DSC Resources for VMware can define ESXi host settings such as NTP servers, DNS servers, and TPS share scan times. We can also define vCenter settings such as statistics level and logging level. As an additional benefit, these resources are also open-source and community contributions are absolutely welcome!

Check out the Desired State Configuration Resources for VMware on GitHub and let us know what you’re looking forward to using DSC on most in your vSphere environment!

Improving PowerCLI Support with Get-ErrorReport

2 Replies

I am always surprised at the shock some people have when it comes to PowerCLI being supported by VMware! We highlighted this in a prior blog post: PowerCLI Support Breakdown However, in that blog post, there was one item that wasn’t covered which can really help streamline the process of receiving support. This item is a cmdlet by the name of Get-ErrorReport and it received a big update as part of PowerCLI 11.

Let’s walk through an example of creating a PowerCLI support bundle using Get-ErrorReport.

Receiving an Error

The first thing we need to do is receive an error! In this case, I’ll be using a known issue with the Move-VM cmdlet which occurs when attempting to move a VM into a vApp.

Example: Generating an error

The error we received was:

This is a pretty straightforward issue where the Move-VM cmdlet is not operating in the way which was been documented. We can now open a support request!

PowerCLI Support Bundle

Normally, when you open a support request, the first ask is for a support bundle from either the vCenter, an ESXi host/s, or even all of the above. Since this is a PowerCLI issue, those standard support bundles may not help. Plus, some of the more advanced PowerCLI troubleshooting options are not easy, or not readily available, in most environments. One example of which would be to use a tool like Fiddler or Wireshark to sniff the network traffic in order to determine what API methods are being used under the covers and hopefully identify the issue.

Instead of going through the process of installing Fiddler or Wireshare, we can retrieve all the required information by making use of the Get-ErrorReport cmdlet!

The Get-ErrorReport cmdlet has a couple important parameters we’re going to be making use of:
Note: If you’ve used Get-ErrorReport before, these parameters have changed

Destination Location of where the PowerCLI support bundle will be placed
IncludeServerLogs Specify whether we want to pull logs from the connected server
ProblemDescription Provide a description and/or support number
ProblemScript Scriptblock which contains the cmdlet causing the error

Continuing with our Move-VM example, we can use the following code to create our support bundle:

Example: Get-ErrorReport command being run

We can now take that output and upload it to our support request!

Support Bundle Examination

If you happen to be curious about what information is contained within the support bundle, like I was, we can unzip the bundle and read through the contents fairly easy. Note: this section is purely educational as the support engineer will handle the actual diagnosis.

The support bundle contains the following files:

  • PowerCLI-Main-Log.svclog
  • Powershell-Debug-Stream.txt
  • Powershell-Error-Stream.txt
  • Powershell-Info-Stream.txt
  • Powershell-Verbose-Stream.txt
  • Powershell-Warning-Stream.txt

The contents of those files should be fairly straight forward, with the exception of the first one. The PowerCLI-Main-Log.svclog is a collection of diagnostic traces. These traces contain all of the pertinent information about the cmdlets being used, how it is being interpreted by PowerShell, and then the underlying call to the vCenter. The svclog file can be opened with the Microsoft Service Stack Trace Viewer. This application is available as part of the Windows SDK, available here: Windows SDK Archive

The following screenshot is a look at the actual exception being returned by the API service:
Example: Reading the svclog exception

We can see the server response was an internal server error, which has a status code of 500. We can then further read through the individual trace to see the properties and methods being used. We also have the option to look at the traces before and after the call happened to see each of the steps being performed as part of the code entered in our $errorCode scriptblock.

Summary

PowerCLI is supported by VMware and the Get-ErrorReport cmdlet was recently improved in PowerCLI 11. The upgrade helps to streamline the support experience by creating a PowerCLI support bundle which can be provided to VMware support. This support bundle includes all of the required environmental information that VMware support will need to start troubleshooting the issue being reported.

The next time you need to open a support ticket on PowerCLI, make sure to use Get-ErrorReport and let us know your feedback!

login