Using vCenter tags with PowerCLI

I was recently introduced to some practical usage of vCenter tags. I used tags to build a fairly easy and dynamic set of sources for Veeam backup jobs, but before I get into that, I want to explain tags a little bit for those who are not familiar with them.

Tags are something that are pretty easy to understand conceptually. You create a category which contains a few tags. An object can receive one or multiple tags from a given category. Tags are managed by vCenter, not by vSphere, so require a license that provides vCenter for management. That’s a pretty simple explanation and list of requirements.

A Tag Category has a collection of Tags available within it. If the Category is “single cardinality”, it means that an object can only be assigned one tag in the category. This might be good for a category associated with ownership or recovery point objective (RPO). A Category can also be “multiple cardinality”, where a single object can be assigned multiple tags in a category. This would be helpful to associate applications with a VM, or a list of support teams that need notified if there is a planned impact or outage.

I’m going to show you how to manage Tags and Tag Categories with PowerCLI (Specifically with the PowerShell ISE and a profile to load PowerCLI), but you can manually create and manage them through the vSphere Web Client, under the Tags item on the left hand menu. You can create and delete and rename tags and categories there all day long, and you can right click on an object almost anywhere else and select Edit Tags to edit the assigned tags on it. When you view most objects, you’ll see an area in the Summary tab labeled Tags that will display and let you manage assignments.

vCenter Tags fig 1vCenter Tags fig 2

Let’s look at how to automate this with PowerCLI. Don’t forget to Connect-VIServer before continuing. Use the cmdlets *-TagCategory, *-Tag, and *-TagAssignment to manage Categories, Tags, and the assignment of tags to objects, respectively. We start by creating a category using New-TagCategory. This accepts the parameters Name*, Cardinality, Description, EntityType, and Server. A new tag is created with New-Tag, as you’d expect, with parameters Category*, Name*, Description, and Server. Asterisks denote required parameters. Both accept the optional Confirm and WhatIf arguments, the latter of which is extremely helpful while you plan out your tag schemes.

As an example, let’s create an Ownership tag category. This will be a single cardinality for most, as most objects will be owned by a single group, but if some objects share ownership, be sure to create it as a multiple-cardinality category. We can restrict the type of entities it applies to with a comma separated list of any of the valid types: Cluster, Datacenter, Datastore, DatastoreCluster, DistributedPortGroup, DistributedSwitch, Folder, ResourcePool, VApp, VirtualPortGroup, VirtualMachine, VM, VMHost (you can see this list any time by reading the New-TagCategory help pages). Many can probably restrict this to VMs and maybe Datastores, as everything else is likely owned by the same single team. WhatIf is helpful to make sure we have the syntax we want before we apply it. We can put these values into the Command add-on and click Insert to see what the PowerCLI looks like:

vCenter Tags fig 3

C:\> New-TagCategory -Name Ownership -Cardinality Single -Description "Group ownership for VMs" -EntityType VirtualMachine -WhatIf

Select New-Tag in the command add-on and add a tag for a group called Development in the new category, then click Insert:

vCenter Tags fig 4

C:\> New-Tag -Category Ownership -Name Development -Description "We put the Dev in DevOps" -WhatIf

You can now create a script with a few more groups, copy and pasting the above line as a start, and plan out your tag scheme:

vCenter Tags fig 5

Run the commands (F5 in ISE) and make sure there are no errors, but unfortunately there will be:

C:\> New-TagCategory -Name Ownership -Cardinality Single -Description "Group ownership for VMs" -EntityType VirtualMachine -WhatIf
New-Tag -Category Ownership -Name Development -Description "We put the Dev in DevOps" -WhatIf
New-Tag -Category Ownership -Name Operations -Description "We put the Ops in DevOps" -WhatIf
New-Tag -Category Ownership -Name Sales -Description "We sell what doesn't exist" -WhatIf
New-Tag -Category Ownership -Name Financial -Description "We make sure your paycheck shows up" -WhatIf

What if: Create tag category 'Ownership' on server 'vcsa'
New-Tag : 6/27/2016 4:16:02 PM    New-Tag        Could not find TagCategory with name 'Ownership'.    
At line:2 char:1
+ New-Tag -Category Ownership -Name Development -Description "We put the Dev in De ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Unfortunately, each command in WhatIf mode is run without knowledge of the previous or following statements, so the first New-Tag statement is unaware that a new tag category would have been created. Remove the WhatIf from the first line and run it again:

C:\> New-TagCategory -Name Ownership -Cardinality Single -Description "Group ownership for VMs" -EntityType VirtualMachine
New-Tag -Category Ownership -Name Development -Description "We put the Dev in DevOps" -WhatIf
New-Tag -Category Ownership -Name Operations -Description "We put the Ops in DevOps" -WhatIf
New-Tag -Category Ownership -Name Sales -Description "We sell what doesn't exist" -WhatIf
New-Tag -Category Ownership -Name Financial -Description "We make sure your paycheck shows up" -WhatIf


Name                                     Cardinality Description                                                        
----                                     ----------- -----------                                                        
Ownership                                Single      Group ownership for VMs                                            
What if: Create tag 'Development' in category 'Ownership'
What if: Create tag 'Operations' in category 'Ownership'
What if: Create tag 'Sales' in category 'Ownership'
What if: Create tag 'Financial' in category 'Ownership'

You can delete or edit the Tags and Categories using Remove-TagCategory, Remove-Tag, SetTagCategory, and Set-Tag. These cmdlets use mostly the same parameters; use the Command Add-On or Get-Help for more details. You can inspect the Tags and Categories that exist with Get-Tag and Get-TagCategory.

C:\> Set-TagCategory -Category Ownership -Description "Organizational ownership for VMs"

Name                                     Cardinality Description
----                                     ----------- -----------
Ownership                                Single      Organizational ownership for VMs



C:\> Get-TagCategory

Name                                     Cardinality Description
----                                     ----------- -----------
Ownership                                Single      Organizational ownership for VMs

I recommend saving your Tag scripts in version control, so you can recreate or adjust them as needed. Next time, we’ll look at how to assign tags to objects in order to solve a specific problem: backups!

2 thoughts on “Using vCenter tags with PowerCLI

  1. Pingback: Tag-based Veeam Backups | rnelson0
  2. Pingback: Newsletter: July 1, 2016 | Notes from MWhite

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s