PowerCLI

Instant Clone PowerCLI cmdlets Best Practices & Troubleshooting

08/06/2015 by William Lam Leave a Comment

I was fortunate to have been given early access to the VMFork (Instant Clone) PowerCLI cmdlets to help provide early feedback and usability improvements before it was released to customers. Having spent some time with the Fling, I have learned a thing or two about how Instant Cloning works and some of the caveats or gotchas while creating the customization scripts that are used as part of the Instant Clone workflows. I wanted to put together a quick reference on some of my findings as well as well as other recommendations from Engineering who have worked closely with the Instant Clone feature.

The idea is to have this as a living document which I will update as new tips and tricks are identified.

Best Practices

Ensure VMware Tools is installed inside the guestOS and also good time to ensure you are running the latest
Both Pre/Post Customization scripts are uploaded to /var/tmp by the Enable-InstantCloneVM cmdlet
Do not delete Child VMs directly on ESXi, manage it through vCenter Server. There is currently a known issue in which deleting Child VMs will also delete the Parent VM's disk
Additional custom variables can be passed to the post-customization script by adding to the -ConfigParams array of variables.
- An example could be passing in two custom properties called "foo" and "bar" which would look like:
@{foo = "val1";bar ="val2"}
- To retrieve the variable "foo" and "bar" from within the post-customization script, you would issue the following commands:
vmtoolsd --cmd "info-get guestinfo.fork.foo"
vmtoolsd --cmd "info-get guestinfo.fork.bar"
A Forked Child VM will also have a duplicate MAC Address which needs to be updated as it is not automatically picked up.
modprobe -r vmxnet3;modprobe vmxnet3

A Forked Child VM may also have identical kernel entropy pools which means semi-predictable RNG, possibly including TCP sequence numbers (Submited by George Hicken)
A Forked Child VM's system clock may also be out of date (until you call hwclock --hctosys or similar) which can cause problems with ordering of file timestamps (Submited by George Hicken)
Shared host keys if you are using a PKI system or identical asset identifiers in the case of Windows and any sort of AD infrastructure would also need to be either removed prior or updated after a Child VM is created (Submited by George Hicken)
Instant Cloning Nested ESXi has been a bit tricky due to a known issue with the VMware Tools for Nested ESXi. I have found that manually preparing the guest prior to Instant Cloning has yield better results. For more information on how to Instant Clone Nested ESXi, check out the blog post here
Powering off the Parent VM means that the VM is no longer quiesced and this also means that new Child VMs can not be instantiated until all existing Forked Child VMs have been powered off and the Parent VM has been re-quiesced
If you plan on downloading or installing additional software packages on the Parent VM, it is recommended that you perform that operation directly in the VM and not within the pre-customization script. I have noticed that if pre-customization takes too long, the quiesce operation eventually fails even though the operations within the pre-customization script executed successfully.
To ensure Forked Child VMs do not contain duplicate disk ID's from Parent VM such as setting up a VSAN environment using Instant Clone Nested ESXi, add the disks after Forked Child VMs have been created.
For additional OS Customization Scripts, be sure to check out the Instant Clone community customization script repository and consider contributing back scripts that you have developed.
When you hard reset or power off on a child VM it will respawn from the parent, soft resets will not respawn (Submitted by Alan Renouf)

Troubleshooting

Instant Clone guestOS logs are stored in /var/tmp/quiesce.log
Consider enabling tracing within your customization scripts. An example of this for a shell script is using
set -x

Add additional echo or print statements like Start/Stop of certain sections like Pre/Post which can aide in reviewing the Instant Clone logs as seen in the screenshot above
For Instant Cloning Nested ESXi guestOSes, I recommend taking a snapshot after you have prepared the guest and removed any system specific information. This allows you to quickly revert back to a known state for ease of debugging. I found this to be very useful to be able to start back a known clean state while developing the customization scripts for Instant Cloning Nested ESXi
A known issue that is mentioned in the documentation of the Instant Clone cmdlets is after enabling a ParentVM for Instant Cloning, is that it is no longer available for migration to another ESXi host. The reason for this is that after powering off the VM, the "parentEnabled" boolean flag is still set to "true" which prevents the migration. Currently, there is not a work around but hopefully this will be resolved in a future update of the cmdlets. You can see this by running the following PowerCLI snippet:
(Get-VM "MyParentVM").ExtensionData.Config.ForkConfigInfo

Using PowerCLI to invoke Guest Operations API to a Nested ESXi VM

07/14/2015 by William Lam 1 Comment

In my opinion, the Guest Operations API in vSphere is still one of the most powerful Virtual Machine capabilities that is available to vSphere Administrators and anyone else who integrates with the vSphere Platform. The Guest Operations API allows users to perform guest operations (running commands, transferring files, etc) directly within the guestOS as if you were logged in. Valid guest credentials are still required and once authenticated, the operations are then proxied through VMware Tools. Networking is not even required which makes this a handy feature for troubleshooting and can even extend into application level provisioning through a single API.

Obviously, I am a huge fan of this capability and have used it myself on more than one occasion. However, one limitation that I discovered awhile back when using the Guest Operations API with Nested ESXi VMs is that it threw some very strange memory related errors. It was only recently did I find out that there was a known issue with the VMware Tools for Nested ESXi, both the installable VIB and the pre-installed version in ESXi 6.0 on how the guest operations are executed. The good news is that for now, there is a simple workaround that can be applied when using the Guest Operations API.

