Home > Blogs > VMware PowerCLI Blog


New Community Module for Tag Management

vSphere tags, in my opinion, are one the unsung heroes when it comes to VMware environment management. They’re extremely versatile. They can be used as labels. They can be used to group similar objects and/or multiple object types together. They can be used to apply policies. There are third party products also using them. I’ve seen lots of companies use them in lots of creative ways. However, automating their usage can be slow in some environments and not available at all in larger environments.

There’s a new module in the PowerCLI Community Repository to help against some of those issues. This new module, named VMware.Community.CISTag, makes use of the vSphere REST API to manage tags in a more performant manner.

The VMware.Community.CISTag module includes the following advanced functions:

Function Name Synopsis
Get-CISTag Gathers tag information from the CIS REST API endpoint
Get-CISTagCategory Gathers tag category information from the CIS REST API endpoint
Get-CISTagAssignment Displays a list of the tag assignments from the CIS REST API endpoint
New-CISTag Creates a new tag from the CIS REST API endpoint
New-CISTagCategory Creates a new tag category from the CIS REST API endpoint
New-CISTagAssignment Creates new tag assignments from the CIS REST API endpoint
Remove-CISTag Removes a tag from the CIS REST API endpoint
Remove-CISTagCategory Removes tag category information from the CIS REST API endpoint
Remove-CISTagAssignment Removes tag assignments from the CIS REST API endpoint

There are also some requirements that are needed in order for this module to work:

  • vCenter 6.0 or newer
  • PowerCLI 6.5.3 or newer
  • Active vCenter CIS service connection, using Connect-CISServer
  • Preferred: Active vCenter connection, using Connect-VIServer

Let’s take a quick look at how to get started using this module.

Accessing the Module

There are a couple ways to get access to this great module, all of which go through the PowerCLI Community Repository. One of the easiest ways is to load up the repository’s page, click on the green ‘Clone or download’ button, then clicking on ‘Download ZIP’. This downloads the entire contents of the repository to your local system.

Download PowerCLI Community Repository to Local System

Once the download is complete, unzip the files and browse to the ‘Modules’ directory. We are now going to copy the VMware.Community.CISTag folder and paste it in one of the directories that are listed in the PSModulePath variable. Doing this allows the module to be available for automatic importing by your PowerShell session!

By default, the PSModulePath variable contains the following directories:

  • $home\Documents\WindowsPowerShell\Modules
  • $pshome\Modules

In my environment, I have placed the module in the first of the above options. This is also where my PowerCLI modules are available.

Module Overview

The functions are written in a very similar format to the existing PowerCLI Tag cmdlets. If you’ve ever used the existing tag cmdlets, these operate in a very similar fashion and offer a very similar response. However, there are some changes that you should be aware of. The PowerCLI Tag cmdlets generally work with objects, whereas these functions work with names or IDs. This means you should test these new functions thoroughly before updating any existing scripts and/or workflows. Making use of Get-Help will greatly aide in the transition.

Overall, I noticed some good performance increases as well.

Example: Comparing an environment with 400 tags assigned, saw an improvement of roughly 25%
Performance test of listing tag assignments

There are some other features that have been added which can be used to achieve even more performance. The first, by using an object’s ID whenever possible. Most of the functions also feature TagId and ObjectId which can be referenced instead of the name parameters. This helps by cutting down on the amount of additional calls which are being made to translate a name into an ID value.

The second way to see even more performance improvement is through the usage of bulk actions. This applies specifically to the TagAssignment functions. The underlying API method allows multiple tags to be assigned or removed from a single object or a single tag can be assigned or removed from multiple objects. Therefore the New-CISTagAssignment and Remove-CISTagAssignment functions accept strings or arrays for Tag or Entity properties. There’s also the ability to further speed up the process by using object IDs too.

Example: Comparing the difference between the bulk assignment of a single tag against multiple VMs. Top example is name based, the bottom example is ID based.
Bulk action performance results

The last big note on improvements for this module, I have yet to run into any timeout issues, maximum results errors, and so forth.

Example: Comparing an environment with 1400 tags assigned, where the Get-TagAssignment cmdlet fails while the Get-CISTagAssignment succeeds
Example comparison with 1400 tags assigned

Summary

The CISTag module is a great new resource for anyone automating tag usage within their vSphere environment. By switching to the tagging methods available in the REST API, we’ve seen performance improvements, the ability to overcome timeout errors, and more!

Head out to the PowerCLI Community Repository, download it, and let us know in the comments how you’re putting it to use in your environment!

This entry was posted in Tags and tagged , , , on by .
Kyle Ruddy

About Kyle Ruddy

Kyle Ruddy is a Senior Technical Marketing Architect working for VMware R&D in the Cloud Platform Business Unit. Kyle currently focuses on vSphere and VMware Cloud on AWS automation and the associated automation frameworks including all things API, CLI, and SDK. Kyle is also a Microsoft MVP and long-term vExpert whom can be found blogging on VMware blogs, http://blogs.vmware.com/vSphere and http://blogs.vmware.com/PowerCLI, and his personal blog, https://www.kmruddy.com. His Twitter: @kmruddy

One thought on “New Community Module for Tag Management

  1. Pingback: New Community Module for Tag Management – VMPRO.AT – all about virtualization

Leave a Reply

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

*