Reporting Tags

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.


In PowerCLI 5.5 R1 we introduced some cmdlets for working with tag assignments and easily allowing multiple inventory objects to be tagged or removed from a tag in an automated fashion.

Tag Cmdlets

An initial discovery shows 4 new tag cmdlets to work with inventory objects, but don’t forget that you can also use some of the existing cmdlets with tag information as well, such as Get-VM –Tag “Gold”.



These cmdlets now have tag parameter

The following example returns all VMs with a tag of “Gold”.

Get-VM –Tag Gold

The following example returns all VMs with a tag of “Gold”.


The following example returns all tags named “MyTag”.

Get-Tag -Name MyTag

The following example returns all tags from the “MyCategory1” and “MyCategory2” categories, named “MyTag”.

Get-Tag -Category MyCategory1, MyCategory2 -Name MyTag


The following example retrieves all tag assignments for the $datastore entity that have tags from the “MyCategory” category.

$myDatastore = Get-DataStore MyDatastore

Get-TagAssignment -Entity $datastore -Category MyCategory


The following example can be used to assign the “MyTag” tag to all virtual machines whose name contains the “*myvm*” wildcard pattern.

$myTag = Get-Tag MyTag

$myVM = Get-VM ‘*myvm*’

New-TagAssignment -Tag $myTag -Entity $myVM


The following example removes all connections to tags from the specified virtual machine entity.

$myVM = Get-VM myvm

$myTagAssignment = Get-TagAssignment $myVM

Remove-TagAssignment $myTagAssignment

See them in action

In the below video we show how to use these cmdlets to easily tag some virtual machines and retrieve tag information for a number of virtual machines with PowerCLI.



27 comments have been added so far

  1. Hi alan,

    nice stuff.

    question just to clarify:
    Are tags are not stored in the vCenter Database. What is the best way to back them up??


  2. New-TagAssignment : Cannot convert ‘System.Object[]’ to the type ‘VMware.VimAutomation.Sdk.Types.V1.VIObjectCore’ required by param
    eter ‘Entity’. Specified method is not supported.
    + New-TagAssignment -Tag $myTag -Entity <<<< $myVM
    + CategoryInfo : InvalidArgument: (:) [New-TagAssignment], ParameterBindingException
    + FullyQualifiedErrorId : CannotConvertArgument,VMware.VimAutomation.ViCore.Cmdlets.Commands.Tagging.NewTagAssignment

    when trying to execute New-TagAssignment -Tag $myTag -Entity $myVM

    any idea why?

  3. Hi Alan
    This is very helpful information on the powercli but have been trying to figure out how to provide this information to users from within the vsphere web client.
    When listing all the virtual machines under related objects within a datacenter and adding columns, you can still only add the columns from the old custom attributes which has been migrated to Tags.
    Wonder if you seen anything within web client before to show the tag associations and where assigned.

  4. When will we see the ability to create, delete, and edit categories and tags using PowerCLI? We have multiple farms with thousands of VMs and we leverage automation wherever possible. One particular custom category I would like to create or modify tags in is called “Application Support Team or Queue”. The data for the tags comes from an external source. We currently populate an attribute with this data, but customers using the WEB client can not see attribute(s). Creating, deleting, and editing categories and tags is currently not possible using PowerCLI. We also have an attribute called “Created On” that shows the VM creation date that just does not seem to fit into tags very well unless I want thousands of them. We are forced to dump all types of information into the notes field for our WEB users, making it difficult to report on and maintain.

    Is there any way to stop the web converter from creating its own description (Besides changing each entry manually)?
    I do not like seeing:
    Migrated from custom attribute:Application Support Team or Queue
    Migrated from custom attribute:Application Support Team or Queue (1)
    Migrated from custom attribute:Application Support Team or Queue (2)
    I want them blank.

    The transition from attributes to tags has not been very graceful. 🙁

  5. My only blog are the readings for which they cares about above his life. You must make more thoughts. Thank you! The guy flipped around the mega tech blast while they must yell which they must be smart.

  6. below code use CSV file to update VM’s tag
    import-csv D:\XXX.csv | ForEach-Object {
    $vmName=Get-VM $
    New-TagAssignment -Tag $_.tag -Entity $vmName

  7. Tags are a wonderful idea.. however when you do run a simple “Get-TagAssignment -Entity you get a return like this:
    Tag Entity
    — ——
    / VMNAME CustomAttribute#1 CustomAttribute#2

    and depending the custom attribute field name.. it could be before the VMNAME, this making what should be a simple script or one-liner a pain because of the searching. is there any way to get a simple dump out with powercli of the VMname and the tags that have been assigned to that VM?

  8. Good blog .. just writing a set-tagassignment function to replace a specific tag with a different one and I am struggling to see a way of removing a specific tag.

    There seems to be a way of removing all the tags from a VM or all tags in a specific category from a VM but no way of removing a specific tag from a VM

    Any help would be appreciated

  9. i have BDP as tag name which i crated under tag category DEV ( aka development ) & PROD ( production ).
    now when i have to assgin VM’s i get an error as its finding duplicate tag names. how do i resolve this

  10. Hey there, I believe the example with the “Get-TagAssignment” example is wrong.

    It says:
    $myDatastore = Get-DataStore MyDatastore
    Get-TagAssignment -Entity $datastore -Category MyCategory

    The factual request will look for the $datastore variable but $myDatastore is supposed to be used, isn’t it?

Leave a Reply

Your email address will not be published. Required fields are marked *