You will need to add the following option, which runs the command under a specific resource group in the ESXi Shell:

'++group=host/vim/tmp'

Here is an example if I were to run the 'echo' command:

/bin/echo '++group=host/vim/tmp' "hello world"

A more interesting example would be to issue ESXCLI commands using the Guest Operations API, perhaps configuring the welcome message?

/bin/python '++group=host/vim/tmp' '/bin/esxcli.py system welcomemsg set -m "vGhetto Was Here"'

Notice, we need to pass in the resource group command to the "python" binary versus ESXCLI binary. The reason for this is that /bin/esxcli is really just a symlink to /bin/esxcli.py which is just a Python wrapper. The actual command being launched is the python interpreter and the arguments to the command is /bin/esxcli.py and the ESXCLI arguments itself.

For those who prefer to consume the Guest Operations API without having to directly use the vSphere API, you can use PowerCLI and use the Invoke-VMScript cmdlet. The problem with that is due to the way the cmdlet has been abstracted, the necessary underlying API details can not be accessed due to certain assumed defaults which can not be overridden or extended. This is a general problem that I have seen in more than one occasion where the abstraction is to make the consumption of the API simpler but in certain cases, it can also inhibit the use of the underlying API feature.

In this case, we will actually need to call into the vSphere API and using PowerCLI as an example, I have created a script called runGuestOpsInNestedESXiVM.ps1 which implements the specific Guest Operations APIs to issue commands to a Nested ESXi VM.

Here is an example of running the script and configuring the welcome message using ESXCLI:

Retrieving statistics for a Distributed Virtual Port using the vSphere API & PowerCLI

06/01/2015 by William Lam 2 Comments

Over the weekend I received an email from a fellow colleague over in the NSBU who was interested in retrieving statistics on an individual Distributed Virtual Port using the vSphere API and had asked if I had done this before. Although I have written about using the vSphere API to access various properties of a Distributed Virtual Switch (here & here) and migrating from a Virtual Standard Switch (VSS) to Distributed Virtual Switch (VDS) and from a VDS back to VSS (here & here), I have not done a whole lot with the vSphere API with regards to individual Distributed Virtual Ports.

Having said that, with the easy to use PowerCLI Distributed Virtual Switch cmdlets being available, it is actually not too difficult to retrieve this information using the vSphere API. For those of you who have not worked with a Distributed Virtual Switch before, to view the statistics of an individual Distributed Virtual Port, you must drill down into a specific Distributed Virtual Portgroup which you can find using either the vSphere Web/C# Client. Below is a screenshot from my vSphere Web Client.

To retrieve information on a Distributed Virtual Port using the vSphere API, you can refer to the DistributedVirtualPort property. Within this object, there is a state property which you can then drill down further to retrieve statistics using the stat property. If you would like to be able to pull other properties as shown in the screenshot, you can use the runtimeInfo property which provides additional information on the Distributed Virtual Port such as connected entity, MAC Address, VLAN ID, state, etc.

The following two PowerCLI VDS cmdlets: Get-VDPortgroup & Get-VDPort will help us retrieve the information we are looking. However, out of the box these cmdlets do not support pulling statistics for a Distributed Virtual Port. To do so, we will need to access the ExtensionData property which will allows us to access the underlying vSphere API from the PowerCLI object.

Below is a simple PowerCLI script which connects to a vCenter Server and retrieves a specific Distributed Virtual Portgroup (dvPg) that we are interested in using the Get-VDPortgroup cmdlet. Once we have the dvPg, we can then identify a specific Distributed Virtual Port (dvP) by using the Get-VDPort and passing in the dvPg from the previous command as well as the specific port by using the -key property. From here, we can then access a few properties from the dvP and most importantly, the statistics which we were originally interested in. In the example below, I am displaying the entire "stat" property, but you can easily filter out the specific stats you care about.

$server = Connect-VIServer -Server reflex.primp-industries.com

# Retrieve a Distributed Portgroup
$vdportgroup = Get-VDPortgroup -Name dv-vlan333

# Retrieve a specific Distributed Virtual Port from the Distributed Portgroup using the "key" property
$vdport = Get-VDPort -VDPortgroup $vdportgroup -Key 4

# Sample Distributed Virtual Port properties
Write-Host "Link Up: " $vdport.ExtensionData.State.RuntimeInfo.Linkup
Write-Host "Connectee: " $vdport.ExtensionData.State.RuntimeInfo.LinkPeer
Write-Host "Runtime MAC Address: " $vdport.ExtensionData.State.RuntimeInfo.macAddress

# Distributed Virtual Port Stats
$vdport.ExtensionData.State.Stats

Disconnect-VIServer -Server $server -Confirm:$false

$server = Connect-VIServer -Server reflex.primp-industries.com

# Retrieve a Distributed Portgroup

$vdportgroup = Get-VDPortgroup -Name dv-vlan333

# Retrieve a specific Distributed Virtual Port from the Distributed Portgroup using the "key" property

$vdport = Get-VDPort -VDPortgroup $vdportgroup -Key 4

# Sample Distributed Virtual Port properties

Write-Host "Link Up: " $vdport.ExtensionData.State.RuntimeInfo.Linkup

