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.
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%
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.
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
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!
