PowerCLI Mastery, Volume 3

Phew, Volume 1 and Volume 2 down, lets wrap this monster up. See, I told you I wasn't going to leave you hanging for weeks to nail through all this.

So, picking up right from where we left off. We need to perform a configuration operation on an ESX host. Of the available properties we're looking at now, which is most likely to tell us what we can configure? That's right, the configManager property! If you guessed "config", you were close - the config property tells us _what_ the current configuration values are. The configManager object tells _how_ we can do the configuring (is that even a word?). Lets click on that.


Now we're cookin! AS you can see at the top of the page, the configManager object is a Data Object of Type 'HostConfigManager', the properties of which contain a whole bunch of Managed Objects. The task at hand is to modify a portgroup configuration, so let’s check out the 'networkSystem' property.



Here we see all the available properties and methods available for the HostNetworkSystem Managed Object. And low and behold, down the bottom we see the method by which we can modify a portgroup, UpdatePortGroup. We can see that 'networkSystem' is actually a Managed object, but we have to traverse the configManager _Data_ object to get there (because we need to provide the correct context for the managed object reference). Recalling that Get-View can only return _Managed_ Object references, in order to get the HostNetworkSystem Managed Object reference for our particular host, we have to again use Get-View but this time passing it in the networkSystem property of the configManager Data object. Which is a lot easier in PowerShell than it is in English.

$esxNetSys = $esxMoRef.configManager.networkSystem
$esxNetSysMoRef = Get-View $esxNetSys

Finally click on the UpdatePortGroup method, and hopefully we're done


OK, finally we see that in order to use the UpdatePortGroup method of a HostNetworkSystem Managed Object, we need to pass in a portgroup name as a string, and a portgroup as a... HostPortGroupSpec object??? WTF!!! Stu, you lead us all this way to a dead fucking end!!! There won't be anything left for Boche to mash at VMworld Europe 2009 by the time I'm done with you!!!

Breathe. Stay Calm. Focus. I have only given you 2 of the 3 tools needed for PowerCLI mastery. Now, we turn to the dark side... err I mean we turn to the SDK documentation, version 2.5 of which is online here.

The online raw SDK documentation is the equivalent of that goo they eat for breakfast in The Matrix - it contains all the things a PowerCLI Master's body needs. You can have a read of the text in the main window there if you want to get a much better explanation of the different object types that what I've given, or you can just jump in, find what you need, then get the fuck out. Yes, while the raw SDK documentation contains everything the body needs, reading it is also a bit like staring at the Sun. Do it for too long, and you'll go insane like that guy in Sunshine.

Open up the online SDK documentation site. Recalling our conversation about the types of object in the VI API, you can reasonably deduce that a 'HostPortGroupSpec' object is likely a Data object. So click on the "Data Object Types" link in the top left hand corner, wait for the list underneath to update then scroll down to find "HostPortGroupSpec", and click on it. This is the equivalent of the part of our PowerShell code where we do:

$pgspec = New-Object VMware.Vim.HostPortGroupSpec

Now where did I pull that “VMware.Vim.” from? We are using a native .net assembly given to us by the VI Toolkit, Vmware.Vim.dll. You probably haven't realised this up until now, I certainly didn’t until about a year ago, but the VI Toolkit is not just PowerShell - it's actually also a native .net wrapper for the VI API, that you can use with C# instead of compiling your own proxy dll from the VI web service. But you don't need to know the nuts and bolts of that - this is something I'm going to ask you to take on faith. You will eat your greens, you will look both ways when crossing the road, and you will know that the VMware.Vim.dll contains a reference for _every_ object available in the underlying API and then some. And for those sceptics out there who don't believe me, execute the following in any old PowerShell window on a box that you have PowerCLI installed on (and make sure u have a large row buffer ;)

$vimDll = [Reflection.Assembly]::LoadWithPartialName("VMware.Vim")
foreach ($type in $vimDll.GetTypes()){write-host $type.name}

Back to the SDK documentation and the code. Now we see what the properties of a HostPortGroupSpec are. There are 4, and all are mandatory. But what’s this, one of those properties is _another_ object, a "HostNetworkPolicy". So what do we need to populate one of those? Click on it and we'll see!

$pgspec.vswitchName = vSwitch0
$pgspec.Name = "VM Network"
$pgspec.vlanId = "0"
$pgspec.Policy = New-Object VMware.Vim.HostNetworkPolicy

OMG!!! We just opened up a Pandora's box. HostNetworkPolicy has 4 properties, _all of them other objects_! But before you bury your head in your hands, check out those red asterisks - anything with one of those is an optional parameter, which is everything in our case!. Since we're only interested in changing the nic order, which has to do with nic teaming, we're going to leave all properties except the nicTeaming property as empty. Which basically means that this portgroup will inherit the offload policy, security policy and shaping policy of the virtual switch that it is created on. We can see that the nicTeaming property requires a "HostNicTeamingPolicy" object. Click through to that.

$pgspec.Policy.NicTeaming = New-Object VMware.Vim.HostNicTeamingPolicy

Once again we see a whole bunch of properties, all optional as denoted by the red asterisk. We are interested in changing what vmnics are active, standby and unavailable for this portgroup, so we'll need to populate the nicOrder property. Which as you can tell by now (see, you get the hang of this pretty fast), is another object named 'HostNicOrderPolicy'. So click on through...

$pgspec.Policy.NicTeaming.nicOrder = New-Object VMware.Vim.HostNicOrderPolicy

Finally! We're at the end of the line. No objects here, just data, and again all optional. As you can see, there are only 2 properties - activeNic and standbyNic. Any nics present on the parent vSwitch but not part of either of these properties is by definition "unused". So in our example, I'll tell you we have 4 vmnics on the parent virtual switch. On the parent virtual switch, all 4 are active (again, this is all in the imaginary pre-existing host this script will be run against). But in this portgroup, we only want vmnic1 and vmnic2 to be active, and vmnic0 and vmnic3 standby. We can see in the SDK documentation that activeNic and standbyNic need values of type 'string array', so we simply do the following to make a valid assignment:

$pgspec.Policy.NicTeaming.nicOrder.activeNic = @("vmnic1","vmnic2")
$pgspec.Policy.NicTeaming.nicOrder.standbyNic = @("vmnic0","vmnic3")

OK, now we've finally populated our HostPortGroupSpec object with all the required properties, objects, data types and data, it's time to finish off with a call to the UpdatePortGroup() method, via the HostNetworkSystem Managed Object reference we setup in the 3rd line of the script, with the required parameters we got from the MOB. Those being the name of portgroup we want to update, and a HostPortGroupSpec object containing the information we want to apply.

$esxNetSysMoRef.UpdatePortGroup($pgspec.Name, $pgspec)

Job done.

Now you understand why I'm such a huge fan of PowerCLI. I've had the displeasure of coding against the VI API directly in C#, and Shyam did most of the heavy lifting in Java when we developed statelesx. It often seems convoluted and contradictory, you often find that what you thought would be a simple operation based on another seemingly similar task, is actually anything but. As you've seen in this example, there are layers upon layers upon layers, you can get lost pretty easy. But thanks to the foresight of the VI Toolkit team to expose the underlying VI API via Get-View and provide us with VMware.Vim.dll assembly, anything is possible with the Power of Shanklin. Ooops I mean the Power of Shell ;-). But the Power of Shanklin does compel you.

Hopefully now you can not only do whatever you want to with PowerCLI, but also look at any script that the forum wizards may post, and understand exactly what they’ve done and how you might tweak them to your needs.

Now go forth and conquer. You are Jedi.