Write-Host "Connectee: " $vdport.ExtensionData.State.RuntimeInfo.LinkPeer

Write-Host "Runtime MAC Address: " $vdport.ExtensionData.State.RuntimeInfo.macAddress

# Distributed Virtual Port Stats

$vdport.ExtensionData.State.Stats

Disconnect-VIServer -Server $server -Confirm:$false

Here is an example of the output from the script above and we can see that Distributed Virtual Port "4" matches to what we see in the vSphere Web Client screenshot.

Automate the reverse, migrating from vSphere Distributed Switch to Virtual Standard Switch using PowerCLI 5.5

11/05/2013 by William Lam 14 Comments

Last week I demonstrated how you can easily leverage the new PowerCLI 5.5 VDS cmdlets to migrate from a VSS (Virtual Standard Switch) to a VDS (vSphere Distributed Switch). During the development of the script, I needed a way to easily jump back and fourth between VSS->VDS and VDS->VSS and I wanted to automate this so I did not have to use the UI to reset my environment.

I initially thought this was not possible after playing around with a couple of the cmdlets but thanks to Kamen, a PowerCLI Engineer who was able to provide me with the necessary information to create a reverse migration script going from VDS to VSS.

Here is what my lab environment looks like which includes three ESXi hosts connected to a VDS called "VDS-01" which is backed by 4 pNICSs. The VDS contains 3 VMkernel interfaces and here are their respective DVPortgroup names: Management Network, Storage Network and vMotion Network.

On each ESXi host, there is an already created VSS called "vSwitch0". If one is not created or if you decide to name it something differently, then you will need to modify the script. Here is a quick screenshot of what that looks like

The PowerCLI example script below uses the Add-VirtualSwitchPhysicalNetworkAdapter cmdlet which accepts a list of pNICs, VMkernel interfaces and the portgroups to migrate from VDS to VSS. The order in which the VMkernel and portgroups are specified is critically important as they will be assigned based on the provided ordering. The script also create the necessary portgroups on the VSS which of course can be modified based on your environment. Once the migration has been completed, it will then use the Remove-VDSwitchVMHost cmdlet to remove the ESXi hosts from the VDS.

Disclaimer: Please ensure you test this script in a development/test lab before using it in a production environment.

Connect-VIServer -Server vcenter55-1.primp-industries.com -User *protected email* -Pass vmware</b></i>

# ESXi hosts to migrate from VSS-&gt;VDS
$vmhost_array = @("vesxi55-1.primp-industries.com","vesxi55-2.primp-industries.com","vesxi55-3.primp-industries.com")

# VDS to migrate from
$vds_name = "VDS-01"
$vds = Get-VDSwitch -Name $vds_name

# VSS to migrate to
$vss_name = "vSwitch0"

# Name of portgroups to create on VSS
$mgmt_name = "Management Network"
$storage_name = "Storage Network"
$vmotion_name = "vMotion Network"

foreach ($vmhost in $vmhost_array) {
Write-Host "`nProcessing" $vmhost

# pNICs to migrate to VSS
Write-Host "Retrieving pNIC info for vmnic0,vmnic1,vmnic2,vmnic3"
$vmnic0 = Get-VMHostNetworkAdapter -VMHost $vmhost -Name "vmnic0"
$vmnic1 = Get-VMHostNetworkAdapter -VMHost $vmhost -Name "vmnic1"
$vmnic2 = Get-VMHostNetworkAdapter -VMHost $vmhost -Name "vmnic2"
$vmnic3 = Get-VMHostNetworkAdapter -VMHost $vmhost -Name "vmnic3"

# Array of pNICs to migrate to VSS
Write-Host "Creating pNIC array"
$pnic_array = @($vmnic0,$vmnic1,$vmnic2,$vmnic3)

# vSwitch to migrate to
$vss = Get-VMHost -Name $vmhost | Get-VirtualSwitch -Name $vss_name

# Create destination portgroups
Write-Host "`Creating" $mgmt_name "portrgroup on" $vss_name
$mgmt_pg = New-VirtualPortGroup -VirtualSwitch $vss -Name $mgmt_name

Write-Host "`Creating" $storage_name "Network portrgroup on" $vss_name
$storage_pg = New-VirtualPortGroup -VirtualSwitch $vss -Name $storage_name

Write-Host "`Creating" $vmotion_name "portrgroup on" $vss_name
$vmotion_pg = New-VirtualPortGroup -VirtualSwitch $vss -Name $vmotion_name

# Array of portgroups to map VMkernel interfaces (order matters!)
Write-Host "Creating portgroup array"
$pg_array = @($mgmt_pg,$storage_pg,$vmotion_pg)

# VMkernel interfaces to migrate to VSS
Write-Host "`Retrieving VMkernel interface details for vmk0,vmk1,vmk2"
$mgmt_vmk = Get-VMHostNetworkAdapter -VMHost $vmhost -Name "vmk0"
$storage_vmk = Get-VMHostNetworkAdapter -VMHost $vmhost -Name "vmk1"
$vmotion_vmk = Get-VMHostNetworkAdapter -VMHost $vmhost -Name "vmk2"

# Array of VMkernel interfaces to migrate to VSS (order matters!)
Write-Host "Creating VMkernel interface array"
$vmk_array = @($mgmt_vmk,$storage_vmk,$vmotion_vmk)

# Perform the migration
Write-Host "Migrating from" $vds_name "to" $vss_name"`n"
Add-VirtualSwitchPhysicalNetworkAdapter -VirtualSwitch $vss -VMHostPhysicalNic $pnic_array -VMHostVirtualNic $vmk_array -VirtualNicPortgroup $pg_array  -Confirm:$false
}

