Bulk Uplink Configuration on Distributed Switches

Recently, as part of some work to install new physical adapters into our ESXi hosts, I was asked to look at some automation around uplink failover order. If you ever have to change these, it can be somewhat tedious, especially if you have lots of port groups, switches and vCenters.

Since I’ve been slacking on the updates round here, I’ll go over the 2 functions that came out of that piece of work. Hopefully they will save someone else some pain 🙂


The first function was written to review current configuration, and to confirm the new configuration. It will get the configuration state of an uplink for all port groups on a particular switch, whether that is “Assigned”, “Standby” or “Unused”.

Let’s take a look at the first example where we report on the status of an uplink “dvUplink1” on all port groups on DV switch “LAB-DVS-1500”. First, we get the distributed switch object:

Then we can fire the function, which will iterate through every port group on this switch and get the status of this uplink:

I can quickly see that this uplink is set to Active within the teaming and failover configuration on all port groups. Great.

I can take this a step further by using pipeline input to get the status of this uplink on all port groups on all distributed switches in this vCenter:

Awesome, life is good with this dvUplink1. Now let’s look at making some changes.


I don’t like dvUplink2 much and I want to set it to unused across all of my port groups on switch “LAB-DVS-1500”. No problem:

But wait, will I need to confirm every port group? No, this function uses PowerShell’s “Should Process” functionality. This means that if you have a function or CMDlet that is potentially impacting (usually denoted by a PowerShell verb like “Set”), then you should be implementing Should Process as a best practice. To overide this and cowboy all port groups without confirmation, use the standard parameter -Confirm as follows:

Yeeha, job done. Let’s confirm the change with Get-VDUplinkState:

Excellent, dvUplink2 has been reassigned on all port groups on this switch. For maximum excitement, you could use pipeline input to pipe all DV switches to this function and set the uplink on all port groups, on all switches. What can go wrong? It goes without saying, just because you can, doesn’t mean you should 😉


Obviously this is a very fast way to make everything stop working, so use with caution and do some testing first.

The eagle eyed might notice that I’ve used an Invoke-Expression in the Set-VDUplinkState function. Generally speaking, people will tell you that Invoke-Expression is the work of the devil and should be avoided. This is probably true, but there are always exceptions. This was a neat way to dynamically build up the paramter set I needed for Set-VDUplinkTeamingPolicy which didn’t accept null inputs for uplink configuration:

                ## Build a cmd string
                $cmdString = "`$teamingPolicy | Set-VDUplinkTeamingPolicy "

                if ($ActiveUplinkPorts) {
                    $cmdString = $cmdString + "-ActiveUplinkPort `$activeUplinkPorts "
                } # if
                if ($StandbyUplinkPorts) {
                    $cmdString = $cmdString + "-StandbyUplinkPort `$StandbyUplinkPorts"
                } # if
                if ($UnusedUplinkPorts) {
                    $cmdString = $cmdString + "-UnusedUplinkPort `$UnusedUplinkPorts"
                } # if

                ## Add tail to cmd
                $cmdString = $cmdString + " -ErrorAction Stop | Out-Null"

                ## Apply new configuration
                try {

                    ## Apply shouldProcess
                    if ($PSCmdlet.ShouldProcess($vdPort.name)) {
                        Invoke-Expression -Command $cmdString -ErrorAction Stop
                    } # if

                    Write-Verbose ("Set new uplink configuration")
                } # try
                catch {
                    Write-Debug ("Failed to set new teaming policy.")
                    throw ("Failed to set new teaming policy. " + $_.exception.message)
                } # catch

There are probably other solutions to this, such as using a large switch block to get every possible uplink combination, but this works for me and I’m happy with it in my environment. Of course stickler types are welcome to amend for their own requirements.

As an aside, we can also see the Should Process wrapped around the part of the function that will actually make the change.


As usual, the above code is available on the TDS Github found here.

If you found these functions useful, or have ideas for improvements, get in touch or leave a comment 🙂

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: