• Skip to primary navigation
  • Skip to content
  • Skip to primary sidebar

virtuallyGhetto

  • About
  • Privacy
  • Automation
    • VMware Kickstart
    • VMware API/SDK/CLI
    • VMware vMA/VIMA
    • VMware OVF / OVFTOOL
  • Apple Mac
  • Nested Virtualization
  • VCSA
  • VSAN

tag

Applying Custom Attributes beyond just Host & Virtual Machine Objects

03/09/2016 by William Lam 4 Comments

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.

applying-custom-feilds-beyond-hosts-and-vms-0
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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
$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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 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.

applying-custom-feilds-beyond-hosts-and-vms-1
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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 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!

applying-custom-feilds-beyond-hosts-and-vms-2
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.

Share this...
  • Twitter
  • Facebook
  • Linkedin
  • Reddit
  • Pinterest

Filed Under: Automation, vSphere Tagged With: custom attributes, metadata, powercli, tag, tagging

How To Add A Tag (Log prefix) To Syslog Entries

05/07/2013 by William Lam 2 Comments

Last year I wrote an article on how to forward vCenter Server logs to a remote syslog server using the built in syslog-ng client in the VCSA. A few weeks back, I received an interesting email from Michael White sharing details about adding a "tag" or more specifically, adding a string prefix to each syslog entry being forwarded. This was interesting as it enables a user to easily search for a specific log entry based on a "tag" and comes really in handy when you have multiple log sources being forwarded from the same host. An example of this would be the various logs from a vCenter Server such as vpxd, vws, inventoryservice, etc. which all have their own individual logs coming from the same host.

Within the Syslog-ng client configuration, you can specify the log_prefix() option and the string you wish to prefix a given log source. The tag has a specific syntax that must contain a : (colon) and a whitespace after the string (e.g. "VC_APP: ").

Using the vCenter Server as example, we could add the following tags:
After restarting the syslog-ng client for the changes to going into effect, you can head over to your syslog server to view the updated syslog entries. In the screenshot below, we can see we have log sources from both our VC_APP (vpxd.log) and VC_IS (ds.log) entries as specified in our syslog-ng client configurations.

Note: For newer versions of syslog-ng, program_override() is used instead of log_prefix(). The syntax for that would be program_override("VC_APP").

I want to thank Michael for sharing this cool tidbit!

Share this...
  • Twitter
  • Facebook
  • Linkedin
  • Reddit
  • Pinterest

Filed Under: Uncategorized Tagged With: syslog, tag, vcsa

vSphere Tagging Feature Not So Invisible

06/08/2011 by William Lam 8 Comments

This evening I was reading a new blog post Tagging: An Invisible Feature in vSphere by Steve Jin in which he describes a hidden vSphere feature for tagging particular managed entities in your vSphere environment. The main consumer of this hidden feature is primarily VMware and it provides a level of meta data tagging to denote the importance of an entity. These tags are used in workflows in various vSphere products such as vCenter Server, vCenter Update Manager and View to just name a few.

Here is a screenshot of a VM entity using the vSphere MOB and as you can see from the tags, VMware can identify that this particular VM is running both vCenter Server and vCenter Update Manager.

If you have a VM that is a View Replica/Linked Clone, you may see these tags associated with the VM:

SYSTEM/COM.VMWARE.SIM.SVIMANAGEDOBJECT
SYSTEM/COM.VMWARE.VIM.SVIMANAGEDOBJECT

This feature can be really useful to allow users to tag particular objects in their environment of importance and easily correlate/integrate with a provisioning system and/or CMDB without having to resort to a separate database to store the meta data. You might say that custom fields exists today that can provide the same level of functionality, but they are actually pretty limited in scope. It only allows you to create custom attributes at a global vCenter level, host and virtual machine but not all managed objects such as Datastore, Networks, Resource Pool, etc.

So what if you wanted to create your own custom tags? Since these are hidden methods from VMware and they are not exposed through the public vSphere API, how might we access it? I spent a few minutes of digging and I was able to identify the two methods that pertained to tag management in the vSphere API:

addTag - Adds a tag to a managed entity
removeTag - Removes a tag to a managed entity

You can access both of these methods using the vSphere MOB as none of the official vSphere SDKs have these methods implemented. These methods are only supported when connecting to vCenter Server and are not exposed at an ESX(i) level.

In this example, I will create a custom tag at the Datacenter level called "WWW.VIRTUALLYGHETTO.COM"

Here is the path to a Datacenter object using the vSphere MOB:

If we scroll down on the page, you will notice a property called "tag" and as you can see in the screenshot below, no tags have been defined:

I will now craft the URL to the "addTag" method using the Datacenter as a point of reference:

https://reflex.primp-industries.com/mob/?moid=datacenter-1246&method=addTag

As you can see the method accepts an array of tags which can be defined within the section. All tags MUST begin with "SYSTEM/" and then a unique string following, in our example I used "SYSTEM/WWW.VIRTUALLYGHETTO.COM". Once you have created your tag, you will then click on the "Invoke Method" to add the tag. Since this method does not return anything, the return result is void.

Now if we go back to the Datacenter page and refresh the page, you should see the new tag that was just created:

To delete a tag, you will generate the same URL but replace "add" with "remove":

https://reflex.primp-industries.com/mob/?moid=datacenter-1246&method=removeTag

You will again fill in the tags to be removed and then click on "Invoke Method":

As you can see, you now have the power to create your own tags on various managed entities in your vSphere environment. If you want to automate this through a script or command line, you can create simple HTTP POST operations to the vSphere MOB or create the appropriate interface methods to the SDK bindings to support these hidden methods. I'll leave the latter as an exercise for the readers.

Share this...
  • Twitter
  • Facebook
  • Linkedin
  • Reddit
  • Pinterest

Filed Under: Uncategorized Tagged With: api, tag, vSphere

Primary Sidebar

Author

William Lam is a Staff Solutions Architect working in the VMware Cloud on AWS team within the Cloud Platform Business Unit (CPBU) at VMware. He focuses on Automation, Integration and Operation of the VMware Software Defined Datacenter (SDDC).

  • GitHub
  • Google+
  • LinkedIn
  • RSS
  • Twitter

Sponsors

Privacy & Cookies: This site uses cookies. By continuing to use this website, you agree to their use.
To find out more, including how to control cookies, see here: Cookie Policy