LucD notes

Another interesting feature of a dvSwitch is the ability to use bidirectional traffic shaping. Besides the outbound traffic shaping that is available on regular virtual switches, with the dvSwitches we can also have inbound traffic shaping. The traffic shaping is defined with the three known, classical values: average bandwidth, peak and burst size.

Recently there were some threads in the PowerCLI Community that asked how to do this with PowerCLI. Time to add this to our repertoire of PowerCLI dvSwitch functions.

Background

By default traffic shaping is disabled for inbound and outbound traffic.

To remember the difference between ingress and egress, look at it from the point of view of the dvSwitch; ingress is the traffic from the VM to the switch (i.e. incoming traffic) and egress is from the switch to the VM (i.e. outgoing or exit traffic).

The three parameters to control traffic shaping are:

• average bandwidth: bits per second averaged over time
• peak bandwidth: maximum amount (in kbps) the portgroup can handle
• burst size: maximum number of bytes the portgroup is allowed to burst. Is a multiplicative factor that defines how long the bandwidth can exceed the average.

The script

function Set-dvPgTrafficShaping{
<#
.SYNOPSIS
Configure traffic shaping on a dvSwitch portgroup
.DESCRIPTION
The function will configure ingress (VM to switch)
and egress (switch to VM) traffic shaping for a specific
dvSwitch portgroup
.NOTES
Author:  Luc Dekens
.PARAMETER dvPg
An object that represents a dvPortgroup as returned by the
Get-dVsWPg function
.PARAMETER InShaping
 A switch which indicates if inshaping (ingress) should be
enabled or not
.PARAMETER inAverageKbps
The value, in Kbits/sec, for the ingress average bandwidth.
If the value is -1, the setting will be left unchanged.
.PARAMETER inBurstKB
The value, in Kbytes, for the ingress burst size
If the value is -1, the setting will be left unchanged.
.PARAMETER inPeakKbps
The value, in Kbits/sec, for the ingress peak bandwidth
If the value is -1, the setting will be left unchanged.
.PARAMETER OutShaping
A switch which indicates if outshaping (egress) should be
enabled or not
.PARAMETER outAverageKbps
The value, in Kbits/sec, for the average bandwidth
If the value is -1, the setting will be left unchanged.
.PARAMETER outBurstKB
The value, in Kbytes, for the burst size
If the value is -1, the setting will be left unchanged.
.PARAMETER outPeakKbps
The value, in Kbits/sec, for the peak bandwidth
If the value is -1, the setting will be left unchanged.
.EXAMPLE
PS> Get-dvSwPg $dvSw $dvPgName | `
 >> Set-dvPgTrafficShaping -IShaping:$false `
 >>    -OutShaping -outAverage 100000 `
 >>    -outPeak 100000 `
 >>    -outBurst 102400
#>

   [CmdletBinding()]
   param(
   [parameter(Mandatory = $true, ValueFromPipeline = $true)]
   [PSObject]$dvPg,
   [switch]$InShaping,
   [long]$inAverageKbps,
   [long]$inBurstKB,
   [long]$inPeakKbps,
   [switch]$OutShaping,
   [long]$outAverageKbps,
   [long]$outBurstKB,
   [long]$outPeakKbps
   )

   $spec = New-Object VMware.Vim.DVPortgroupConfigSpec
   $spec.ConfigVersion = $dvPg.Config.ConfigVersion
   $spec.DefaultPortConfig = New-Object VMware.Vim.VMwareDVSPortSetting
   if($InShaping){
      $spec.DefaultPortConfig.InShapingPolicy = New-Object VMware.Vim.DVSTrafficShapingPolicy
      $spec.DefaultPortConfig.InShapingPolicy.Enabled = New-Object VMware.Vim.BoolPolicy
      $spec.DefaultPortConfig.InShapingPolicy.Enabled.Value = $true
      $spec.DefaultPortConfig.InShapingPolicy.Enabled.Inherited = $false
      if($inAverageKbps -ne -1){
         $spec.DefaultPortConfig.InShapingPolicy.averageBandwidth = New-Object VMware.Vim.LongPolicy
         $spec.DefaultPortConfig.InShapingPolicy.averageBandwidth.Value = $inAverageKbps * 1000
         $spec.DefaultPortConfig.InShapingPolicy.averageBandwidth.Inherited = $false
      }
      if($inBurstKB -ne -1){
         $spec.DefaultPortConfig.InShapingPolicy.burstSize = New-Object VMware.Vim.LongPolicy
         $spec.DefaultPortConfig.InShapingPolicy.burstSize.Value = $inBurstKB * 1KB
         $spec.DefaultPortConfig.InShapingPolicy.burstSize.Inherited = $false
      }
      if($inPeakKbps -ne -1){
         $spec.DefaultPortConfig.InShapingPolicy.peakBandwidth = New-Object VMware.Vim.LongPolicy
         $spec.DefaultPortConfig.InShapingPolicy.peakBandwidth.Value = $inPeakKbps * 1000
         $spec.DefaultPortConfig.InShapingPolicy.peakBandwidth.Inherited = $false
      }
   }
   else{
      $spec.DefaultPortConfig.InShapingPolicy = New-Object VMware.Vim.DVSTrafficShapingPolicy
      $spec.DefaultPortConfig.InShapingPolicy.Enabled = New-Object VMware.Vim.BoolPolicy
      $spec.DefaultPortConfig.InShapingPolicy.Enabled.Value = $false
      $spec.DefaultPortConfig.InShapingPolicy.Enabled.Inherited = $true
   }

   if($OutShaping){
      $spec.DefaultPortConfig.OutShapingPolicy = New-Object VMware.Vim.DVSTrafficShapingPolicy
      $spec.DefaultPortConfig.OutShapingPolicy.Enabled = New-Object VMware.Vim.BoolPolicy
      $spec.DefaultPortConfig.OutShapingPolicy.Enabled.Value = $true
      $spec.DefaultPortConfig.OutShapingPolicy.Enabled.Inherited = $false
      if($outAverageKbps -ne -1){
         $spec.DefaultPortConfig.OutShapingPolicy.averageBandwidth = New-Object VMware.Vim.LongPolicy
         $spec.DefaultPortConfig.OutShapingPolicy.averageBandwidth.Value = $outAverageKbps * 1000
         $spec.DefaultPortConfig.OutShapingPolicy.averageBandwidth.Inherited = $false
      }
      if($outBurstKB -ne -1){
         $spec.DefaultPortConfig.OutShapingPolicy.burstSize = New-Object VMware.Vim.LongPolicy
         $spec.DefaultPortConfig.OutShapingPolicy.burstSize.Value = $outBurstKB * 1KB
         $spec.DefaultPortConfig.OutShapingPolicy.burstSize.Inherited = $false
      }
      if($outPeakKbps -ne -1){
         $spec.DefaultPortConfig.OutShapingPolicy.peakBandwidth = New-Object VMware.Vim.LongPolicy
         $spec.DefaultPortConfig.OutShapingPolicy.peakBandwidth.Value = $outPeakKbps * 1000
         $spec.DefaultPortConfig.OutShapingPolicy.peakBandwidth.Inherited = $false
      }
   }
   else{
      $spec.DefaultPortConfig.OutShapingPolicy = New-Object VMware.Vim.DVSTrafficShapingPolicy
      $spec.DefaultPortConfig.OutShapingPolicy.Enabled = New-Object VMware.Vim.BoolPolicy
      $spec.DefaultPortConfig.OutShapingPolicy.Enabled.Value = $false
      $spec.DefaultPortConfig.OutShapingPolicy.Enabled.Inherited = $true
   }

   $dvPg.ReconfigureDVPortgroup($spec)
}

