Home > Blogs > VMware PowerCLI Blog

Using vSphere Tags with PowerCLI

imageWith the new 5.5 R2 release of PowerCLI we introduced end-to-end support for the vSphere Tagging functionality. You can now automate Tag and TagCategory management, assign tags on objects and search for objects by tag. This blog post will give you an overview of the new functionalities and a couple of useful scripts:

  • One for exporting/importing of tags
  • One for converting the legacy custom attributes to tags

Managing Tag Categories

Tag Categories allow you to group related tags together. When you define a category, you can also specify which object types its tags can be applied to and whether more than one tag in the category can be applied to an object. Creating a category with PowerCLI is easy:

New-TagCategory –Name [name] -Description [description] -Cardinality [single/multiple] –EntityType [list of types]

For example let’s create a category that will contain a tag for each vSphere user. We’ll name this category “Owner” and use it to tag the owners of Virtual Machines. The tags will only be applicable to Virtual Machines and a Virtual Machine can have only one owner. The following script creates such a category:

New-TagCategory –Name “Owner” –Cardinality single –EntityType VirtualMachine

The “-Cardinality” parameter specifies whether a single or multiple tags from this category can be applied to the same object at the same time. If you don’t specify it the default is “single”. The “-EntityType” parameter allows you to specify the object types to which you can attach tags from this category. If you omit the parameter by default the category will be applicable to all supported entity types.

The full list of supported entity types is: VirtualMachine, VM, VMHost, Folder, Datastore, DatastoreCluster, Cluster, ResourcePool, DistributedSwitch, DistributedPortGroup, VirtualPortGroup, VApp, Datacenter, All.

Modifying an existing TagCategory is done through Set-TagCategory cmdlet. You can change its name, description, cardinality (you can only extend it to “multiple”, restricting it to “single” is not possible) and add more entity types (again you can only extend the applicable entity types).

In our previous example the “Owner” category is only applicable to Virtual Machines, however VApps can also have an owner. Let’s modify the category to allow tagging VApps as well:

Get-TagCategory “Owner” | Set-TagCategory –AddEntityType VApp

Removing an existing category is just as easy by using the Remove-TagCategory cmdlet. Note that by removing a category you are also removing all tags in it and any assignments of these tags! Here is an example:

Remove-TagCategory “Owner”

Managing Tags

Once you have a tag category you are able to create new tags in it. This is done through the New-Tag cmdlet. For example in our “Owner” category let’s create a tag for John Smith:

New-Tag –Name “jsmith” –Category “Owner”

You can also create multiple tags – by reading the input values from CSV file or from other cmdlets. Here is how to create tags for each user in the “Example.org” domain:

# Retrieve all user accounts in the “Example.org” domain

$userList = Get-VIAccount –User –Domain “Example.org”

# For each user account create a new tag based on the user’s Id

foreach ($user in $userList) { New-Tag –Category “Owner” –Name $user.Id –Description $user.Description }

Modifying an existing tag is done through the Set-Tag cmdlet. It allows you to change the tag’s name and description:

Get-Tag “jsmith” –Category “Owner” | Set-Tag –Description “John Smith”

Removing a tag is done through Remove-Tag cmdlet, similar to removing a category. When removing a tag you will automatically remove any assignments of this tag.

Now that you have created some tags – it’s time to put them to use. You can assign tag to an entity using the New-TagAssignment cmdlet. Here is how to assign the “jsmith” tag to the VMs that belong to John (we assume they have “jsmith” in their name):

Get-VM –Name *jsmith* | New-TagAssignment –Tag “jsmith”

You can easily retrieve all tag assignments on a given entity:

Get-VM jsmith_vm1 | Get-TagAssignment

Or you can retrieve all VMs that have a given tag associated with them:

Get-VM –Tag “jsmith”

If you want to build a report that displays information about your inventory objects and all tags associated with them – you can do that by using the New-VIProperty cmdlet to add a “Tag” property to your objects. Here is an example of how to do that for the VirtualMachines, but it is easily applicable to other types as well:

# First we want to define the new “Tag” property of the VirtualMachine object

