Monday 9 February 2009

PowerCLI Mastery, Volume 1

OK, this one has been a looooooooooong time coming. I've been meaning to take a shot at conveying the advanced features of the VI SDK as applied to PowerShell for quite some time now. When Carter corrected me some months ago with regards to what is and isn't possible with PowerCLI (in the first statelesx video, about 1 minute in I mistakenly suggested there was something it _couldn't_ do :-), I've thought I really should get this info out there. Whether I will succeed in this post and the ones that follow is of course for you to decide (this is way to long for a single post), but I'm going to take you through what I think is the fastest way to get your head around the _entire_ SDK. That's right, the whole fucking thing. For as you will see, when you conquer a small piece of the SDK, the rest falls like dominoes.

Now the usual caveats. Yes there are other, possibly more efficient ways to find this info, or write the example code in this article. And some of the things I say will make people who work for Carter cringe. But I've done all this intentionally for the sake of simplicity. And about the the term 'PowerCLI' - Carter dropped it once on Twitter, and all bloggers being opportunists at heart, I'm going to seize on that one with both hands. Besides, it sounds a lot cooler than the VI Toolkit (or at least it more specifically refers to a part of the VI Toolkit). But to avoid any confusion, yes I am talking about this.

It's going to be difficult to go further without the help of an example, so let’s use an example of an operation that there is no native cmdlet for (yet) - modifying the nic order of a portgroup. I don't know how often other people do this, but every ESX blade built where I work gets this treatment. And there are hundreds of those.

Here's the code:
$esxMoRef = Get-VMHost esxbox.corp.com | % {Get-View $_.Id}
$esxNetSys = $esxMoRef.configManager.networkSystem
$esxNetSysMoRef = Get-View $esxNetSys

$pgspec = New-Object VMware.Vim.HostPortGroupSpec
$pgspec.vswitchName = "vSwitch0"
$pgspec.Name = "VM Network"
$pgspec.vlanId = "0"
$pgspec.Policy = New-Object VMware.Vim.HostNetworkPolicy
$pgspec.Policy.NicTeaming = New-Object VMware.Vim.HostNicTeamingPolicy
$pgspec.Policy.NicTeaming.nicOrder = New-Object VMware.Vim.HostNicOrderPolicy
$pgspec.Policy.NicTeaming.nicOrder.activeNic = @("vmnic1","vmnic2")
$pgspec.Policy.NicTeaming.nicOrder.standbyNic = @("vmnic0","vmnic3")

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

But how did I know those methods and properties are available, what are required and optional values, and what type of values to use? It's not by remote chi, the force, and I didn't pull them out of my arse. I used a combination of Get-View, the MOB and the SDK documentation to do this. No it's not as scary as it sounds, anyone can be on their way to PowerCLI mastery with these tools.

The Get-View cmdlet is part of PowerCLI, and is the window to the underlying VI API. When you need to do something that isn't available via the usual PowerCLI cmdlets, you can use Get-View to acquire an object reference that the underlying API exposes. And of course with PowerShell natively supporting .net objects, you can then access all the associated methods and properties of those underlying objects. That's all well and good, but how do we know what underlying objects, methods and properties we need to use to get our desired result? Continue reading in our next exciting episode, when you will be introduced to the MOB. No, not the sleeps with the fishes type mob, the Managed Object Browser.

No comments: