WilliamLam.com

I recently came to learn about a neat little tidbit from one of my readers, Ziad, regarding vSphere Custom Attributes. I had been a long time user of Custom Attributes when I was a customer and heavily used it in-conjunction with Automation. This is how many of our customers leveraged this capability, especially around provisioning and reporting use cases. Custom Attributes allows you to specify custom "keys" associated with either a Virtual Machine or an ESXi host object. Once these keys have been created, you can then assign object-specific metadata "values" to these objects. An example would be a Custom Attribute called "Application Owner" and for VM1 I can have a value of "Duncan Epping" and for VM2 I can have a value of "Alan Renouf".

Custom Attributes can be created using either the vSphere API or from the vSphere C# Client (currently not possible using the vSphere Web Client). The UI has already restricted Custom Attributes to either a Host, Virtual Machine or Global which means it applies to both objects as shown in the screenshot below. This has always been my understanding of how Custom Attributes work and has also been documented as such.

Well, it turns out, this "restriction" was only a UI restriction. The actual Custom Attributes feature can actually be applied across variety of vSphere Objects and not just limited to Hosts and Virtual Machines when using the vSphere API. If we look at the Custom Attributes API which uses the customFieldsManager and specifically the AddCustomFieldDef() method which is used to create new custom fields. We can see that the moType property can accept any of the supported vSphere Objects such as the following:

• ClusterComputeResource (Multi-ESXi host Cluster)
• ComputeResource (Single ESXi host Cluster)
• Datacenter
• Datastore
• DistributedVirtualSwitch
• Folder
• HostSystem
• Network
• ResourcePool
• StoragePod (Datastore Cluster)
• VirtualApp
• VirtualMachine

I decided to quickly verify this by giving this a try in my lab and using PowerCLI (just one of the many options to the vSphere API) to exercise the Custom Attributes API against a Datacenter, Cluster, Datastore and Network object.

We start off by retrieving the CustomFieldsManager and then creating four new Custom Fields for each of the respective vSphere Objects that we want to associate with.

$customFieldMgr = Get-View ($global:DefaultVIServer.ExtensionData.Content.CustomFieldsManager)

# Custom Field Key names

$dcCFName = "DatacenterCF"
$clCFName = "ClusterCF"
$dsCFName = "DatastoreCF"
$netCFName = "NetworkCF"

# Create Custom Field Keys for Datacenter, Cluster, Datastore & Network objects

$customFieldMgr.AddCustomFieldDef($dcCFName,"Datacenter",$null,$null)
$customFieldMgr.AddCustomFieldDef($clCFName,"ClusterComputeResource",$null,$null)
$customFieldMgr.AddCustomFieldDef($dsCFName,"Datastore",$null,$null)
$customFieldMgr.AddCustomFieldDef($netCFName,"Network",$null,$null)

Next, we retrieve a Datacenter, Cluster, Datastore and Network object in our vSphere inventory and then call the setCustomValue() API which is used to set the value for a particular Custom Attribute that has been defined for that object.

# Set Custom Field for Datacenter, Cluster, Datastore & Network objects

$datacenterName = "Santa-Barbara"
$datacenterView = Get-View -ViewType Datacenter -Property Name -Filter @{"name"=$datacenterName}
$datacenterView.setCustomValue("$dcCFName","AB-123")

$clusterName = "Production"
$clusterView = Get-View -ViewType  ClusterComputeResource -Property Name -Filter @{"name"=$clusterName}
$clusterView.setCustomValue("$clCFName","BC-456")

$datastoreName = "datastore1"
$datastoreView = Get-View -ViewType Datastore -Property Name -Filter @{"name"=$datastoreName}
$datastoreView.setCustomValue("$dsCFName","CD-789")

$networkName = "VM Network"
$networkView = Get-View -ViewType Network -Property Name -Filter @{"name"=$networkName}
$networkView.setCustomValue("$netCFName","EF-012")

If we take a look at our vSphere Web/C# Client, we should see tasks being initiated on setting the custom value. So far, so good.