New-VIProperty -Name Tag -ObjectType VirtualMachine -Value `

{ Get-TagAssignment -Entity $args[0] | select -ExpandProperty Tag }

# Now retrieve all VMs and their tags:

Get-VM | select Name, Tag

Exporting and importing tags

Now that you know the basics, let’s do something more advanced. If you have created all your tags with a script using the above commands it’s very easy to run this scrip on another vCenter Server in order to replicate all tags on that server as well. But if you created them by hand how can you replicate them on a different VC? Well, here is one solution, using the attached script ExportImportTags.ps1 you will be able to export your tag configuration from one VC and then import it to another (one or multiple).

To use the script – simply download it from here and save it in a folder of your preference. Start PowerCLI and load the script:

. <path_to_folder>\ExportImportTags.ps1

Then connect to the VC you want to export tags from:

$sourceVC = Connect-VIServer <connection_parameters>

To export all tags use the Export-Tags function. It accepts two parameters, the server from which to export the tags and a destination file where to save them:

Export-Tags –Server $sourceVC –Destination C:\vc1_tags.txt

Then connect to the VC(s) that you want to import those tags to:

$destinationVC = Connect-VIServer <connection_parameters>

To import the tags use the Import-Tags function. It accepts two parameters, the server on which to import the tags and a source file from which to read them (the file produced by Export-Tags earlier):

Import-Tags –Server $destinationVC –Source C:\vc1_tags.txt

That’s it! You now have the same tag configuration across all your VCs.

Converting your existing custom attributes to tags

What if you are using the legacy custom attributes and want to convert those to tags? The attached ConvertCustomAttributesToTags.ps1 script will do that for you. The script will scan your existing custom attributes and annotation values and based on those create the corresponding tag categories and tags. It will then assign the newly created tags to your inventory items. Using the script is done in the same way as above, download it from here, start PowerCLI, load the script and connect to your vCenter server:

. <path_to_folder>\ ConvertCustomAttributesToTags.ps1

$sourceVC = Connect-VIServer <connection_parameters>

To run the script just call the ConvertCustomAttributesToTags function and pass it the server you want to operate on:

ConvertCustomAttributesToTags $server

Once the function completes you will have tags matching your existing custom attribute hierarchy. If you like you can remove the old custom attributes.


clip_image002[8]This post was created by Dimitar Barfonchovski.Dimitar joined VMware and the PowerCLI team in 2007. He is member of the development part of the team and his main responsibilities are the functional design and implementation of features for the vSphere and vCloud PowerCLI components.

As with all members of the team, he is working to deliver a good and valuable product. He is also working to improve all processes and tools involved in the product development and validation.

EVC with PowerCLI 5.5 R2–Part 2

In this previous post we talked about one of the great new features introduced in PowerCLI 5.5 R2 for configuring EVC, in this post we will continue to show how we can make configuring and using EVC easier with PowerCLI.

Compatibility checks

While configuring EVC on a cluster you will probably need to perform some compatibility checks. Here’s how you can automate them with a script.

Check host’s compatibility with a target EVC mode

You can obtain the key for the desired EVC mode using one of the methods I described earlier.

$vmHost = Get-VMHost ‘MyVMHost’

$evcModeKey = ‘intel-westmere’

$availableEVCModes = $viServer.ExtensionData.Capability.SupportedEVCMode

$targetEVCMode = $availableEVCModes | ?{$_.Key -eq $evcModeKey}

$hostMaxEvcMode = $availableEVCModes | ?{$_.Key -eq $vmHost.MaxEVCMode}

$hostIsEVCCompatible = ($targetEVCMode.Vendor -eq $hostMaxEvcMode.Vendor) -and `

($targetEVCMode.VendorTier -le $hostMaxEvcMode.VendorTier)

Detect VMs on a host that are incompatible with a target EVC mode

$incompatibleVMs = @()

if ($targetEVCMode.VendorTier -lt $hostMaxEvcMode.VendorTier)