Write-Host "`nRemoving" $vmhost_array "from" $vds_name
$vds | Remove-VDSwitchVMHost -VMHost $vmhost_array -Confirm:$false

<i><b>Disconnect-VIServer -Server $global:DefaultVIServers -Force -Confirm:$false

Connect-VIServer -Server vcenter55-1.primp-industries.com -User administrator@vsphere.local -Pass vmware</b></i>

# ESXi hosts to migrate from VSS->VDS

$vmhost_array = @("vesxi55-1.primp-industries.com","vesxi55-2.primp-industries.com","vesxi55-3.primp-industries.com")

# VDS to migrate from

$vds_name = "VDS-01"

$vds = Get-VDSwitch -Name $vds_name

# VSS to migrate to

$vss_name = "vSwitch0"

# Name of portgroups to create on VSS

$mgmt_name = "Management Network"

$storage_name = "Storage Network"

$vmotion_name = "vMotion Network"

foreach ($vmhost in $vmhost_array) {

Write-Host "`nProcessing" $vmhost

# pNICs to migrate to VSS

Write-Host "Retrieving pNIC info for vmnic0,vmnic1,vmnic2,vmnic3"

$vmnic0 = Get-VMHostNetworkAdapter -VMHost $vmhost -Name "vmnic0"

$vmnic1 = Get-VMHostNetworkAdapter -VMHost $vmhost -Name "vmnic1"

$vmnic2 = Get-VMHostNetworkAdapter -VMHost $vmhost -Name "vmnic2"

$vmnic3 = Get-VMHostNetworkAdapter -VMHost $vmhost -Name "vmnic3"

# Array of pNICs to migrate to VSS

Write-Host "Creating pNIC array"

$pnic_array = @($vmnic0,$vmnic1,$vmnic2,$vmnic3)

# vSwitch to migrate to

$vss = Get-VMHost -Name $vmhost | Get-VirtualSwitch -Name $vss_name

# Create destination portgroups

Write-Host "`Creating" $mgmt_name "portrgroup on" $vss_name

$mgmt_pg = New-VirtualPortGroup -VirtualSwitch $vss -Name $mgmt_name

Write-Host "`Creating" $storage_name "Network portrgroup on" $vss_name

$storage_pg = New-VirtualPortGroup -VirtualSwitch $vss -Name $storage_name

Write-Host "`Creating" $vmotion_name "portrgroup on" $vss_name

$vmotion_pg = New-VirtualPortGroup -VirtualSwitch $vss -Name $vmotion_name

# Array of portgroups to map VMkernel interfaces (order matters!)

Write-Host "Creating portgroup array"

$pg_array = @($mgmt_pg,$storage_pg,$vmotion_pg)

# VMkernel interfaces to migrate to VSS

Write-Host "`Retrieving VMkernel interface details for vmk0,vmk1,vmk2"

$mgmt_vmk = Get-VMHostNetworkAdapter -VMHost $vmhost -Name "vmk0"

$storage_vmk = Get-VMHostNetworkAdapter -VMHost $vmhost -Name "vmk1"

$vmotion_vmk = Get-VMHostNetworkAdapter -VMHost $vmhost -Name "vmk2"

# Array of VMkernel interfaces to migrate to VSS (order matters!)

Write-Host "Creating VMkernel interface array"

$vmk_array = @($mgmt_vmk,$storage_vmk,$vmotion_vmk)

# Perform the migration

Write-Host "Migrating from" $vds_name "to" $vss_name"`n"

Add-VirtualSwitchPhysicalNetworkAdapter -VirtualSwitch $vss -VMHostPhysicalNic $pnic_array -VMHostVirtualNic $vmk_array -VirtualNicPortgroup $pg_array -Confirm:$false

}

Write-Host "`nRemoving" $vmhost_array "from" $vds_name

$vds | Remove-VDSwitchVMHost -VMHost $vmhost_array -Confirm:$false

<i><b>Disconnect-VIServer -Server $global:DefaultVIServers -Force -Confirm:$false

Here is a screenshot of the script executing:

Automate the migration from Virtual Standard Switch to vSphere Distributed Switch using PowerCLI 5.5

10/31/2013 by William Lam 22 Comments

I have been spending quite a bit of time in the lab lately working with some of our "future" software and one of the fun tasks I get to do is perform frequent rebuilds of my lab environment. Depending on the issues I encounter, I may even need to rebuild it on a daily basis and of course I have the majority of this automated so it is not as painful as it would be if I had to go through this manually.

The output of this build is a complete working vSphere environment that consists of several ESXi hosts connected to a vCenter Server with all the network and storage configured. On the networking front, the ESXi hosts were all running on a regular Virtual Standard Switch (VSS) and I needed to migrate them over to a Virtual Distributed Switch (VDS). In this particular environment, there is some Windows infrastructure and I thought about the different ways I could accomplish this and I remember hearing about some new VDS cmdlets that came out of PowerCLI 5.5. release.

