Editing VM Annotation Notes via VMware vSphere PowerCLI
Yesterday, a few of my fellow co-workers approached me with a problem. They asked if I would be interested in figuring out a way to update the Notes: field within the annotations section on the summary tab of each VM we have in our server environment.
For those of you unfamiliar with VM Annotations, its a simple box that looks like this:
Pretty interesting, right?
Well, it turns out that annotations are in fact very helpful. Their purpose is to display useful information about the specific VM selected. vCenter provides an easy to use GUI for manually adding custom attributes, or fields, to the annotations box. For instance, it’s usually helpful to at least create a “Description” and “Contact” entry specifying an overview of what the server is/does and to identify the admin for each VM. Of course, more categories can be added as needed.
We are currently modifying the naming convention of our servers. This is being done to make the admin’s lives a bit simpler when browsing through our ever growing server environment. Another reason is to take advantage of the Search feature within vCenter. The whole thought process is that a well named server can be easily found via the Search bar. Brilliant. However, there is one major flaw (in my opinion) related to searching within vCenter. Remember how I said that annotations were useful in providing key information to the admins? Well, searching in vCenter doesn’t actually search (to my knowledge) any custom attributes or the useful information they contain! Interestingly though, the Notes: field is searchable. Hopefully now you can begin to see the origins of our problem. All of the categories containing descriptions, admins, priority levels, etc. that we had created custom attributes for were somewhat useless.
So, back to my task. Getting the information from the custom attributes entered into the Notes: section was the goal. This wasn’t a high priority job, but I was told if I had any free time, it’d be nice to get done. With roughly 200 VMs in our environment, it would be a long, long day, if I were to manually copy and paste the text. I knew there had to be a way to script this.. but I didn’t know where to start.
Enter PowerCLI, a plugin for PowerShell that enables scripting for vCenter. In some brief searching online, I found many forum posts, blog posts, and VMware KB topics highlighting some advanced scripting features within vCenter that are offered through PowerCLI (I hope to cover PowerCLI in more detail in future posts, for now we’ll get back to this one). However, all I wanted to do was modify some annotations.
I began to narrow my searches and came across a few articles, including this site: http://www.cassese.net/?p=34
I found the information to be very useful, but it only covered scripting entries for the custom attributes. Nothing about the Notes: field.
I kept searching.. and searching.. and after an hour and a half, I had two sources that shared a common characteristic.
The first source: http://communities.vmware.com/thread/195115
A single post on the VMware forums (out of the many I found) seemed to address the same goal as myself. These two lines of code caught my eye:
$vmcSpec.config = New-Object VMware.Vim.VirtualMachineConfigSpec
$vmcSpec.config.annotation = “whatever textyou want in the notes field”
There it was! All I had to do was create a new VirtualMachineConfigSpec object. Now I had to figure out how to do that.
Luckily the second source held the answer: http://blogs.vmware.com/vipowershell/2008/04/index.html
Granted, this code was for changing CPU and memory allocations for every VM, but it had the basic framework I needed. Most importantly, it showed me how to pipe the current VM into a VirtualMachineConfigSpec through “Get-View $_.ID” and it illustrated a very important concept: Re-configuring the VM manually with “Get-View($_.ReconfigVM_Task($spec))”
I had the pieces of code required, now I just had to modify them to fit my needs.
This is the final script I came up with, albeit I hope to modify it somewhat more (csv file input for starters), it’s functional nonetheless.
# Input array, includes all VM names within vCenter you wish to edit.
$vms = "vm1","vm2";
# Loop through all VMs within vCenter
ForEach ($vmname in $vms) {
# Create variables for the current VM and its "Contact" and "Description" which are custom attribute fields.
$vm = Get-VM -Name $vmname;
$contact = $vm | Get-Annotation -CustomAttribute Contact;
$description = $vm | Get-Annotation -CustomAttribute Description;
$vm | %{Get-View $_.ID} | % {$spec = New-Object VMware.Vim.VirtualMachineConfigSpec;
# Edit the annotation notes field
$spec.Annotation = ""+$contact.name+":`t"+$contact.value+"`n`n"+$description.name+": "+$description.value;
# Re-configure the current VM to apply changes
Get-View($_.ReconfigVM_Task($spec))}
}
###########################################################################
Quick Update: I posted my script on the VMware PowerCLI forums,http://communities.vmware.com/message/1787432#1787432, and LucD was kind enough to suggest using Set-VM -Description as a simpler way of editing the Notes: field. I did and it turns out this method was much easier. The new code is below.
Updated Code:
# Input array, includes all VM names within vCenter you wish to edit.
$vms = "vm1","vm2";
# Loop through all VMs within vCenter
ForEach ($vmname in $vms)
{
# Create variables for the current VM and its "Contact" and "Description" which are custom attribute fields.
# Also create a string $note to use with Set-VM -Description
$vm = Get-VM -Name $vmname;
$contact = $vm | Get-Annotation -CustomAttribute User;
$description = $vm | Get-Annotation -CustomAttribute Description;
$note = $contact.name+":`t"+$contact.value+"`n`n"+$description.name+":`t"+$description.value;
Set-VM -VM $vm -Description $note -Confirm:$false;
}
For more information on PowerCLI, the VMware blog provides a good intro and installation guide here: http://blogs.vmware.com/vipowershell/2011/06/back-to-basics-part-1-installing-powercli.html
Also, once installed, make sure to read the “vSphere PowerCLI Admin Guide”, it covers a lot of helpful topics for beginners. The ‘vSphere PowerCLI Cmdlets Reference’ that is installed with PowerCLI is also a great source and easier to search than the web-based version.
With that said, I hope this will assist someone else who may be wondering how to edit the annotation notes field through a script.
Thanks for reading!
7 months ago • 24 notes