function Get-dvPgTrafficShaping{
<#
.SYNOPSIS
Returns the traffic shaping settings for a dvSwitch portgroup
.DESCRIPTION
The function will return all traffic shaping settings for a dvSwitch portgroup
.NOTES
Author:  Luc Dekens
.PARAMETER dvPg
An object that represents a dvPortgroup as returned by the
Get-dVsWPg function
.EXAMPLE
PS> Get-dvSwPg $dvSw $dvPgName | Get-dvPgTrafficShaping
#>

   [CmdletBinding()]
   param(
   [parameter(Mandatory = $true, ValueFromPipeline = $true)]
   [PSObject]$dvPg)

   $ts = New-Object PSObject

   $ingress = $dvPg.Config.DefaultPortConfig.InshapingPolicy
   Add-Member -InputObject $ts -Name IngressState -Value $ingress.Enabled.Value -MemberType NoteProperty
   if($ingress.Enabled.Value){
      Add-Member -InputObject $ts -Name "InAverage (Kbps)" -Value ($ingress.AverageBandwidth.Value/1000) -MemberType NoteProperty
      Add-Member -InputObject $ts -Name "InBurst (KB)" -Value ($ingress.BurstSize.Value/1KB) -MemberType NoteProperty
      Add-Member -InputObject $ts -Name "InPeak (Kbps)" -Value ($ingress.PeakBandwidth.Value/1000) -MemberType NoteProperty
   }
   else{
      Add-Member -InputObject $ts -Name "InAverage (Kbps)" -Value "na" -MemberType NoteProperty
      Add-Member -InputObject $ts -Name "InBurst (KB)" -Value "na" -MemberType NoteProperty
      Add-Member -InputObject $ts -Name "InPeak (Kbps)" -Value "na" -MemberType NoteProperty
   }

   $egress = $dvPg.Config.DefaultPortConfig.OutshapingPolicy
   Add-Member -InputObject $ts -Name EgressState -Value $egress.Enabled.Value -MemberType NoteProperty
   if($egress.Enabled.Value){
      Add-Member -InputObject $ts -Name "OutAverage (Kbps)" -Value ($egress.AverageBandwidth.Value/1000) -MemberType NoteProperty
      Add-Member -InputObject $ts -Name "OutBurst (KB)" -Value ($egress.BurstSize.Value/1KB) -MemberType NoteProperty
      Add-Member -InputObject $ts -Name "OutPeak (Kbps)" -Value ($egress.PeakBandwidth.Value/1000) -MemberType NoteProperty
   }
   else{
      Add-Member -InputObject $ts -Name "OutAverage (Kbps)" -Value "na" -MemberType NoteProperty
      Add-Member -InputObject $ts -Name "OutBurst (KB)" -Value "na" -MemberType NoteProperty
      Add-Member -InputObject $ts -Name "OutPeak (Kbps)" -Value "na" -MemberType NoteProperty
   }

   $ts
}