Since I already had some scripts being kicked off on this Windows system, I thought I give the new PowerCLI cmdlets a try for VSS->VDS migration as I have heard good things about the new cmdlets. I performed my prototyping on a vSphere 5.5 environment, but I believe you might even be able to use this on older releases of vSphere.

Here is a list of the new VDS cmdlets that I used for the script:

Here are additional vSphere networking cmdlets that were required for script:

Even as a beginner of PowerCLI, I was able to quickly knock out a script that performed the migration from VSS to VDS and was able migrate ALL VMkernel interfaces and physical interfaces without any downtime. These new cmdlets definitely make it very easy for administrators to go from old Virtual Standard Switch over to the vSphere Distributed Switch.

Here is a overview of what my environment looks like which consists of three ESXi hosts with four physical NICs and three VMkernel interfaces.

The script below will create a brand new VDS and their associated Distributed Portgroups and attach a list of ESXi hosts which is configurable and performs the migration of VMkernel and physical interfaces. It does this by first moving two of the four physical NICs to the new VDS to ensure connectivity and then starts the migration of all VMkernel interfaces. Once that is complete, it will move the remainder physical NICs and then delete the Virtual Stand Switch portgroups.

Disclaimer: Please ensure you test this script in a development/test lab before using it in a production environment.

Connect-VIServer -Server vcenter55-1.primp-industries.com -User *protected email* -Pass vmware

# ESXi hosts to migrate from VSS-&gt;VDS
$vmhost_array = @("vesxi55-1.primp-industries.com", "vesxi55-2.primp-industries.com", "vesxi55-3.primp-industries.com")

# Create VDS
$vds_name = "VDS-01"
Write-Host "`nCreating new VDS" $vds_name
$vds = New-VDSwitch -Name $vds_name -Location (Get-Datacenter -Name "VSAN-Datacenter")

# Create DVPortgroup
Write-Host "Creating new Management DVPortgroup"
New-VDPortgroup -Name "Management Network" -Vds $vds | Out-Null
Write-Host "Creating new Storage DVPortgroup"
New-VDPortgroup -Name "Storage Network" -Vds $vds | Out-Null
Write-Host "Creating new vMotion DVPortgroup"
New-VDPortgroup -Name "vMotion Network" -Vds $vds | Out-Null
Write-Host "Creating new VM DVPortgroup`n"
New-VDPortgroup -Name "VM Network" -Vds $vds | Out-Null

foreach ($vmhost in $vmhost_array) {
# Add ESXi host to VDS
Write-Host "Adding" $vmhost "to" $vds_name
$vds | Add-VDSwitchVMHost -VMHost $vmhost | Out-Null

# Migrate pNIC to VDS (vmnic0/vmnic1)
Write-Host "Adding vmnic0/vmnic1 to" $vds_name
$vmhostNetworkAdapter = Get-VMHost $vmhost | Get-VMHostNetworkAdapter -Physical -Name vmnic0
$vds | Add-VDSwitchPhysicalNetworkAdapter -VMHostNetworkAdapter $vmhostNetworkAdapter -Confirm:$false
$vmhostNetworkAdapter = Get-VMHost $vmhost | Get-VMHostNetworkAdapter -Physical -Name vmnic1
$vds | Add-VDSwitchPhysicalNetworkAdapter -VMHostNetworkAdapter $vmhostNetworkAdapter -Confirm:$false

# Migrate VMkernel interfaces to VDS

# Management #
$mgmt_portgroup = "Management Network"
Write-Host "Migrating" $mgmt_portgroup "to" $vds_name
$dvportgroup = Get-VDPortgroup -name $mgmt_portgroup -VDSwitch $vds
$vmk = Get-VMHostNetworkAdapter -Name vmk0 -VMHost $vmhost
Set-VMHostNetworkAdapter -PortGroup $dvportgroup -VirtualNic $vmk -confirm:$false | Out-Null

# Storage #
$storage_portgroup = "Storage Network"
Write-Host "Migrating" $storage_portgroup "to" $vds_name
$dvportgroup = Get-VDPortgroup -name $storage_portgroup -VDSwitch $vds
$vmk = Get-VMHostNetworkAdapter -Name vmk1 -VMHost $vmhost
Set-VMHostNetworkAdapter -PortGroup $dvportgroup -VirtualNic $vmk -confirm:$false | Out-Null

# vMotion #
$vmotion_portgroup = "vMotion Network"
Write-Host "Migrating" $vmotion_portgroup "to" $vds_name
$dvportgroup = Get-VDPortgroup -name $vmotion_portgroup -VDSwitch $vds
$vmk = Get-VMHostNetworkAdapter -Name vmk2 -VMHost $vmhost
Set-VMHostNetworkAdapter -PortGroup $dvportgroup -VirtualNic $vmk -confirm:$false | Out-Null

# Migrate remainder pNIC to VDS (vmnic2/vmnic3)
Write-Host "Adding vmnic2/vmnic3 to" $vds_name
$vmhostNetworkAdapter = Get-VMHost $vmhost | Get-VMHostNetworkAdapter -Physical -Name vmnic2
$vds | Add-VDSwitchPhysicalNetworkAdapter -VMHostNetworkAdapter $vmhostNetworkAdapter -Confirm:$false
$vmhostNetworkAdapter = Get-VMHost $vmhost | Get-VMHostNetworkAdapter -Physical -Name vmnic3
$vds | Add-VDSwitchPhysicalNetworkAdapter -VMHostNetworkAdapter $vmhostNetworkAdapter -Confirm:$false

# Remove old vSwitch portgroups
$vswitch = Get-VirtualSwitch -VMHost $vmhost -Name vSwitch0

Write-Host "Removing vSwitch portgroup" $mgmt_portgroup
$mgmt_pg = Get-VirtualPortGroup -Name $mgmt_portgroup -VirtualSwitch $vswitch
Remove-VirtualPortGroup -VirtualPortGroup $mgmt_pg -confirm:$false

Write-Host "Removing vSwitch portgroup" $vmotion_portgroup
$vmotion_pg = Get-VirtualPortGroup -Name $vmotion_portgroup -VirtualSwitch $vswitch
Remove-VirtualPortGroup -VirtualPortGroup $vmotion_pg -confirm:$false

Write-Host "Removing vSwitch portgroup" $storage_portgroup
$storage_pg = Get-VirtualPortGroup -Name $storage_portgroup -VirtualSwitch $vswitch
Remove-VirtualPortGroup -VirtualPortGroup $storage_pg -confirm:$false
Write-Host "`n"
}