$incompatibleVMs = Get-VM -Location $vmhost | `

? {$_.PowerState -eq ‘PoweredOn’ -or $_.PowerState -eq ‘Suspended’}


My EVC configuration check list

In this section I have outlined the steps for configuring EVC in different scenarios. For steps that require some kind of compatibility check, you can use the sample scripts from the previous section.

Adding a host to an EVC enabled cluster

1. Check if the host you are adding is compatible with the current EVC mode of the cluster.

2. If the host’s CPU feature set is greater than the EVC mode of the cluster, ensure that the host has no powered-on or suspended virtual machines. If the check returns any incompatible VMs you will have two options:

· Migrate incompatible VMs to another host

· Power off incompatible VMs, add the host to the cluster and then power back on the VMs.

Enable EVC on a cluster

1. Select a desired EVC mode for the cluster

2. Detect hosts within the cluster that are incompatible with the selected EVC mode

3. Move incompatible hosts out of the cluster

4. Set the EVC mode

Raise the EVC mode of a cluster

1. Make sure all hosts in the new cluster support the new EVC mode

2. Move incompatible hosts out of the cluster

3. Set the EVC mode

Just keep in mind that all running VMS will not have access to the CPU features available in the new EVC mode until they are powered off and powered back on

Lower the EVC mode of a cluster

1. Power off any VMs on any hosts in the cluster that are incompatible with the new EVC mode

2. Set the EVC mode

A small EVC helper script

Finally, I have prepared a couple of high-level PowerShell functions that will help you automate your process, download the script containing the helper functions from here.

Detect what is the maximum EVC mode that can be set on an existing cluster

This is helpful when you want to determine your cluster EVC readiness depending on the EVC capabilities of the hosts in that cluster.

Function name: Get-MaxEVCModeKey
Returns the maximum EVC mode that is supported by all of the specified VM hosts

$VMHosts = Get-VMHost -Location ‘MyCluster’

Get-MaxEVCModeKey $VMHosts

Select a group of hosts with common EVC capability

This is applicable in two different scenarios:

· To identify compatible hosts that can be added to an EVC enabled cluster

· To identify hosts that are incompatible with a given EVC mode and prevent the cluster from running in that EVC mode

Function name: Get-VMHostByEVCCompatibility

Returns all VM hosts from the specified list that match the specified EVC compatibility criteria


$VMHosts = Get-VMHost -Location ‘MyCluster’

Get-VMHostByEVCCompatibility $VMHosts -EvcModeKey ‘intel-westmere’ -IncompatibleVMHosts

$VMHosts = Get-VMHost -Location ‘MyCluster’

Get-VMHostByEVCCompatibility $VMHosts -EvcModeKey ‘intel-westmere’ -CompatibleVMHosts

Check host’s compatibility with a particular EVC mode

Function name: CheckVMHostEVCCompatibility
Checks whether the specified VM host is compatible with the specified EVC mode

List available EVC modes

Function name:GetAvailableEVCModeKeys
Retrieves the keys of all EVC modes that are supported by the specified vCenter Server

Download the script containing these functions from here.

TodorThis post was created by Todor Tsvetkov…

Todor is a developer engineer in the PowerCLI team. He joined VMware and PowerCLI in late 2011 and has since taken active part in analyzing, architecting and developing various features of the product. His contribution to the latest PowerCLI release includes the Tagging and EVC functionality.

Like everyone in the PowerCLI team, he is dedicated on delivering a fully-functional, high-quality product. When not working on PowerCLI, he spends his time roller skating, playing the piano and practicing impro theater.

EVC with PowerCLI 5.5 R2–Part 1

What is EVC?

Enhanced vMotion Compatibility (EVC) is a vSphere feature that you can enable on a specific cluster to maximize the vMotion compatibility of hosts within that cluster. EVC will make sure that all hosts in the cluster present the same CPU feature set to their virtual machines, even if the actual CPUs on the hosts differ. An EVC-enabled cluster can contain hosts with CPUs of different generations but only from a single CPU vendor.

What about performance?

EVC masks only those processor features that affect vMotion compatibility. Enabling EVC does not prevent a virtual machine from taking advantage of faster processor speeds, increased numbers of CPU cores, or hardware virtualization support that might be available on newer hosts.

What is “EVC mode”?

The EVC mode of a cluster reflects the minimum CPU generation that is supported by all hosts in that cluster.

Apart from its human readable name, each EVC mode also has a “key” that is used by the vSphere API as a unique identifier. PowerCLI uses the EVC key for all EVC-related operations. The set of available (supported) EVC modes depends on the particular vSphere Server version. For version 5.5 these are:

EVC modes for Intel CPUs

Intel Processor Family (Generation) EVC-Mode Key
Intel® “Merom” Generation intel-merom
Intel® “Penryn” Generation intel-penryn
Intel® “Nehalem” Generation intel-nehalem
Intel® “Westmere” Generation intel-westmere
Intel® “Sandy Bridge” Generation intel-sandybridge
Intel® “Ivy Bridge” Generation intel-ivybridge

EVC modes for AMD CPUs

Intel Processor Family (Generation) EVC-Mode Key
AMD Opteron™ Generation 1 amd-rev-e
AMD Opteron™ Generation 2 amd-rev-f
AMD Opteron™ Gen. 3 (no 3DNow!™) amd-greyhound-no3dnow
AMD Opteron™ Generation3 amd-greyhound
AMD Opteron™ Generation 4 amd-bulldozer
AMD Opteron™ “Piledriver” Generation amd-piledriver

The EVC modes in each of the above groups are sorted in ascending order. Each EVC mode for the same CPU vendor exposes all CPU features of the previous EVC mode plus any new features that are present in the newer CPU generation. EVC modes from different CPU vendors are not compatible and cannot be compared. You can retrieve all available EVC modes on a specific vSphere server using:

$viserver = Connect-VIServer MYVISERVER


Retrieving the EVC mode for clusters, hosts and VMs with PowerCLI


You can retrieve the current EVC mode of a cluster using its EVCMode property.

Get-Cluster ‘MyCluster’ | select -Property Name,EVCMode


Hosts always inherit their EVC mode from the cluster which they are part of. To retrieve the current EVC mode of a host you just have to read its cluster’s EVCMode property.

$vmhost = Get-VMHost MYVMHOST



Get-Cluster -VMHost ‘MyVMHost’ | select -Property EVCMode

The maximum EVC capability of a host depends on its hardware capabilities, such as CPU vendor and CPU generation. Additionally, software settings in BIOS that disable specific CPU features may also affect the host’s EVC capability. You can determine the maximum EVC capability of a host using its MaxEVCMode property

$vmhost = Get-VMHost MYVMHOST



Get-VMHost ‘MyVMHost’ | select Name,MaxEvcMode

Virtual Machine

Virtual machines typically inherit their EVC mode from the host (and respectively the cluster) on which they are running. There are two exceptions to this. Both of them have impact on the vMotion compatibility of the VM. The first one is when the CPUID mask of the VM is set explicitly and it overrides the current EVC mode for that particular VM. Although possible, it is unlikely that you will use it in a vMotion related scenario, so you do not have to bother about it. The second one is when the cluster’s EVC mode was changed while the VM was running. In this case, the cluster switches to the newer EVC mode, but the VM preserves its old EVC mode until it is powered off and powered on again. If you need to find the actual EVC mode for a specific VM, you can use :

$view = Get-VM ‘MyVM’ | Get-View



(Get-VM ‘MyVM’).Extensiondata.Summary.Runtime.MinRequiredEVCModeKey

Configuring EVC

Enable EVC on a newly created cluster

If you are building up a new cluster from scratch, the process is quite straight forward. You create the cluster, enable EVC mode, select compatible hosts and move them into the new cluster.

$cluster = New-Cluster -Name ‘MyCluster’ -Location ‘Datacenter’ -EVCMode ‘intel-westmere’

Get-VMHost ‘MyVMHost’ | Move-VMHost -Destination $cluster

The above example assumes that the host is not already part of another cluster. Otherwise, you will first have to move it out of the original cluster before adding it to the new one. This example also assumes that the selected host is compatible with the cluster’s EVC mode. In an upcoming post, I will show you how you can select hosts automatically with PowerCLI, using different compatibility checks.

Enable EVC on an existing cluster

To enable EVC on an existing cluster, you first have to make sure that hosts in the cluster support the desired EVC mode. If the cluster contains incompatible hosts, they will have to be moved out of the cluster to allow setting the particular EVC mode. Then you can use Set-Cluster to change the cluster’s EVC mode.

Set-Cluster ‘MyCluster’ -EVCMode ‘intel-westmere’

Disable EVC on a cluster

To disable EVC on a cluster, you set its EVC mode to $null.

Set-Cluster ‘ MyCluster’ -EVCMode $null

TodorThis post was created by Todor Tsvetkov…

Todor is a developer engineer in the PowerCLI team. He joined VMware and PowerCLI in late 2011 and has since taken active part in analyzing, architecting and developing various features of the product. His contribution to the latest PowerCLI release includes the Tagging and EVC functionality.

Like everyone in the PowerCLI team, he is dedicated on delivering a fully-functional, high-quality product. When not working on PowerCLI, he spends his time roller skating, playing the piano and practicing impro theater.

New Release: vSphere PowerCLI 5.5 R2


I am pleased to announce that vSphere PowerCLI 5.5 R2 has now been released and has some great new features.  In this release we take PowerCLI one step further and allow even more troubleshooting, reporting and automation of vCloud Suite products by introducing easy access to vCenter Site Recovery Manager (SRM) APIs through the core PowerCLI cmdlets.


Why wait, download the latest version today from here.

vSphere PowerCLI 5.5 Release 2 introduces the following new features and improvements, for a full list of all that has changed please check the full vSphere PowerCLI 5.5 R2 Release notes here.

Full management of the vCenter SRM Public API

Using the Connect-SRMServer and Disconnect-SRMServer you are now able to connect to vCenter SRM and access
all public APIs available, use of the $global:DefaultSrmServers object properties and methods after connection allow for access to recovery group and protection group automation, see the built in help and examples for more information and watch out for future posts with more information on this site.

Support for creating and removing Tags and Tag Categories

Enhancing the cmdlets from the previous version of PowerCLI we are now able to use PowerCLI for complete Tag management with the added New/Set/Remove Tag and TagCategory cmdlets.

Enable/Retrieve information on EVC Mode for Clusters

Adjustments to the Host and Cluster Cmdlets now allow for enabling, disabling and retrieving information for EVC Mode making automated build environments one step easier to accomplish.

Security policies for vSphere standard switch and port groups

Security policies can now be easily adjusted on vSphere standard switches and portgoups using the Get/Set-SecurityPolicy cmdelts.

Added support for PowerShell 4.0

PowerCLI can now be installed and used with the latest version of PowerShell at this time, PowerShell 4.0

Added support for IPv6

PowerCLI has now been updated to support vSphere servers configured with IPv6

Added statistical information

PowerCLI has been updated and we have added the ability to specify all supported types including clusters, datastores, etc and retrieve more statistical information via the Get-Stat and Get-StatType cmdlets.

64 bit Support

The New/Set-OSCustomizationSpec cmdlets have been updated to work in 64-bit PowerShell and no longer require running in a 32-bit PowerShell environment.

Even more updates

The above list is a high level list of the updates made to vSphere PowerCLI, for a more comprehensive list including all parameter and functional improvements, security enhancements, and deprecated features, see the vSphere PowerCLI Release Notes and the vSphere PowerCLI Change Log.

For more information on specific product features, see the VMware vSphere PowerCLI 5.5 Release 2 User’s Guide.

For more information on specific cmdlets, see the VMware vSphere PowerCLI 5.5 Release 2 Cmdlet Reference.

Download and Install PowerCLI 5.5 Release 2 today from here.

New Book: Learning PowerCLI

Everyone I meet sees the time that PowerCLI can save you by automating your day to day tasks, easily creating reports, troubleshooting your environment and much more but to use PowerCLI you first need to take the time to learn it, this can be achieved in a variety of methods but still the most popular is reading a book and putting it into practice.

If you are the reading kind of person then make sure you check out the existing PowerCLI Library of books:


Learning PowerCLI

There is a new book now available with the latest up to date information, it was written specifically with the vSphere Admin in mind and shows how you can easily get started using PowerCLI.  The book was written by community member Robert van den Nieuwendijk and published by PACKT.

The book is available in all good book stores and online book retailers such as with Amazon here.  Whats more you can take a look inside the book to see if its for you here.

What you will learn from this book

    • Download and install PowerCLI
    • Add hosts to VMware vCenter Server
    • Configure vSphere Auto Deploy
    • Use the esxcli command from PowerCLI
    • Create OS Customization Specs
    • Monitor virtual machine performance
    • Configure distributed virtual switches and storage I/O Control
    • Enable VM and Application Monitoring
    • Manage licenses for multiple hosts to migrate them easily
    • Configure an alarm to monitor your networks virtual machines
    • Generate a good-looking HTML report in no time

Win a copy

PACKT and Robert were kind enough to give VMware 5 copies of the book to give away here, in order to win a copy all you need to do is add a comment to this site (make sure you include your email address) telling us why you need to learn PowerCLI.

Entries will be judged by Robert and chosen by March 14th 2014, once chosen you will receive an email with a link to receive your copy of the book.

Good Luck.

Introduction to PowerCLI

Here at VMware we still get questions from people who are starting out with PowerCLI,

To make sure everyone is aware of the power that is available to system administrators in PowerCLI we wanted to create the below introduction which answers some of the frequent questions we receive when people start out on their journey to manage VMware platforms with the command line interface and provide automation to the Software Defined Data Center.

Using Tags with PowerCLI

The Tagging feature was introduced in vCenter Server 5.1 where custom defined tags can be categorized and added to any of your inventory objects in your environment.

Tags can be quickly searched on and retrieved quickly. Multiple unique tags can be used on the same inventory object creating granular metadata that can easily be grouped and search on.

As an example this is helpful for looking for all VMs tagged against a particular project or placing all departmental objects into groups, IE HR requiring not just there VMs but networking and datastores used as well, This all benefits the administrator by simplifying management and making information more easily available.


Continue reading

VSAN and vSphere Flash Read Cache cmdlets

Today a new VMware fling has been released, and it’s fantastic!  By now I am sure you have probably heard all the buzz from VMworld and with the 5.5 release and announced betas.  Two of the most talked about technologies are vSphere Flash Read Cache (vFRC) released in the new vSphere 5.5 version and also VSAN which was announced as a beta.

Today a new VMware fling was added to the site called “PowerCLI Extensionshere which allows you to use both VSAN and vFRC from PowerCLI, this gives you the added cmdlets needed in your PowerCLI session to automate two of the latest and greatest features from VMware.

Continue reading

Opening the Virtual Machine Remote Console through PowerCLI

With the 5.5 R1 release PowerCLI got even better. With the introduction of the new Open-VMConsoleWindow cmdlet you can access the virtual machine console of both vCenter Server and vCloud Director virtual machines. To open a virtual machine console window, simply pass a powered-on virtual machine to the Open-VMConsoleWindow cmdlet:

Get-VM “Win2k3” | Open-VMConsoleWindow

As a result, the cmdlet opens a Web page containing the virtual machine remote console: Continue reading

PowerCLI Session at VMworld 2013 Barcelona

Following the amazing sessions at VMworld San Francisco and knowing that PowerCLI took the top spot from the VMworld sessions I wanted to again give you the information you need for VMworld Barcelona so you don’t miss out on the awesome PowerCLI content available.

The Session Builder is live on the VMworld siteand I thought it might be valuable to the PowerCLI fans out there to know which sessions and interesting PowerCLI related topics are out there and what is available to attend.

Whilst PowerCLI is mentioned in many sessions these are the hard hitting PowerCLI sessions which you will want to attend to get the latest and greatest information. I also know that a lot of the sessions have been changed and enhanced to include different content from the VMworld San Francisco sessions.

You may have also noticed that not much of the information from VMworld around PowerCLI has been blogged yet, after VMworld Barcelona you will start to see more of this information and some great videos and examples.


Continue reading