Annotations

Line 1-120: The Set-dvPgTrafficShaping function

Line 61: When calling methods on distributed virtual switches it is important to pass the ConfigVersion value of the object.

Line 63-89: Handles the Ingress settings

Line 91-117: Handles the Egress settings

Line 67,76,81,88,95,99,104,109,116: When the network shaping settings are define on the portgroup it is important to indicated that property is not inherited from the dvSwitch.

Line 70,80,98,108: The function parameters allow to specify the average and peak bandwidth values in the Kbps, while the actual call requires these values to be passed in bps. Note that to convert from Kbps to bps you have to multiply by 1000, not 1024.

Line 75,103: The function parameters for the burst size expects values in KB, just like in the vSphere Client. The method itself requires these values to be in bytes.

Line 1-120: The Get-dvPgTrafficShaping function.

Line 143: The result is returned as PSObject to which the properties with the packet shaping values are added.

Sample usage

By default, a new dvSwitch and new dvPortgroup will have traffic shaping disabled.
To get the actual settings we can do

$dcName = "MyDatacenter"
$dvSwName = "dvSw1"
$dvPgName = "dvPg12"

$dvSw = Get-dvSwitch $dcName $dvSwName
$dvPg = Get-dvSwPg $dvSw $dvPgName

Get-dvPgTrafficShaping -dvPg $dvPg

This produces output likes this

Btw, the Get-dvSwitch and Get-dvSwPg functions are described in previous episodes of my dvSwitch series.

To enable inbound and outbound traffic shaping you can call the function as follows

$dcName = "MyDatacenter"
$dvSwName = "dvSw1"
$dvPgName = "dvPg12"

$dvSw = Get-dvSwitch $dcName $dvSwName
$dvPg = Get-dvSwPg $dvSw $dvPgName

Set-dvPgTrafficShaping -dvPg $dvPg `
-InShaping -inAverageKbps 100000 -inBurstKB 102400 -inPeakKbps 100000 `
-OutShaping -outAverageKbps 100000 -outBurstKB 102400 -outPeakKbps 100000

$dvPg = Get-dvSwPg $dvSw $dvPgName
Get-dvPgTrafficShaping -dvPg $dvPg

This will result in

And in the vSphere Client this will show as follows.

Notice how we had to call the Get-dvSwPg function again before the Get-dvPgTrafficShaping function. This is required to fetch the actual values for the portgroup.

To enable inbound and disable outbound traffic shaping, you can make the following call.

Set-dvPgTrafficShaping -dvPg $dvPg `
   -InShaping -inAverageKbps 100000 -inBurstKB 102400 -inPeakKbps 100000 `
   -OutShaping:$false

The result looks like this

To change specific values (average/peak/burst) you can use the function as follows

Set-dvPgTrafficShaping -dvPg $dvPg `
   -InShaping -inAverageKbps -1 -inBurstKB 204800 -inPeakKbps -1 `
   -OutShaping:$false

This call only changes the burst value, the average and peak values are kept as they are, indicated by the -1 values.

And finally a somewhat more advanced example, we use the Get function combined with the Set function to increase the inbound peak bandwidth with 10%.

$ps = Get-dvPgTrafficShaping -dvPg $dvPg

Set-dvPgTrafficShaping -dvPg $dvPg `
-InShaping -inAverageKbps -1 -inBurstKB -1 -inPeakKbps ($ps."InPeak (Kbps)" * 1.1) `
-OutShaping:$false

The result

Enjoy!