Disconnect-VIServer -Server $global:DefaultVIServers -Force -Confirm:$false

Connect-VIServer -Server vcenter55-1.primp-industries.com -User administrator@vsphere.local -Pass vmware

# ESXi hosts to migrate from VSS->VDS

$vmhost_array = @("vesxi55-1.primp-industries.com", "vesxi55-2.primp-industries.com", "vesxi55-3.primp-industries.com")

# Create VDS

$vds_name = "VDS-01"

Write-Host "`nCreating new VDS" $vds_name

$vds = New-VDSwitch -Name $vds_name -Location (Get-Datacenter -Name "VSAN-Datacenter")

# Create DVPortgroup

Write-Host "Creating new Management DVPortgroup"

New-VDPortgroup -Name "Management Network" -Vds $vds | Out-Null

Write-Host "Creating new Storage DVPortgroup"

New-VDPortgroup -Name "Storage Network" -Vds $vds | Out-Null

Write-Host "Creating new vMotion DVPortgroup"

New-VDPortgroup -Name "vMotion Network" -Vds $vds | Out-Null

Write-Host "Creating new VM DVPortgroup`n"

New-VDPortgroup -Name "VM Network" -Vds $vds | Out-Null

foreach ($vmhost in $vmhost_array) {

# Add ESXi host to VDS

Write-Host "Adding" $vmhost "to" $vds_name

$vds | Add-VDSwitchVMHost -VMHost $vmhost | Out-Null

# Migrate pNIC to VDS (vmnic0/vmnic1)

Write-Host "Adding vmnic0/vmnic1 to" $vds_name

$vmhostNetworkAdapter = Get-VMHost $vmhost | Get-VMHostNetworkAdapter -Physical -Name vmnic0

$vds | Add-VDSwitchPhysicalNetworkAdapter -VMHostNetworkAdapter $vmhostNetworkAdapter -Confirm:$false

$vmhostNetworkAdapter = Get-VMHost $vmhost | Get-VMHostNetworkAdapter -Physical -Name vmnic1

$vds | Add-VDSwitchPhysicalNetworkAdapter -VMHostNetworkAdapter $vmhostNetworkAdapter -Confirm:$false

# Migrate VMkernel interfaces to VDS

# Management #

$mgmt_portgroup = "Management Network"

Write-Host "Migrating" $mgmt_portgroup "to" $vds_name

$dvportgroup = Get-VDPortgroup -name $mgmt_portgroup -VDSwitch $vds

$vmk = Get-VMHostNetworkAdapter -Name vmk0 -VMHost $vmhost

Set-VMHostNetworkAdapter -PortGroup $dvportgroup -VirtualNic $vmk -confirm:$false | Out-Null

# Storage #

$storage_portgroup = "Storage Network"

Write-Host "Migrating" $storage_portgroup "to" $vds_name

$dvportgroup = Get-VDPortgroup -name $storage_portgroup -VDSwitch $vds

$vmk = Get-VMHostNetworkAdapter -Name vmk1 -VMHost $vmhost

Set-VMHostNetworkAdapter -PortGroup $dvportgroup -VirtualNic $vmk -confirm:$false | Out-Null

# vMotion #

$vmotion_portgroup = "vMotion Network"

Write-Host "Migrating" $vmotion_portgroup "to" $vds_name

$dvportgroup = Get-VDPortgroup -name $vmotion_portgroup -VDSwitch $vds

$vmk = Get-VMHostNetworkAdapter -Name vmk2 -VMHost $vmhost

Set-VMHostNetworkAdapter -PortGroup $dvportgroup -VirtualNic $vmk -confirm:$false | Out-Null

# Migrate remainder pNIC to VDS (vmnic2/vmnic3)

Write-Host "Adding vmnic2/vmnic3 to" $vds_name

$vmhostNetworkAdapter = Get-VMHost $vmhost | Get-VMHostNetworkAdapter -Physical -Name vmnic2

$vds | Add-VDSwitchPhysicalNetworkAdapter -VMHostNetworkAdapter $vmhostNetworkAdapter -Confirm:$false

$vmhostNetworkAdapter = Get-VMHost $vmhost | Get-VMHostNetworkAdapter -Physical -Name vmnic3

$vds | Add-VDSwitchPhysicalNetworkAdapter -VMHostNetworkAdapter $vmhostNetworkAdapter -Confirm:$false

# Remove old vSwitch portgroups

$vswitch = Get-VirtualSwitch -VMHost $vmhost -Name vSwitch0

Write-Host "Removing vSwitch portgroup" $mgmt_portgroup

$mgmt_pg = Get-VirtualPortGroup -Name $mgmt_portgroup -VirtualSwitch $vswitch

Remove-VirtualPortGroup -VirtualPortGroup $mgmt_pg -confirm:$false

Write-Host "Removing vSwitch portgroup" $vmotion_portgroup

$vmotion_pg = Get-VirtualPortGroup -Name $vmotion_portgroup -VirtualSwitch $vswitch

Remove-VirtualPortGroup -VirtualPortGroup $vmotion_pg -confirm:$false

Write-Host "Removing vSwitch portgroup" $storage_portgroup

$storage_pg = Get-VirtualPortGroup -Name $storage_portgroup -VirtualSwitch $vswitch

Remove-VirtualPortGroup -VirtualPortGroup $storage_pg -confirm:$false

Write-Host "`n"

}