Finally, it is time to retrieve these Custom Attributes to see if they were indeed properly set. We first need to build up a hash table of the key's name, so we can easily correlate the specific Custom Attribute name with the unique key ID. Next, we can then extract the Value property which extends CustomFieldStringValue and contains both the key which we can look up from our look up table and most importantly, the value which contains the data that we had set earlier.

# Retrieve Custom Field for Datacenter, Cluster, Datastore & Network objects

# Create Custom Field & Name lookup table
# Borrowed from my buddy Alan Renouf http://www.virtu-al.net/2009/05/29/powercli-on-steroids-custom-attributes/
$customKeyLookup = @{}
$customNameLookup = @{}
$customFieldMgr.Field | % {
$customKeyLookup.Add($_.Key, $_.Name)
$customNameLookup.Add($_.Name, $_.Key)
}

# Print the Custom Fields property for each vSphere Object

$datacenterView = Get-View -ViewType Datacenter -Property Name,Value -Filter @{"name"=$datacenterName}
Write-Host "`nDatacenter:" $datacenterName "has Custom Field:" $customKeyLookup[$datacenterView.Value[0].Key] "with value:" $datacenterView.Value[0].Value "`n"

$clusterView = Get-View -ViewType  ClusterComputeResource -Property Name,Value -Filter @{"name"=$clusterName}
Write-Host "`Cluster:" $clusterName "has Custom Field:" $customKeyLookup[$clusterView.Value[0].Key] "with value:" $clusterView.Value[0].Value "`n"

$datastoreView = Get-View -ViewType Datastore -Property Name,Value -Filter @{"name"=$datastoreName}
Write-Host "`Datastore:" $datastoreName "has Custom Field:" $customKeyLookup[$datastoreView.Value[0].Key] "with value:" $datastoreView.Value[0].Value "`n"

$networkView = Get-View -ViewType Network -Property Name,Value -Filter @{"name"=$networkName}
Write-Host "`Network:" $networkName "has Custom Field:" $customKeyLookup[$networkView.Value[0].Key] "with value:" $networkView.Value[0].Value "`n"

Here is a screenshot of running the above PowerCLI code and we can see the values match up with what we had set earlier. This is pretty awesome if you ask me!

Some of you might be thinking, if Custom Attributes can be applied across different vSphere Objects, then why should I use vSphere Tags? Well, there are definitely some differences between the two today and I highly recommend you give this article a read first before continuing further. Although Custom Attributes may provide similiar behaviors to vSphere Tags, there is a lot of limitations that come with Custom Attributes. I do believe vSphere Tags is the future and when we bring vSphere Tags to parity with some of the use cases that Custom Attributes can only cover today only, it will be an even more powerful feature.

There are several major benefits to vSphere Tags over Custom Attributes. One they are multi-vCenter Server aware when joined to the same SSO Domain, which means existing Tags/Tag Categories are automatically made available versus Custom Attributes which are bounded by a single vCenter Server. vSphere Tags is also deeply integrated with VM Storage Policy and Content Library for provisioning which is lacking with Custom Attributes and require custom Automation to leverage its metadata. A single vSphere Tag can support one or more groupings to a given vSphere Object, where as Custom Attribute must be tied to a single object. Lastly, being able to globally search across various tagged vSphere Objects is trivial with vSphere Tags. For Custom Attributes, you would need to first identity the object which means you must search through all objects unless you know the one you are looking for first and then iterate through the list of Custom Attributes looking for the specific key and then finally the value. There is definitely still room for improving vSphere Tags, but I think it is definitely the more superior metadata system that customers should be looking at going forward.

One final note which I thought was interesting is that PowerCLI also provides a few cmdlets for managing Custom Attributes and it looks like they did in fact support different vSphere Object types as documented here. The only issue is that it does not cover all vSphere Objects that is possible and if you still may want to consider calling into the vSphere API from PowerCLI and by-passing the default cmdlets.