Disconnect-VIServer -Server $global:DefaultVIServers -Force -Confirm:$false

Here is a screenshot of running through the script:

If we now take a look at our enviornment, we can see all three ESXi hosts have been migrated over to the VDS.

UPDATE (11/4/13) - Thanks to one of the PowerCLI engineers, it looks like there is a PowerCLI cmdlet that can be used to migrate from VDS->VSS. I will be sharing that script in another blog post for those that may want to perform the reverse.

One caveat that I hit during the development of this script is needing the ability to easily migrate between VSS->VDS and VDS->VSS. I was hoping it was simply reversing the set of operations and moving the VMkernel interfaces back to the Virtual Standard Switch but what I found for the Set-VMHostNetworkAdapter cmdlet is that it only accepts a Distributed Virtual Portgroup. This meant that I could only migrate to a VDS but not to a VSS. Though this will probably will fit the majority of customer use cases, for me this was a problem and means I will need to dig into the vSphere APIs to be able to seamlessly perform a VDS->VSS migration. Given that PowerCLI is an abstraction, we should be able to easily add this feature and I will be filing an FR with Engineering to see if we can get this added as I think it would be a useful feature to have.

Automate Update Manager Operations using vSphere SDK for Perl + VIX + PowerCLI + PowerCLI VUM

07/30/2010 by William Lam Leave a Comment

I recently saw an interesting question on the VMTN developers forum asking about vSphere SDK for Perl and VUM API integrations. As it stands today, VMware has not publicly exposed or documented the VMware Update Manager APIs, though they have released a few PowerCLI VUM cmdlets for PowerCLI users. This is one feature, in my opinion, that PowerCLI has over the other vSphere SDKs. This is quite unfortunate, since automating VUM operations is something I have looked forward to and the process can be slow from clicking around in the GUI. I think VMware sometimes forget that the world does not run on Windows and that VMware != Windows.

I was hoping with the release of vSphere 4.1, the VUM APIs would finally be exposed as a standard web service like the vSphere API provided with proper SDKs for the various languages. My reply to the VMTN user was exactly this: this type of integration does not exist today. If you would like to automate VUM operations, you must use the PowerCLI VUM cmdlets. The follow-up comment was how one might integrate between vSphere SDK for Perl and PowerCLI VUM cmdlets. Initially, I did not recommend this but it could potentially work with some type of WMI call or hooks from some Perl modules. The solution might get a little messy and it would probably be faster to just set up the PowerCLI VUM cmdlets on a Windows host.

As I thought about the question later that evening, I realized that there is potentially another method if you wanted to use the vSphere SDK for Perl but utilize the PowerCLI VUM cmdlets. The following solution will demonstrate the use of vMA, vSphere SDK for Perl, VIX Perl API, PowerCLI and PowerCLI VUM cmdlets. VMware VIX is used for guest management for VMs running on a VMware hypervisor, whether it be Workstation, Fusion or ESX(i). There is a Perl SDK for the VIX API which I use to generate a PowerCLI script that is transferred directly into a Windows VM running both PowerCLI and PowerCLI VUM. This dynamic PowerCLI script will contain the host information and VUM baseline provided from the vSphere SDK for Perl script. The script will remediate the host and then it will be deleted by VIX. This configuration is not ideal, but if you wanted to automate some of the available VUM operations but continue to use your vSphere SDK for Perl scripts, then you can.

The dynamic PowerCLI script that is generated is the following:

Connect-VIServer -Server [vc-server] -Protocol https -User [vc-user] -Password [vc-password]
$vmhost = Get-VMHost [vi-host]
$baseline = Get-Baseline [host-baseline]
$baseline | Attach-Baseline -Entity $vmhost -Confirm:$false
$vmhost | Scan-Inventory
$baseline | Remediate-Inventory -Entity $vmhost -Confirm:$false

Note: This is just one example, you can easily customize the script to generate other VUM operations or more complex PowerCLI script. Once the operation is completed on the ESX(i) host, the script is deleted via VIX.

Before we get started, you will need to have a Windows VM that has both PowerCLI and PowerCLI VUM installed which resides in the same infrastructure as your VUM Server. You will also need to have VMware vMA available and installed with VMware VIX which will be documented down below.

1. Download VMware VIX 1.10

2. Transfer VMware-VIX-1.10.1-266898.x86_64.bundle installer to vMA

3. Install VIX:

VMware-VIX-1.10.1-266898.x86_64.bundle

================================================================

[[email protected] ~]$ sudo sh VMware-VIX-1.10.1-266898.x86_64.bundle
Password:
Extracting VMware Installer...done.
You must accept the VMware VIX API End User License Agreement to
continue. Press Enter to proceed.
.....
The product is ready to be installed. Press Enter to begin
installation or Ctrl-C to cancel.
Installing VMware VIX API 1.10.1
Configuring...
[######################################################################] 100%
Installation was successful.

To complete the next section, you will need GCC to be installed which is not part of the default vMA installation. If you are using vMA 4.1, it is running CentOS and you can setup CentOS YUM repository. This will require that your vMA host can proxy out to internet or to specific site. I will document the changes that need to be made to talk to CentOS repository for package installs.

4. Create repository file:

[[email protected] ~]$ sudo vi /etc/yum.repos.d/centos-base.repo

Add the following to the repo file:

5. Install GCC using yum:

[[email protected] ~]$ sudo yum -y --nogpgcheck install gcc.x86_64

6. CD to vmware-vix directory and extract VIX Perl

[[email protected] ~]$ cd /usr/lib/vmware-vix/

[[email protected] vmware-vix]$ sudo tar -zxvf vix-perl.tar.gz
vix-perl/
vix-perl/vix.h
vix-perl/includeCheck.h
vix-perl/vm_basic_types.h
vix-perl/VixBinding.xs
vix-perl/VixBinding.pm
vix-perl/ModuleList
vix-perl/lib/
vix-perl/lib/API/
vix-perl/lib/API/API.pm
vix-perl/lib/API/Host.pm
vix-perl/lib/API/Job.pm
vix-perl/lib/API/VM.pm
vix-perl/lib/API/Snapshot.pm
vix-perl/lib/API/PropertyList.pm
vix-perl/lib/API/Constants.pm
vix-perl/lib/Simple.pm
vix-perl/Makefile.PL
vix-perl/typemap
vix-perl/ppport.h
vix-perl/README
vix-perl/samples/
vix-perl/samples/findhosttest.pl
vix-perl/samples/powertest.pl
vix-perl/samples/vmrun.pl
vix-perl/libvixAllProducts.so

7. Install VIX Perl

[[email protected] vmware-vix]$ cd vix-perl

[[email protected] vix-perl]$ sudo perl Makefile.PL
Writing Makefile for VMware::VixBinding

[[email protected] vix-perl]$ sudo make

[[email protected] vix-perl]$ sudo make install

If you did not want to go through all these manual steps after installing VIX, I actually wrote a quick shell script that will automate the configuration of the CentOS repository, GCC installation and extraction and installation of VIX Perl.

Download installVIXPerl.sh

Executing installVIXPerl.sh:

[[email protected] ~]$ chmod +x installVIXPerl.sh

[[email protected] ~]$ sudo ./installVIXPerl.sh

9. Download patch-host.pl script and transfer it to vMA

10. You will need to edit 4 variables defined within the script:

$psvm_username = Is the username to your Windows system running PowerCLI
$psvm_password = Is the password to your Windows system running PowerCLI
$powercli_bin = Is the full path to your powershell binary, if it is a default installation, you can leave this unchanged
$powercli_options = Is the path to vSphere PowerCLI psc file, you can also leave this as the default

Note: If you do decide to change either $powercli_bin or $powercli_options, make sure you add an extra "forward slash" which needs to be escaped in the Perl script.

The script requires you to connect to your vCenter server and provide the following parameters:

--vihost = Name of ESX(i) host to be patched

--baseline = Name of the VUM basline to attach

--psvm = Name of the Windows VM running both PowerCLI and PowerCLI VUM

Here is an example patching an ESXi host that is running on 4.0u2 and using the script to apply vSphere 4.1 baseline:

[[email protected]]$ ./patch-host.pl --config --server reflex.primp-industries.com --username primp --vihost esxi4-3.primp-industries.com --psvm powerclivm --baseline vSphere4.1-Upgrade

Entering maintenance mode for esxi4-3.primp-industries.com
Successfully entered maintenance mode for esxi4-3.primp-industries.com
Guest login successfully!
Copy patch-host-esxi4-3.primp-industries.com-22174.ps1 to guest successfully!
PowerCLI/VUM script executed successfully!
Script removed successfully!
Successfully patched esxi4-3.primp-industries.com using VUM baseline: vSphere4.1-Upgrade

One thing I did notice, after the script is transferred to the Windows VM, it takes about 15-20 seconds before the script executes. I am not exactly sure why this occurs, as this does not happen when running the PowerCLI script logged into the VM. This may be due to the way VIX is executing the script within the guest.

The following resources were used in creating this script:

Referenced growdisk.pl vSphere SDK for Perl/VIX script written by Matt Lamantia
Referenced Alan's video on Getting Started with Update Managed cmdlets